# KISS static blog site generator

### Pseudo abandoned, re-implemented as a [flask project](https://git.node5.net/blog/blog.node5.net_flask/about/)

For [blog.node5.net](https://blog.node5.net), Made for my speceific use case, but otherwise generalized.

## Table of contents
- [KISS static blog site generator](#kiss-static-blog-site-generator)
- [Table of contents](#table-of-contents)
- [Features](#features)
- [Installation](#installation)
- [Creating content](#creating-content)
  - [Articles](#articles)
  - [Templates](#templates)
  - [Static](#static)
- [Usage](#usage)
- [TODO](#todo-feature-creep-galore)

## Features
- [live reload](https://pypi.org/project/livereload/) Preview changes live in your browser
- [Jinja2](https://jinja.palletsprojects.com/) Templating
- [Markdown](https://python-markdown.github.io/) Content writing
- [Code blocks syntax hightlighting](https://python-markdown.github.io/extensions/code_hilite/)

## Installation
```bash
git clone https://git.node5.net/blog-generator.git
cd blog-generator
make
```

If it throws an error like path not found or you otherwise don't have `~/.local/bin` in `echo $PATH` run the following,
for an explaination see 
[this StackExchange post](https://unix.stackexchange.com/questions/316765/which-distributions-have-home-local-bin-in-path)
```bash
mkdir ~/.local/bin
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.profile
```

## Creating content

All the of the site content is derived from one folder e.g. `default page` this containts 3 folders:

- [articles](#articles)
- [templates](#templates)
- [static](#static)

To make your own site simply, copy the `Default page`,
and pass this to the blog generator `blog_generator.py "Default page" live_reload`

### Articles
Any markdown file with the extension `.md` will be used, it can be in the root, or it can be in a folder and be named 
`index.md`, in which case the folder name will be used as the article name, this is useful, if you wish to have media
e.g. images for an aricle.

Meta data is defined at the top of the article in YAML format enclosed in `---`

```yaml
---
description: Example description
created: 2024-01-30
modified: 2024-02-01
---
```

Todays date can be generated in this format using the following command
```bash
date +%F
```

### Templates
These are [Jinja2](https://jinja.palletsprojects.com/) templates, which makes them very flexible.

### Static
All files in this folder will be copied over to the `output` folder

## Usage
`make generate` to delete the output folder and generate page
`make live_reload` to first generate and locally host the site and regenerate on file change
`make deploy` to remove meta data from media in this directory and sub directories (warning overwrites media)

The `generate` and `live_reload` both generate the site and outputs it to the `output` folder.
Which can be served, or copied to the web server you host it on.

## TODO Feature creep galore
- Refactor code, split out logic
- Refactor code, add comments
- Code highlight theme, based on blog color theme
- Headlines ids, for URL #reference
- Move more stuff to config(s), e.g. port, dateformat, sort
- Pretty format logging
- Propagate additional article meta data to be
- Split out article meta data to seperate class, do this once the desired features are more well known
- Build test pipeline
- Page source content root defined in one dir, pass arg with this, so it's easy to make a new page
- Text to diagrams
- Package code
- Default page code highlight
- Default page CSS
- Publish node5.net source
- Fix Debian install, it doesn't have user writable bin folder in `$PATH` by default like Arch's `~/.local/bin`
- Tags, article meta data tags
- RSS feed, auto generated
- Support other markdown files extentions
- Command line arguments for creating articles with meta data pre-filled
- Table of contents, auto generated
- Use modified date
- Add tree directory structure ascii art explaining folder structure
- Article source versioning
    - Sites as a sub repo? What about big media files like images?
    - Versioning git integration for markdown change history + derive modified meta data from git history
    - PEP8 check
    - CI/CD git deploy pipeline
- Categories
    - Derive values from directory structure
    - Allow for sub categories e.g. `hardware/keyboards`
    - Display the sub categories like folder structure
- Done
    - Make install
    - Describe insertion of HTML like for videos
    - Allow no arguments, by using current working directory to derive the source folder from, and default to live reload
    - On file change, generate only the specific file, don't regenerate the entire site
    - Allow an article to not have a directory, but just be a markdown file in the source directory