Introduction #

I created StuffPages as a quick way to publish simple web pages on my web server. Basically, it takes Markdown files from a specified directory, turns them into CSS-styeld HTML files, and saves the output in another specified directory.

Have a look at some examples!

Installation #

Make sure Python 3 (>=3.6) is installed

Install pipx

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Install StuffPages
```
pipx install stuffpages
```

Usage #

Initialize StuffPages within the directory that contains the Markdown files:
```
cd /path/to/directory/
stuffpages init
```
Adapt /path/to/directory/_stuffpages/config.py according to your settings:
- output_dir is the name of the directory that will contain the converted HTML files
- ignore_dirs is a list of (sub)directories (within the directory that contains the Markdown files) to not build pages from
- defaults are the values to be used when nothing is set in the metadata of the Markdown file:
  - title is the default title for generated pages
  - description is the default description for generated pages
  - author is the default name of the author shown on generaged pages
  - authorlink is the default target the author name links to
  - style is a URL or file path for the css style to be used
  - settings is an optional list of the following settings:
    - nonav for not creating a nav section
    - noheader for not creating a header section
    - nofooter for not creating a footer section
    - selfcontained for having a _resources directory for each page
- html_head is a list of lines that are injected in the final HTML output between <head> and </head>
- html_nav is a list of lines that are injected in the final HTML output between <nav> and </nav>
- html_header is a list of lines that are injected in the final HTML output between <header> and </header>
- html_footer is a list of lines that are injected in the final HTML output between <footer> and </footer>
- pagelisting_format is a string describing the format for each item in pages listings ([PAGE])
- breadcrumb_format is a string describing the format for each item in breadcrumb listings ([BREADCRUMB])
- extras is a dictionary with additional modules to be used by the Markdown Python package
- extras-configs is a dictionary of configurations for the additional modules
Build the HTML pages:
```
stuffpages build
```

Listings #

Each Markdown file, as well as the html_(head|nav|header|footer) in the config file can contain special listings markers:

[TOC] will be replaced by the table of contents
[PAGES] will be replaced by a list of pages sorted by title, prepending ! (i.e. [!PAGES]) will reverse sort, and appending a defaults/meta data variable name (e.g. Description) will sort by that defaults/meta data (e.g. [PAGES Description])
[BREADCRUMB] will be replaced by a breadcrumb trail of links from the current page to the parent page