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.
+# IMPORTANT
-It uses cpp to create html files from md.
+This is still work in progress. It doesn't work yet.
-It also allows for some configuration with `.toml` files.
+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?
+# What works, what doesn't?
-Pretty simple. You just write blog entries into `/posts`.
+As this is still a WIP, here is a short list of what works and what still needs work.
-Then you run the compiled binary in `/src`.
+- [x] config parsing
-Voila. All the html and css is ready for deployment inside of `/out` directory.
+- [x] metadata parsing
 - [x] basic tests
 - [ ] parsing markdown
 - [ ] generating html documents
 - [ ] some nicer css styles
 - [ ] more sensible templates
-# How do I compile the binary?
+# What is this? 
-Simple. Just run `make` command and the magic will happen.
+This is a small blog app. Basically a static site generator.
-# How do I configure this?
+# How does it work?
-There are `.toml` files inside of `/config` directory.
+It creates html files from markdown files, then it inserts them into html templates.
 Every entry is pretty self-explanatory.
-# 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.
+- `/out` for processed site.
- `/posts` here you write your blog posts. Every file should be in markdown format.
+- `/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
+Because I wanted to build something! It's a fun exercise.
-javascript bullshit and is small, but also easy to write blog entries.
+Besides it's cool to host a blog with your own software.
 Besides it's a pretty cool project, If I do say so myself.
 # 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.