Tiny static site generator
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.




    stoic [OPTIONS]

    -h, --help
        Show this help message.

    -c, --copy-mode
        Copy the unknown files to the output directory.

    -a, --sync-assets FILE ...
        Synchronize the given assets.

    -o, --output-dir OUTPUT_DIR
        Set the output directory.


stoic is a tiny static site generator.

It builds a tree of items by walking in the site directory and render that tree in the output directory.


The settings are read from ./settings.py.


  • title: site title
  • home: site url
  • site_dir: directory to build the tree of items from
  • output_dir: directory to render the tree to
  • layouts_dir: directory to read the layouts from
  • assets_dir: directory in which the assets are located
  • exclude: list of directories not to be included in the tree
  • items_per_page: maximum number of items per page
  • custom_filters: a dictionary which will be merged to the Jinja2 environment filters
  • default_layout: default layout (path is relative to layouts_dir)
  • source_extension: file extension of the markdown files (default: 'md')
  • source_index: file name of the markdown index (default: 'index.md')
  • destination_index: file name of the output index (default: 'index.html')
  • thumbnail_fmt: format string used to generate the thumbnail path.


stoic scans site_dir for files having a source_extension extension.

Unless --copy-mode is passed, stoic ignores any other files.

The output paths are computed as so:

  • foo/bar.md becomes foo/bar/index.html
  • foo/index.md becomes foo/index.html

The layouts will be given the following elements:

  • item: the node being processed, carries the following attributes:
    • content: the html content
    • url: the url of the item relative to home
    • parent: the parent item
    • children: the list of children
    • prev, next (only if paginated)
  • trail: (of type list), the path from item to root
  • root: the root item
  • title: the site title
  • home: the site url

Extra attributes are set through the YAML front matter of the markdown files.

You might want to set the layout attribute to indicate the layout of the related item.

To get the url of item a relative to item b, use the following: a.relurl(b).

Pagination will occur on item a if items_per_page > 0, a.paginate is true (and if len(a.children) > items_per_page).

The ignore attribute can be used to prevent rendering on the related item.


Python 3 and the following python libraries:

  • Jinja2
  • Misaka
  • PyYAML
  • Beautiful Soup 4