forked from slonk/bingus-blog
update documentation
This commit is contained in:
parent
2eb14be977
commit
99e91db6aa
5 changed files with 189 additions and 106 deletions
51
BUILDING.md
Normal file
51
BUILDING.md
Normal file
|
@ -0,0 +1,51 @@
|
||||||
|
# Building bingus-blog
|
||||||
|
|
||||||
|
this guide assumes you have git and are on linux.
|
||||||
|
at the moment, compiling on windows is supported, but not _for windows_.
|
||||||
|
|
||||||
|
1. first, acquire _rust nightly_.
|
||||||
|
the recommended method is to install [rustup](https://rustup.rs/),
|
||||||
|
and use that to get _rust nightly_. choose "customize installation",
|
||||||
|
and set "default toolchain" to nightly to save time later, provided
|
||||||
|
you do not need _rust stable_ for something else
|
||||||
|
2. start your favorite terminal
|
||||||
|
3. then, download the repository: `git clone https://git.slonk.ing/slonk/bingus-blog && cd bingus-blog`
|
||||||
|
4. finally, build the application: `cargo +nightly build --release`
|
||||||
|
5. your executable is `target/release/bingus-blog`, copy it to your server and
|
||||||
|
you're done!
|
||||||
|
|
||||||
|
## Building for another architecture
|
||||||
|
|
||||||
|
you can use the `--target` flag in `cargo build` for this purpose.
|
||||||
|
examples are for Arch Linux x86_64.
|
||||||
|
|
||||||
|
here's how to compile for `aarch64-unknown-linux-gnu`
|
||||||
|
(eg. Oracle CI Free Tier ARM VPS):
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# install the required packages to compile and link aarch64 binaries
|
||||||
|
sudo pacman -S aarch64-linux-gnu-gcc
|
||||||
|
cargo +nightly build --release --target=aarch64-unknown-linux-gnu
|
||||||
|
```
|
||||||
|
|
||||||
|
your executable will be `target/aarch64-unkown-linux-gnu/release/bingus-blog`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
a more tricky example is building for `aarch64-unknown-linux-musl`
|
||||||
|
(eg. a Redmi 5 Plus running postmarketOS):
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# there is no toolchain for aarch64-unknown-linux-musl,
|
||||||
|
# so we have to repurpose the GNU toolchain. this doesn't
|
||||||
|
# work out of the box so we have to set some environment variables
|
||||||
|
sudo pacman -S aarch64-linux-gnu-gcc
|
||||||
|
export CC=aarch64-linux-gnu-gcc
|
||||||
|
export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=$CC
|
||||||
|
cargo +nightly build --release --target=aarch64-unknown-linux-musl
|
||||||
|
# the reason we had to do this is because cargo tries to use
|
||||||
|
# the same toolchain as the target's name. but we can tell it to use
|
||||||
|
# the GNU one like so.
|
||||||
|
```
|
||||||
|
|
||||||
|
your executable will be `target/aarch64-unkown-linux-musl/release/bingus-blog`.
|
61
CONFIG.md
Normal file
61
CONFIG.md
Normal file
|
@ -0,0 +1,61 @@
|
||||||
|
# Configuration
|
||||||
|
|
||||||
|
the configuration format, with defaults, is documented below:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
title = "bingus-blog" # title of the blog
|
||||||
|
# description of the blog
|
||||||
|
description = "blazingly fast markdown blog software written in rust memory safe"
|
||||||
|
markdown_access = true # allow users to see the raw markdown of a post
|
||||||
|
# endpoint: /posts/<name>.md
|
||||||
|
js_enable = true # enable javascript (required for below 2 options)
|
||||||
|
date_format = "RFC3339" # format string used to format dates in the backend
|
||||||
|
# it's highly recommended to leave this as default,
|
||||||
|
# so the date can be formatted by the browser.
|
||||||
|
# format: https://docs.rs/chrono/latest/chrono/format/strftime/index.html#specifiers
|
||||||
|
default_sort = "date" # default sorting method ("date" or "name")
|
||||||
|
#default_color = "#f5c2e7" # default embed color, optional
|
||||||
|
|
||||||
|
[rss]
|
||||||
|
enable = false # serve an rss field under /feed.xml
|
||||||
|
# this may be a bit resource intensive
|
||||||
|
link = "https://..." # public url of the blog, required if rss is enabled
|
||||||
|
|
||||||
|
[dirs]
|
||||||
|
posts = "posts" # where posts are stored
|
||||||
|
media = "media" # directory served under /media/
|
||||||
|
custom_templates = "custom/templates" # custom templates dir
|
||||||
|
custom_static = "custom/static" # custom static dir
|
||||||
|
# see CUSTOM.md for documentation
|
||||||
|
[http]
|
||||||
|
host = "0.0.0.0" # ip to listen on
|
||||||
|
port = 3000 # port to listen on
|
||||||
|
|
||||||
|
[cache]
|
||||||
|
enable = true # save metadata and rendered posts into RAM
|
||||||
|
# highly recommended, only turn off if absolutely necessary
|
||||||
|
cleanup = true # clean cache, highly recommended
|
||||||
|
#cleanup_interval = 86400000 # clean the cache regularly instead of just at startup
|
||||||
|
# uncomment to enable
|
||||||
|
persistence = true # save the cache to on shutdown and load on startup
|
||||||
|
file = "cache" # file to save the cache to
|
||||||
|
compress = true # compress the cache file
|
||||||
|
compression_level = 3 # zstd compression level, 3 is recommended
|
||||||
|
|
||||||
|
[render]
|
||||||
|
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`)
|
||||||
|
```
|
||||||
|
|
||||||
|
configuration is done in [TOML](https://toml.io/)
|
||||||
|
if an option marked "optional" is not set, it will not be initialized with
|
||||||
|
a default value
|
||||||
|
you don't have to copy the whole thing from here,
|
||||||
|
it's generated by the program if it doesn't exist
|
||||||
|
|
||||||
|
## Specifying Configuration
|
||||||
|
|
||||||
|
the configuration file is loaded from `config.toml` by default, but the path
|
||||||
|
can be overriden by setting the environment variable `BINGUS_BLOG_CONFIG`,
|
||||||
|
which will make bingus-blog try to read that file or fail and exit.
|
50
CUSTOM.md
Normal file
50
CUSTOM.md
Normal file
|
@ -0,0 +1,50 @@
|
||||||
|
# Custom Content
|
||||||
|
|
||||||
|
bingus-blog supports loading custom content such as templates and static files
|
||||||
|
at runtime from custom locations.
|
||||||
|
|
||||||
|
the configuration options `dirs.custom_templates` and `dirs.custom_static`
|
||||||
|
allow you to set where these files are loaded from.
|
||||||
|
|
||||||
|
customizing the error page, other than CSS, is not supported at this time.
|
||||||
|
|
||||||
|
## Custom Templates
|
||||||
|
|
||||||
|
custom templates are loaded from `custom/templates` by default and they are
|
||||||
|
written in [Handlebars (the rust variant)](https://crates.io/crates/handlebars)
|
||||||
|
|
||||||
|
the *custom templates directory* has a non-recursive structure:
|
||||||
|
|
||||||
|
```md
|
||||||
|
./
|
||||||
|
- index.html # ignored
|
||||||
|
- index.hbs # loaded as `index`
|
||||||
|
- post.hbs # loaded as `post`
|
||||||
|
- [NAME].hbs # loaded as `[NAME]`
|
||||||
|
- ...
|
||||||
|
```
|
||||||
|
|
||||||
|
templates will be loaded from first, the executable, then, the custom
|
||||||
|
templates path, overriding the defaults.
|
||||||
|
|
||||||
|
template changes are also processed after startup, any changed template will be
|
||||||
|
compiled and will replace the existing template in the registry, or add a
|
||||||
|
new one (though that does nothing).
|
||||||
|
if a template is deleted, the default template will be recompiled into
|
||||||
|
it's place.
|
||||||
|
note that the watcher only works if the *custom templates directory* existed
|
||||||
|
at startup. if you delete/create the directory, you must restart the program.
|
||||||
|
|
||||||
|
## Custom Static Files
|
||||||
|
|
||||||
|
GET requests to `/static` will first be checked against `dirs.custom_static`.
|
||||||
|
if the file is not found in the *custom static directory*, bingus-blog will try
|
||||||
|
to serve it from the directory embedded in the executable. this means you can
|
||||||
|
add whatever you want in the *custom static directory* and it will be served
|
||||||
|
under `/static`.
|
||||||
|
|
||||||
|
## Custom Media
|
||||||
|
|
||||||
|
the endpoint `/media` is served from `dirs.media`. no other logic or mechanism
|
||||||
|
is present.
|
||||||
|
|
131
README.md
131
README.md
|
@ -9,85 +9,37 @@ created_at: 2024-04-18T04:15:26+03:00
|
||||||
|
|
||||||
blazingly fast markdown blog software written in rust memory safe
|
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
|
## TODO
|
||||||
|
|
||||||
- [x] RSS
|
|
||||||
- [x] finish writing this document
|
|
||||||
- [x] document config
|
|
||||||
- [ ] blog thumbnail and favicon
|
- [ ] blog thumbnail and favicon
|
||||||
- [x] fix webkit dates (what.)
|
|
||||||
- [ ] sort asc/desc
|
- [ ] sort asc/desc
|
||||||
- [x] alt text for post icon
|
|
||||||
- [ ] extend syntect options
|
- [ ] extend syntect options
|
||||||
- [x] general cleanup of code
|
|
||||||
- [ ] better error reporting and error pages
|
- [ ] better error reporting and error pages
|
||||||
- [ ] better tracing
|
- [ ] better tracing
|
||||||
- [x] cache cleanup task
|
- [ ] replace HashMap with HashCache once i implement [this](https://github.com/wvwwvwwv/scalable-concurrent-containers/issues/139)
|
||||||
- [ ] ^ replace HashMap with HashCache once i implement [this](https://github.com/wvwwvwwv/scalable-concurrent-containers/issues/139)
|
|
||||||
- [x] (de)compress cache with zstd on startup/shutdown
|
|
||||||
- [ ] make date parsing less strict
|
- [ ] make date parsing less strict
|
||||||
- [x] make date formatting better
|
|
||||||
- [x] date formatting respects user timezone
|
|
||||||
- [x] clean up imports and require less features
|
|
||||||
- [ ] improve home page
|
- [ ] improve home page
|
||||||
- [x] tags
|
|
||||||
- [ ] multi-language support
|
- [ ] multi-language support
|
||||||
- [x] be blazingly fast
|
- [x] be blazingly fast
|
||||||
- [x] 100+ MiB binary size
|
- [x] 100+ MiB binary size
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
the default configuration with comments looks like this
|
see [CONFIG.md](/CONFIG.md)
|
||||||
|
|
||||||
```toml
|
## Building
|
||||||
title = "bingus-blog" # title of the blog
|
|
||||||
# description of the blog
|
|
||||||
description = "blazingly fast markdown blog software written in rust memory safe"
|
|
||||||
markdown_access = true # allow users to see the raw markdown of a post
|
|
||||||
# endpoint: /posts/<name>.md
|
|
||||||
js_enable = true # enable javascript (required for below 2 options)
|
|
||||||
date_format = "RFC3339" # format string used to format dates in the backend
|
|
||||||
# it's highly recommended to leave this as default,
|
|
||||||
# so the date can be formatted by the browser.
|
|
||||||
# format: https://docs.rs/chrono/latest/chrono/format/strftime/index.html#specifiers
|
|
||||||
default_sort = "date" # default sorting method ("date" or "name")
|
|
||||||
#default_color = "#f5c2e7" # default embed color, optional
|
|
||||||
|
|
||||||
[rss]
|
|
||||||
enable = false # serve an rss field under /feed.xml
|
|
||||||
# this may be a bit resource intensive
|
|
||||||
link = "https://..." # public url of the blog, required if rss is enabled
|
|
||||||
|
|
||||||
[dirs]
|
|
||||||
posts = "posts" # where posts are stored
|
|
||||||
media = "media" # directory served under /media/
|
|
||||||
custom_templates = "custom/templates" # custom templates dir
|
|
||||||
custom_static = "custom/static" # custom static dir
|
|
||||||
# see CUSTOM.md for documentation
|
|
||||||
[http]
|
|
||||||
host = "0.0.0.0" # ip to listen on
|
|
||||||
port = 3000 # port to listen on
|
|
||||||
|
|
||||||
[cache]
|
|
||||||
enable = true # save metadata and rendered posts into RAM
|
|
||||||
# highly recommended, only turn off if absolutely necessary
|
|
||||||
cleanup = true # clean cache, highly recommended
|
|
||||||
#cleanup_interval = 86400000 # clean the cache regularly instead of just at startup
|
|
||||||
# uncomment to enable
|
|
||||||
persistence = true # save the cache to on shutdown and load on startup
|
|
||||||
file = "cache" # file to save the cache to
|
|
||||||
compress = true # compress the cache file
|
|
||||||
compression_level = 3 # zstd compression level, 3 is recommended
|
|
||||||
|
|
||||||
[render]
|
|
||||||
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`)
|
|
||||||
```
|
|
||||||
|
|
||||||
you don't have to copy it from here, it's generated if it doesn't exist
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
this project uses nightly-only features.
|
this project uses nightly-only features.
|
||||||
make sure you have the nightly toolchain installed.
|
make sure you have the nightly toolchain installed.
|
||||||
|
@ -100,21 +52,7 @@ cargo +nightly build --release
|
||||||
|
|
||||||
the executable will be located at `target/release/bingus-blog`.
|
the executable will be located at `target/release/bingus-blog`.
|
||||||
|
|
||||||
### Building for another architecture
|
see [BUILDING.md](/BUILDING.md) for more information and detailed instructions.
|
||||||
|
|
||||||
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 +nightly build --release --target=aarch64-unknown-linux-musl
|
|
||||||
```
|
|
||||||
|
|
||||||
your executable will be located at `target/<target>/release/bingus-blog` this time.
|
|
||||||
|
|
||||||
## Writing Posts
|
## Writing Posts
|
||||||
|
|
||||||
|
@ -167,44 +105,29 @@ standard. examples of valid and invalid dates:
|
||||||
- # everything else is also invalid
|
- # everything else is also invalid
|
||||||
```
|
```
|
||||||
|
|
||||||
## Custom Content (CSS, HTML, JS)
|
## Non-static Routes
|
||||||
|
|
||||||
though you can modify the content and commit it so you still get changes from
|
|
||||||
upstream with minimal problems.
|
|
||||||
you can edit the css and js however you want but changing the html requires a
|
|
||||||
recompilation as it is made from compile-time parsed templates.
|
|
||||||
|
|
||||||
bingus-blog currently loads css files from `/static/custom`:
|
|
||||||
|
|
||||||
- `/static/custom/style.css` for all pages
|
|
||||||
- `/static/custom/post.css` for posts
|
|
||||||
- `/static/custom/error.css` for the error page
|
|
||||||
|
|
||||||
you can create a `custom` directory inside the `static_dir` you set in the
|
|
||||||
config and put the css files there.
|
|
||||||
|
|
||||||
## Routes
|
|
||||||
|
|
||||||
- `GET /`: index page, lists posts
|
- `GET /`: index page, lists posts
|
||||||
- `GET /posts`: returns a list of all posts with metadata in JSON format
|
- `GET /posts`: returns a list of all posts with metadata in JSON format
|
||||||
- `GET /posts/<name>`: view a post
|
- `GET /posts/<name>`: view a post
|
||||||
- `GET /posts/<name>.md`: view the raw markdown of a post
|
- `GET /posts/<name>.md`: view the raw markdown of a post
|
||||||
- `GET /post/*`: redirects to `/posts/*`
|
- `GET /post/*`: redirects to `/posts/*`
|
||||||
|
- `GET /feed.xml`: RSS feed
|
||||||
|
|
||||||
## Cache
|
## Cache
|
||||||
|
|
||||||
bingus-blog caches every post retrieved and keeps it permanently in cache.
|
bingus-blog caches every post retrieved and keeps it permanently in cache.
|
||||||
the only way a cache entry is removed is when it's requested and it does
|
there is a toggleable cleanup task that periodically sweeps the cache to
|
||||||
not exist in the filesystem. cache entries don't expire, but they get
|
remove dead entries, but it can still get quite big.
|
||||||
invalidated when the mtime of the markdown file changes.
|
|
||||||
|
|
||||||
if cache persistence is on, the cache is compressed & written on shutdown,
|
if cache persistence is on, the cache is (compressed &) written to disk on
|
||||||
and read & decompressed on startup. one may opt to set the cache location
|
shutdown, and read (& decompressed) on startup. one may opt to set the cache
|
||||||
to point to a tmpfs so it saves and loads really fast, but it doesn't persist
|
location to point to a tmpfs to make it save and load quickly, but not persist
|
||||||
across boots, also at the cost of even more RAM usage.
|
across reboots at the cost of more RAM usage.
|
||||||
|
|
||||||
the compression reduced a 3.21 MB file cache into 0.18 MB with almost instantly.
|
in my testing, the compression reduced a 3.21 MB cache to 0.18 MB almost
|
||||||
there is basically no good reason to not have compression on.
|
instantly. there is basically no good reason to not have compression on,
|
||||||
|
unless you have filesystem compression already of course.
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
|
|
|
@ -5,8 +5,6 @@
|
||||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||||
<title>error</title>
|
<title>error</title>
|
||||||
<link rel="stylesheet" href="/static/style.css" />
|
<link rel="stylesheet" href="/static/style.css" />
|
||||||
<link rel="stylesheet" href="/static/custom/style.css" />
|
|
||||||
<link rel="stylesheet" href="/static/custom/error.css" />
|
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
<main>
|
<main>
|
||||||
|
|
Loading…
Reference in a new issue