fnldoc
is a simple static site generator that uses the FNL markup language.
FNL is a Lisp-like markup language that provides uniform syntax and an extremely simple extension system, where extensions are libraries instead of middleware.
fnldoc
accepts a config file and a directory of files to which this config
is pointing. It produces another directory, where it puts the generated files.
That directory can then be used to serve a site, for example, using GitHub pages.
An example project is included in the github repository. input/
is the input
directory with the source files, and fnldoc.json
is the configuration file.
Firstly, the input fnl directory includes the docs themselves:
input/
thing.fnl
aaa/
stuff.fnl
x.fnl
It also includes the CSS and JS files to be included:
input/
dummy.css
dummy.js
Let's look at the example documentation.
{
// Path to the input directory, will be used relatively to the current directory
"input_directory": "input",
// The page
"start": "Thing",
// 'toc' (table of contents) defines the tree structure of the documentation.
// Each key is the name of the documentation page, and each value is either
// a path to an FNL file (relative to the input directory) or another TOC
"toc": {
"Thing": "thing.fnl",
"Aaa": {
"stuff": "aaa/stuff.fnl",
"In auctor tellus": "aaa/x.fnl"
},
"Bbb": {
"stuff": "aaa/stuff.fnl",
"In auctor tellus": "aaa/x.fnl"
}
},
// 'output_directory' is where all the generated files will be put,
// with both the 'serve' and the 'build' modes
"output_directory": "output",
// Optional extensions list. Contains pairs of values:
// ["python.module.name", "name_to_look_up"].
// python.module.name.name_to_look up must be a dictionary
// mapping strings to fnl.Entity
"extensions": [
["fnldoc.interpolate", "__extension__"],
["fnldoc.md", "__extension__"]
],
// The title that will be placed in the <title> tag
"title": "Example Title",
// CSS and JS files to put in the output directory:
"extra_css": [
"dummy.css"
],
"extra_js": [
"dummy.js"
]
}
pip install -e git+https://github.com/decorator-factory/fnldoc
-e git+https://github.com/decorator-factory/fnldoc#egg=fnldoc
install_requires=[
...
"fnldoc@git+https://github.com/decorator-factory/fnldoc#egg=fnldoc",
...
],
git clone ssh://git@github.com/decorator-factory/fnldoc
cd fnldoc
python3.8 -m venv env
env/bin/python -m pip install .
Build the documentation:
python -m fnldoc build path/to/config.json
Serve the documentation at 0.0.0.0:8080
:
python -m fnldoc serve path/to/config.json