Lesser Potoo. Original photo by julian londono (CC BY-SA 2.0)


potoo is the program that generates this website. It is available on GitHub.

Input directory

├── 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.

Markdown files

potoo supports the standard Markdown syntax, with a few additions:

  • Obsidian's links (wikilinks)
  • Obsidian's embeded elements
  • Fenced code blocks
  • Tables

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

Category descriptors

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.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

│   ├── 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.

Generated files

├── 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.