2023-03-27 15:08:00 +00:00
|
|
|
# Doc-generator
|
|
|
|
|
|
2023-03-29 00:18:06 +00:00
|
|
|
Here is the documentation of the language in markdown, and a program to
|
|
|
|
|
generate static HTML files from them.
|
2023-03-27 15:08:00 +00:00
|
|
|
|
|
|
|
|
## `src` folder
|
|
|
|
|
|
2023-03-29 00:18:06 +00:00
|
|
|
Rust code to generate HTML files from MD files.
|
|
|
|
|
|
|
|
|
|
The binary is called like:
|
|
|
|
|
|
|
|
|
|
```sh
|
2023-04-11 02:10:53 +00:00
|
|
|
generator --input /path/to/markdown/folder/ --output /path/to/static/folder/
|
2023-03-29 00:18:06 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## `markdown` folder
|
|
|
|
|
|
|
|
|
|
Contains the Markdown. All files inside are expected to be UTF-8 encoded
|
|
|
|
|
markdown, and have the `.md` file extension.
|
2023-03-27 15:08:00 +00:00
|
|
|
|
2023-04-11 02:10:53 +00:00
|
|
|
The markdown follows the CommonMark specification, but certain code blocks
|
|
|
|
|
contain custom behaviour:
|
|
|
|
|
|
|
|
|
|
### `meta`
|
|
|
|
|
|
|
|
|
|
A code block with language `meta` contains text in TOML format that indicates
|
|
|
|
|
metadata for the current page.
|
|
|
|
|
|
|
|
|
|
````toml
|
|
|
|
|
```meta
|
|
|
|
|
title: "Title of the page"
|
|
|
|
|
description: "Description of the page"
|
|
|
|
|
```
|
|
|
|
|
````
|
|
|
|
|
|
|
|
|
|
- title: Used to create the title of the page with the format `{title} - Misti`
|
|
|
|
|
- description: The description of the page, placed in a `<meta>` element in the `<head>`
|
|
|
|
|
|
|
|
|
|
### `nav`
|
|
|
|
|
|
|
|
|
|
Used to link to the previous/next page.
|
|
|
|
|
|
|
|
|
|
````toml
|
|
|
|
|
```nav
|
|
|
|
|
[previous]
|
|
|
|
|
href = "./relative/path/to/previous.html"
|
|
|
|
|
title = "Title of previous page"
|
|
|
|
|
|
|
|
|
|
[next]
|
|
|
|
|
href = "./relative/path/to/previous.html"
|
|
|
|
|
title = "Title of previous page"
|
|
|
|
|
```
|
|
|
|
|
````
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2023-03-27 15:08:00 +00:00
|
|
|
## `static` folder
|
|
|
|
|
|
2023-03-29 00:18:06 +00:00
|
|
|
Contains CSS, JS, and HTML templates. Here the MD files are written to
|
|
|
|
|
after being converted.
|
2023-03-27 15:08:00 +00:00
|
|
|
|
2023-03-29 00:32:06 +00:00
|
|
|
There must be a `template.html` file inside this folder. This file will be used to generate the HTML from MD files.
|
|
|
|
|
|
|
|
|
|
Inside `template.html` there must be a string `{{markdown}}`:
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
<!-- Some html -->
|
|
|
|
|
{{markdown}}
|
|
|
|
|
<!-- More html -->
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This string, `{{markdown}}`, will be replaced with the HTML generated
|
|
|
|
|
from Markdown
|
|
|
|
|
|
2023-03-27 15:08:00 +00:00
|
|
|
## `dist` folder
|
|
|
|
|
|
2023-03-29 00:18:06 +00:00
|
|
|
Coming soon, this folder will contain all HTML, CSS & JS minified after
|
|
|
|
|
running a script.
|
