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 filesignore_dirs
is a list of (sub)directories (within the directory that contains the Markdown files) to not build pages fromdefaults
are the values to be used when nothing is set in the metadata of the Markdown file:title
is the default title for generated pagesdescription
is the default description for generated pagesauthor
is the default name of the author shown on generaged pagesauthorlink
is the default target the author name links tostyle
is a URL or file path for the css style to be usedsettings
is an optional list of the following settings:nonav
for not creating a nav sectionnoheader
for not creating a header sectionnofooter
for not creating a footer sectionselfcontained
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 packageextras-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