Warhol — Website Assembler Requiring Hardly any Other Libraries

Make a website from Markdown and HTML snippets

Current popular static-website generators are complex beasts, with advanced templating languages, and complicated, fragile and (e.g. Node) dependency-heavy example styles. This package is the antidote: a simple, minimal-dependency package for wrapping HTML and Markdown content pages in site-standard header/footer/etc. snippets. It's HTML, not rocket science.

Installing Warhol

As you probably expect, use a recipe like pip install warhol or python -m pip install warhol to install from the PyPI archive.

There isn't a way with Python packages to specify a build option that reduces the default number of dependencies, and as almost everyone will want Markdown format support the Python markdown is the sole installation dependency. If you actively want to avoid that, pass --no-deps to the installation command, and you can still use Warhol to assemble websites from pure-HTML chunks.

Using Warhol

Use warhol init to initialise a project directory with the basic structure and a simple template.

The warhol build command merges pages from the content/ directory with headers, footers, and box "asides" loaded from the include/ directory. Any Markdown .md files in the content directory tree are converted to HTML, and staged in the .build directory. The final stage is injection of includes and template parameters, which augment the cache contents and write out to the public/ directory.

Parameters are mostly defined as URL-regex maps in the config.toml config file. The default behaviour is for the build step to create a directory and index.html file in place of each (non-index) HTML file, so the webpage URLs do not have .html suffixes; this can be disabled via a regex match in the config file.

The generated site in the public/ directory can be viewed directly with a web browser, but as URLs are internally specified relative to the HTTP server root and index.html pages are assumed to be implicitly loaded, it's best to run a local web server. The warhol serve command does this, from the public/ dir by default.

Example

First, install warhol. Make and activate a virtual environment, then e.g.

$ python -m pip install warhol[md]

to install warhol with Markdown support.

Let's make a new site using the default template:

$ warhol init mysite -t
$ ls mysite/
content  include  warhol.toml
$ cd mysite/

You can edit the include components in the include/ dir, and customise how they are used by editing the warhol.toml. But just functionally, let's build the site:

$ warhol build
$ ls
content  include  public  warhol.toml

Note that the new public/ directory has appeared; this is your website, ready to use:

$ ls public/
favicon.ico  images  index.html  md  navbar.js  style.css  sub

For testing, run the local server:

$ warhol serve
Serving site from public/ at http://0.0.0.0:8080
Press Ctrl-C to stop serving...

and point your web browser at the given URL (something like Ctrl-click on the link in the terminal may work.)

You might like to run this like warhol serve & or otherwise put the process in the background. Another little hack is that if you like the rebuilds to happen continually, so you don't have to keep running the build command (and your site builds quickly), try watch warhol build once the server is running, and you can reload the browser ~immediately after saving file-changes.

When happy, deploy manually using your file-transfer tool of choice, e.g.

$ rsync -r public/ my.webhost.com/public_html/

TODO's

• pass markdown extensions list and options from the config?
• add a "deploy" command to execute a saved upload destination / command?
• add RST rendering via Python docutils
• blog mode with date-indexed pages, maybe tags?
• allow Markdown-based includes? Would require a restructure
• allow replacement of the site-root leading slash with a configurable string
• allow regex capture-group injection into templates... needs subst map?!?
• parallel processing for MD -> HTML (careful with progress bar, cf. tqdm.process_map)
• is there a use for JustHTML or BeautifulSoup to normalize output?
• use inotify to auto-trigger updates?