bingus-blog/posts
2024-04-18 04:05:52 +03:00
..
README.md initial slonkmit 2024-04-18 04:05:52 +03:00

title description author created_at
README the README.md file of this project slonkazoid 2024-04-18T04:15:26+03:00

bingus-blog

blazingly fast markdown blog software written in rust memory safe

TODO

  • RSS
  • finish writing this document
  • 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
  • be blazingly fast
  • 100+ MiB binary size

Configuration

the default configuration with comments looks like this

# 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:

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):

# 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/<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

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:

---
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 standard. examples of valid and invalid dates:

+ 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

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/*