--- 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 ## TODO - [ ] RSS - [x] finish writing this document - [x] document config - [ ] extend syntect options - [ ] general cleanup of code - [ ] make `compress.rs` not suck - [ ] better error reporting and pages - [ ] better tracing - [ ] cache cleanup task - [ ] (de)compress cache with zstd on startup/shutdown - [ ] make date parsing less strict - [ ] make date formatting better - [ ] clean up imports and require less features - [x] be blazingly fast - [x] 100+ MiB binary size ## Configuration the default configuration with comments looks like this ```toml # main settings host = "0.0.0.0" # ip to listen on port = 3000 # port to listen on title = "bingus-blog" # title of the website description = "blazingly fast markdown blog software written in rust memory safe" # description of the website posts_dir = "posts" # where posts are stored #cache_file = "..." # file to serialize the cache into on shutdown, and # to deserialize from on startup. uncomment to enable markdown_access = true # allow users to see the raw markdown of a post [render] # rendering-specific settings syntect.load_defaults = false # include default syntect themes syntect.themes_dir = "themes" # directory to include themes from syntect.theme = "Catppuccin Mocha" # theme file name (without `.tmTheme`) [precompression] # precompression settings enable = false # gzip every file in static/ on startup watch = true # keep watching and gzip files as they change ``` you don't have to copy it from here, it's generated if it doesn't exist ## Usage build the application with `cargo`: ```sh cargo build --release ``` the executable will be located at `target/release/bingus-blog`. ### Building for another architecture you can use the `--target` flag in `cargo build` for this purpose building for `aarch64-unknown-linux-musl` (for example, a Redmi 5 Plus running postmarketOS): ```sh # install the required packages to compile and link aarch64 binaries sudo pacman -S aarch64-linux-gnu-gcc export CC=aarch64-linux-gnu-gcc export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=$CC cargo build --release --target=aarch64-unknown-linux-musl ``` your executable will be located at `target//release/bingus-blog` this time. ## 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. example: ```md --- title: "README" description: "the README.md file of this project" author: "slonkazoid" created_at: 2024-04-18T04:15:26+03:00 #modified_at: ... # see above --- ``` 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:26Z # invalid (missing Z) - 2024-04-18T04:15Z # invalid (missing seconds) - # everything else is also invalid ``` ## Routes - `GET /`: index page, lists posts - `GET /posts`: returns a list of all posts with metadata in JSON format - `GET /posts/`: view a post - `GET /posts/.md`: view the raw markdown of a post - `GET /post/*`: redirects to `/posts/*`