62 lines
3.1 KiB
Markdown
62 lines
3.1 KiB
Markdown
# 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.
|
|
|