hydrogen

Simplistic static site generator

Quickstart

git clone https://git.exocortex.ru/Exocortex/hydrogen.git

cd hydrogen && pip install -r requirements.txt

put some Markdown files into the content directory.

./hydrogen.py

the public directory is ready to be published.

Building and running in Docker

git clone https://git.exocortex.ru/Exocortex/hydrogen.git

cd hydrogen && docker buildx build --tag hydrogen .

put some Markdown files into the content directory

docker run -v .:/app hydrogen

the public directory is ready to be published.

Conventions / expectations

hydrogen expects the following files in the content directory:

• Markdown files ('*.md' only): these are the text files rendered to the HTML.
• Image files ('*.jpg' only): if a '.jpg' file is present in the content directory and has the same name as an '.md' file, the '.jpg' file will be rendered at the top of the HTML page and in the preview card for the entry.
• Custom CSS files ('.css' only): if a '.css' file is present in the content directory and has the same name as an '.md' file, it will be included in the HTML page.
• Custom Javascript files ('.js' only): if a '.js' file is present in the content directory and has the same name as an '.md' file, it will be included in the HTML page for late loading.

Required syntax

The resulting HTML files are rendered from the Markdown source files in the content folder, so even the plain text source files will work.
The correct HTML may be included directly in the source file and will be rendered both in the preview card and in the HTML page.
frontmatter header is recommended, specifying the following values:

• title: "Will be rendered in the preview card and in the HTML page" (String)
• omit_second_title: Should the title be displayed immediately above the text in the HTML page (HTML page always also displays the title in the header) (Boolean, "True|False")
• date: Timestamp, like the date and time the text was created. ("2000-01-01T00:00:00+03:00")

Configuration

Configuration is minimal and done via the self-explanatory config.py file.

Customization

Individual HTML pages can be customized via CSS and Javascript. To do so, put a '.css' and/or '.js' file into the content directory and make sure those files have the same name as the source '.md file'. E.g.:

• article-01.md - source file rendered to HTML.
• article-01.css - a CSS file with custom styles for the resulting HTML page.
• article-01.js - a Javascript file with custom logic for the resulting HTML page.

Directories and structure

Output directories

• public - main output directory, which can be served via a web server.
• assets - contains the resulting custom CSS and JS snippets.
• images - contains the resulting images rendered in the HTML pages.

Input directories

• content - contains the source Markdown. images, CSS and Javascript customization files.
• static - contains static image files and the special about.md source file.
• templates - contains Jinja2 templates for rendering Markdown to HTML.