bingus-blog/README.md

144 lines
4.8 KiB
Markdown
Raw Normal View History

2024-04-18 04:05:38 +03:00
---
2024-07-01 03:21:33 +03:00
title: README
description: the README.md file of this project
author: slonkazoid
created_at: 2024-04-18T04:15:26+03:00
2024-04-18 04:05:38 +03:00
---
2024-04-18 04:16:12 +03:00
# bingus-blog
2024-04-18 04:05:38 +03:00
blazingly fast markdown blog software written in rust memory safe
2024-08-13 16:53:39 +03:00
for bingus-blog viewers: [see original document](https://git.slonk.ing/slonk/bingus-blog)
## Features
- posts are written in markdwon and loaded at runtime, meaning you
can write posts from anywhere and sync it with the server without headache
- RSS is supported
- the look of the blog is extremely customizable, with support for
2024-08-17 10:47:48 +03:00
[custom drop-ins](CUSTOM.md) for both templates and static content
2024-08-13 16:53:39 +03:00
- really easy to deploy (the server is one executable file)
- blazingly fast
2024-04-18 04:05:38 +03:00
## TODO
2024-07-01 03:17:21 +03:00
- [ ] blog thumbnail and favicon
2024-08-01 01:03:51 +03:00
- [ ] sort asc/desc
2024-04-18 04:05:38 +03:00
- [ ] extend syntect options
2024-04-30 09:34:51 +03:00
- [ ] better error reporting and error pages
- [ ] better tracing
2024-08-13 16:53:39 +03:00
- [ ] replace HashMap with HashCache once i implement [this](https://github.com/wvwwvwwv/scalable-concurrent-containers/issues/139)
- [ ] make date parsing less strict
2024-04-30 09:34:51 +03:00
- [ ] improve home page
2024-05-02 19:23:20 +03:00
- [ ] multi-language support
2024-04-18 04:05:38 +03:00
- [x] be blazingly fast
- [x] 100+ MiB binary size
## Configuration
2024-08-17 10:47:48 +03:00
see [CONFIG.md](CONFIG.md)
2024-08-13 16:53:39 +03:00
## Building
2024-04-30 11:44:00 +03:00
this project uses nightly-only features.
make sure you have the nightly toolchain installed.
build the application with `cargo`:
```sh
2024-04-30 11:44:00 +03:00
cargo +nightly build --release
```
the executable will be located at `target/release/bingus-blog`.
2024-08-17 10:47:48 +03:00
see [BUILDING.md](BUILDING.md) for more information and detailed instructions.
## Writing Posts
posts are written in markdown. the requirements for a file to count as a post are:
1. the file must be in the root of the `posts` directory you configured
2. the file's name must end with the extension `.md`
3. the file's contents must begin with a valid [front matter](#front-matter)
this file counts as a valid post, and will show up if you just `git clone` and
`cargo r`. there is a symlink to this file from the default posts directory
## Front Matter
every post **must** begin with a **valid** front matter. else it wont be listed
in / & /posts, and when you navigate to it, you will be met with an error page.
the error page will tell you what the problem is.
2024-07-01 02:44:43 +03:00
full example:
```md
---
2024-07-01 03:21:33 +03:00
title: My first post # title of the post
description: The first post on this awesome blog! # short description of the post
author: Blubber256 # author of the post
icon: /media/first-post/icon.png # icon/thumbnail of post used in embeds
icon_alt: Picture of a computer running DOOM
2024-07-01 02:44:43 +03:00
color: "#00aacc" # color of post, also used in embeds
created_at: 2024-04-18T04:15:26+03:00 # date of writing, this is highly
# recommended if you are on a system which doesnt have btime (like musl),
# because this is fetched from file stats by default
#modified_at: ... # see above. this is also fetched from the filesystem
tags: # tags, or keywords, used in meta and also in the ui
2024-08-01 00:25:42 +03:00
- lifestyle
---
```
only first 3 fields are required. if it can't find the other 2 fields, it will
get them from filesystem metadata. if you are on musl and you omit the
`created_at` field, it will just not show up
the dates must follow the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)
standard. examples of valid and invalid dates:
```diff
+ 2024-04-18T01:15:26Z # valid
+ 2024-04-18T04:15:26+03:00 # valid (with timezone)
2024-04-20 13:10:57 +03:00
- 2024-04-18T04:15:26 # invalid (missing Z)
- 2024-04-18T04:15Z # invalid (missing seconds)
- # everything else is also invalid
```
2024-08-13 16:53:39 +03:00
## Non-static Routes
2024-08-03 10:28:01 +03:00
- `GET /`: index page, lists posts
- `GET /posts`: returns a list of all posts with metadata in JSON format
- `GET /posts/<name>`: view a post
- `GET /posts/<name>.md`: view the raw markdown of a post
- `GET /post/*`: redirects to `/posts/*`
2024-08-13 16:53:39 +03:00
- `GET /feed.xml`: RSS feed
## Cache
bingus-blog caches every post retrieved and keeps it permanently in cache.
2024-08-13 16:53:39 +03:00
there is a toggleable cleanup task that periodically sweeps the cache to
remove dead entries, but it can still get quite big.
2024-08-13 16:53:39 +03:00
if cache persistence is on, the cache is (compressed &) written to disk on
shutdown, and read (& decompressed) on startup. one may opt to set the cache
location to point to a tmpfs to make it save and load quickly, but not persist
across reboots at the cost of more RAM usage.
2024-08-13 16:53:39 +03:00
in my testing, the compression reduced a 3.21 MB cache to 0.18 MB almost
instantly. there is basically no good reason to not have compression on,
unless you have filesystem compression already of course.
2024-07-01 16:38:47 +03:00
## Contributing
2024-08-03 10:28:01 +03:00
make sure your changes don't break firefox, chromium,text-based browsers,
and webkit support
2024-07-01 16:38:47 +03:00
2024-08-03 01:13:02 +03:00
### Feature Requests
2024-08-03 10:28:01 +03:00
i want this project to be a good and usable piece of software, so i implement
feature requests provided they fit the project and it's values.
2024-08-03 01:13:02 +03:00
2024-08-03 10:28:01 +03:00
most just ping me on discord with feature requests, but if your request is
non-trivial, please create an issue [here](https://git.slonk.ing/slonk/bingus-blog/issues).