From 1c2e480232904dd549aa886684fc2dd319dbad85 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stig-=C3=98rjan=20Smelror?= Date: Fri, 2 Feb 2024 13:04:25 +0100 Subject: [PATCH] Update README.md --- README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 901df77..bf1c7e0 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,56 @@ -# qsgen2 -Quick Site Generator 2 is a static website generator inspired by Nikola and written using Zsh +# Quick Site Generator 2 +Quick Site Generator 2 is a static website generator inspired by Nikola and written using Zsh. -At the moment, it doesn't do anything as it is a work in progress. +```qsgen2``` is capable of creating static HTML pages using the native ```_html``` engine (that I'll describe in detail later) or by writing your pages and blogs in Markdown. It uses [Pandoc](https://github.com/jgm/pandoc/releases), mostly because it's the most compete tool for the job. Not all Linux distributions have it, so you can just download the binaries and place them where it suits you the best. + +You cannot mix native and Markdown when creating your project. + +## Configuration + +You first have to configure your site and this is done in the file [config](config). + +## Themes + +```qsgen``` uses templates that reside in ```$project_dir/themes/```. +The theme consists of 4 files: + +* blogs.tpl +* pages.tpl +* blog_index.tpl +* blog_list.tpl + +### Blogs + +The file ```blogs.tpl``` is used to create the blog posts that will reside in ```$www_root/blogs/year/mon/date/title-of-blog-post.html```. +```qsgen2``` will list all the files in ```blog/*.blog``` and do its magic before the word/tag ```BODY``` in the blogs.tpl file is replaced with the HTML formatted content and then the file will be written to disk. + +Other tags/words that are replaced are: + +* BLOGTITLE +* CALADAY +* CALNDAY +* CALMONTH +* CALYEAR +* INGRESS + +Then the footer of the document is updated with today's date and the name and version of the script. + +The themes engine is not 100% complete because there still are some static text that could or should be replaced. It is, however, quite easy. + +#### Blog Index + +There is an option in the file ```config``` if you want to show the blog on the front page or not. If set to false, it will write a file in ```$www_root/blog/index.html``` that contains, in reverse order, the blogs written. + +To do this it uses the file ```blog_list.tpl``` as a template for how to format this list and then it inserts this into the file ```blog_index.tpl``` which then is written to disk. + +### Pages + +The process of creating pages is almost the same as with blogs, but with fewer, and other, replacements. + +Tags replaced are: + +* #pagetitle +* #tagline +* BODY + +And then the footer gets the same touch as the blog posts.