new, better version of README, more suitable for a public repo :D

2026-09-07 12:10:42 +02:00 · 2026-01-04 15:37:10 +01:00
parent 55b80dee8e
commit 7d422c23b2
1 changed files with 129 additions and 19 deletions
--- a/README.md
+++ b/README.md
@@ -1,34 +1,144 @@
-# What is this? This is a small blog app. Basically a static site generator.
-It uses cpp to create html files from md.
-It also allows for some configuration with `.toml` files.
+# IMPORTANT
+This is still work in progress. It doesn't work yet.
+I pushed it onto github just to have easy access from other computers.
+(I'm too lazy to make a private repo)

-# How do I use this?
-Pretty simple. You just write blog entries into `/posts`.
-Then you run the compiled binary in `/src`.
-Voila. All the html and css is ready for deployment inside of `/out` directory.
+# What works, what doesn't?
+As this is still a WIP, here is a short list of what works and what still needs work.
+- [x] config parsing
+- [x] metadata parsing
+- [x] basic tests
+- [ ] parsing markdown
+- [ ] generating html documents
+- [ ] some nicer css styles
+- [ ] more sensible templates

-# How do I compile the binary?
-Simple. Just run `make` command and the magic will happen.
+# What is this? 
+This is a small blog app. Basically a static site generator.

-# How do I configure this?
-There are `.toml` files inside of `/config` directory.
-Every entry is pretty self-explanatory.
+# How does it work?
+It creates html files from markdown files, then it inserts them into html templates.

-# How does the directory structure works?
+# How do I use it?
+It is very simple.
+## First you need to compile the program
+In `/src` directory.
+`make`
+## Then you write some blog posts
+Every blog post needs to be in a different file in `/posts` directory.
+
+*Don't forget to put metadata in the header*
+
+An example from `/examples/post.md`
+```md
+---
+author: "joseph"
+date: "2026-01-01"
+title: "Example of a blog post"
+tags: ["blog", "test", "lalilulelo"]
+---
+# This is an example post
+
+In this example we will do a couple of cool markdown things.
+
+## This is a h2 header
+*This text is written in italic!*
+### Look at this!
+**This text is BOLD!**
+
+## Hello world!
+
+## Time to link some random website!
+This [should be clickable](https://example.com)
+
+## Image test
+![this should show an image](image.png)
+
+## This is an ordered list
+1. one
+2. six
+3. seven
+
+## This is an unordered one
+- six
+- nine
+- six
+- nine
+```
+## You also mustn't forget about creating a config file
+In root repo directory.
+`cp examples/config.toml config/`
+Then you can edit it for your liking.
+
+## Then you just run the binary
+In `/src` directory.
+`./blog`
+
+## Finally! Your beautiful site will be in `/out` directory
+From there you can rsync/push it to your server or do whatever you want to do with it.
+
+# How does the directory structure work?
 Also pretty simple. You have:
- `/config` for config files
+- `/config` for config files. Initially empty so you need to copy it from example dir or make one yourself.
 - `/examples` example of configuration files. Tests are dependent on it so don't edit the content of these files! You can copy it to `/config` and edit it there.
- `/out` for ready site. This folder should be on the web server.
- `/posts` here you write your blog posts. Every file should be in markdown format.
+- `/out` for processed site.
+- `/posts` here you write your blog posts. Every file should be in markdown format, metadata included!.
 - `/src` for cpp files. Here's where you run the binary to translate your markdown posts into html.
 - `/style` for css styling. You can tune it for your liking.
 - `/templates` for html templates. The format is pretty simple, so you can edit it, if you like.

+# Config file explanation
+## Fields
+`[general]` - General info about your site. Mostly `<head>` info.
+- lang – Language of the blog
+- title – Html title of the MAIN site. It will only show in the index.
+
+`[contact]` - Contact information in the footer.
+- author – Your name/nickname/whatever
+- email – Your email address | optional
+- signal – Signal profile url | optional
+
+Optional means it can be an empty string! Don't remove it from the file.
+
+## Example
+From `examples/config.toml`
+```
+[general]
+lang = "en"
+title = "Blog"
+
+[contact]
+author = "author"
+email = "email@example.com"
+signal = "signal url"
+```
+
+# Metadata explanation
+Metadata is everything at the beginning of the markdown file between `---`.
+It's written in a format similar to yaml.
+
+## Fields
+- author – the author of particular blog entry | string
+- date – date of writing an entry | string YYYY-MM-DD
+- title – title of blog entry | string
+- tags – tags for blog entry. | json like list
+
+## Example
+```
+author: "joseph"
+date: "2026-01-01"
+title: "Example of a blog post"
+tags: ["blog", "test", "lalilulelo"]
+```
+
 # Why did you do this?
-Because I wanted a small utility for my personal blog that doesn't have any
-javascript bullshit and is small, but also easy to write blog entries.
-Besides it's a pretty cool project, If I do say so myself.
+Because I wanted to build something! It's a fun exercise.
+Besides it's cool to host a blog with your own software.

 # Dependencies
 - `Catch2` framework for unit tests
 - `toml++` for toml parsing
+- `md4c` for markdown parsing
+
+# IMPORTANT NOTICE
+The project is developed for Linux only and is not expected to work on other platforms.