potoo is the program that generates this website. It is available on GitHub.
input/ ├── input.md ├── note.md └── category/ ├── a note in a category.md # regular Markdown note ├── image.jpg # media file └── sub-category/ ├── sub-category.md # category descriptor └── a note in a sub-category.md
The website is generated from a set of files in a directory. potoo processes it by following these rules:
- Each Markdown file generates an HTML file, with a few special cases (see below).
- Each directory generates an HTML file.
- Every non-Markdown file is copied into a media sub-directory.
- Hidden files/directories (ie its name starts with ".") are skipped.
potoo supports the standard Markdown syntax, with a few additions:
- Obsidian's links (wikilinks)
- Obsidian's embeded elements
- Fenced code blocks
Four optional meta-data fields can be placed at the beginning of the file: title, description, header, and header-caption.
title: My awesome note description: A short phrase explaining what this is about header: image.jpg header-caption: Description of the image ## Actual Markdown content ...
Note that if no header field is present, the header-caption meta-data is ignored.
Notes can be placed in directories to create categories.
└── category/ ├── a note in a category.md └── sub-category/ └── a note in a sub-category.md ...
Each category will generate a corresponding HTML page with links to its content.
Special Markdown files
If a Markdown file have the same name as its parent directory, it is considered a category descriptor. Its content is inserted at the top of the corresponding category page.
... └── sub-category/ ├── sub-category.md ...
Category descriptors may have an additional children meta-data field, which sets the order in which to display the children links.
The index file
input/ ├── input.md ...
The category descriptor of the whole input directory will generate the index.html file (even if its name is not index.md).
This Markdown file is effectively a category descriptor, which means it also supports the children meta-data field for ordering elements.
The static directory
static/ │ ├── style/ │ ├── style.css │ ├── Fredoka.ttf │ └── Josefin.ttf ├── favicon.ico ...
Files that should be used as-is (CSS files, fonts, favicon...) can be placed inside the static directory.
output/ ├── index.html ├── favicon.ico ├── note.html ├── category.html ├── a_note_in_a_category.html ├── sub-category.html ├── a_note_in_a_sub-category.html ├── media/ │ └── image.jpg └── style/ ├── style.css ├── Fredoka.ttf └── Josefin.ttf
The output directory contains the generated files. Its structure is as follows:
- Every HTML file is placed at the root
- Every non-HTML file is placed in a media sub-directory
- Everything that was stored in the static directory is copied at the root
Names of the generated files are "URLized" by replacing all non-alphanumeric character with an underscore.
This creates a limitation, as the program will return an error if two file names result in the same "URLized" name, even if the original files were placed in different directories.