144 lines
4.8 KiB
Markdown
144 lines
4.8 KiB
Markdown
---
|
|
title: README
|
|
description: the README.md file of this project
|
|
author: slonkazoid
|
|
created_at: 2024-04-18T04:15:26+03:00
|
|
---
|
|
|
|
# bingus-blog
|
|
|
|
blazingly fast markdown blog software written in rust memory safe
|
|
|
|
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
|
|
[custom drop-ins](CUSTOM.md) for both templates and static content
|
|
- really easy to deploy (the server is one executable file)
|
|
- blazingly fast
|
|
|
|
## TODO
|
|
|
|
- [ ] blog thumbnail and favicon
|
|
- [ ] sort asc/desc
|
|
- [ ] extend syntect options
|
|
- [ ] ^ fix syntect mutex poisoning
|
|
- [ ] better error reporting and error pages
|
|
- [ ] better tracing
|
|
- [ ] replace HashMap with HashCache once i implement [this](https://github.com/wvwwvwwv/scalable-concurrent-containers/issues/139)
|
|
- [ ] make date parsing less strict
|
|
- [ ] improve home page
|
|
- [ ] multi-language support
|
|
- [x] be blazingly fast
|
|
- [x] 100+ MiB binary size
|
|
|
|
## Configuration
|
|
|
|
see [CONFIG.md](CONFIG.md)
|
|
|
|
## Building
|
|
|
|
this project uses nightly-only features.
|
|
make sure you have the nightly toolchain installed.
|
|
|
|
build the application with `cargo`:
|
|
|
|
```sh
|
|
cargo +nightly build --release
|
|
```
|
|
|
|
the executable will be located at `target/release/bingus-blog`.
|
|
|
|
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.
|
|
|
|
full example:
|
|
|
|
```md
|
|
---
|
|
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
|
|
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
|
|
- 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-18T04:15:26 # invalid (missing Z)
|
|
- 2024-04-18T04:15Z # invalid (missing seconds)
|
|
- # everything else is also invalid
|
|
```
|
|
|
|
## Non-static Routes
|
|
|
|
- `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/*`
|
|
- `GET /feed.xml`: RSS feed
|
|
|
|
## Cache
|
|
|
|
bingus-blog caches every post retrieved and keeps it permanently in cache.
|
|
there is a toggleable cleanup task that periodically sweeps the cache to
|
|
remove dead entries, but it can still get quite big.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Contributing
|
|
|
|
make sure your changes don't break firefox, chromium,text-based browsers,
|
|
and webkit support
|
|
|
|
### Feature Requests
|
|
|
|
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.
|
|
|
|
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).
|