A python utility for creating static websites and PDF documents from markdown and yaml files.
Webify is a Python tool for creating static websites and PDF documents from HTML and markdown files. It is similar to static site generators, such as Hugo and Jekyll. However, Webify has far fewer features (I believe), and it is probably much much slower. The upside is that Webify code is much easier to understand. It is also fast enough for my needs.
My primary motivation for writing Webify is to be able to use plaintext (markdown) for website. Jeykyll and Hugo are very good; however, I wanted something even simpler. I consider Webify the “hello world” of static site generators. A secondary motivation was to move my document generation work flow (course slides, assignments, etc.) to pandoc. You can think of Webify as a wrapper around pandoc. Webify sort of automates website and PDF documents generation. I have recently dockerized Webify, so now we can use it on any machine that supports docker.
I have used Webify to generate the following sites:
This documentation is also generated using webify.
Webify supports templating through Mustache. Context for Mustache is stored in YAML data files.
Webify is used as follows:
This will populate the destination folder with the generated website. You can then use ‘rsync’ or something similar to upload to the contents of the destination folder to your favorite web hosting site.
At its core, Webify renders html and markdown files using mustache templates and data stored in yaml files. Markdown files are rendered via pandoc through pypandoc. Currently the following four options are supported:
Yaml front matter included in a Markdown file is used to control how a Markdown file will be converted.
---
render: /path/to/mustache/template/fileIn this case the contents of this markdown files replace the ‘{{{body}}}’ tag of mustache template.
---
template: /path/to/optional/pandoc/html5/template/fileThis is akin to using the following pandoc command
---
to: pdf
template: /path/to/optional/pandoc/latex/template/fileThis is akin to using the following pandoc command
or
---
to: beamer
template: /path/to/optional/pandoc/beamer/template/fileThis is akin to using the following pandoc command
or
/_partialsThe _partials is used to store HTML, markdown and YAML files that can be used to create html snippets, which will be available to every markdown and html file during rendering.
For example, a _partial folder might contain the following files:
It is possible to include the contents of the rendered nav.md, footer.html and header.html files using {{{nav_md}}}, {{{footer_html}}} and {{{header_html}}} mustache keys.
Use .webifyignore file to indicate which files folders should not be processed. For example:
*~
.DS_Store index.yaml
_tmp
Internally, fnmatch is used to find matching files/folders.
YAML files are used to specify the data that is avaiable during mustache rendering. Data in a YAML file is available to every html/mustache file present in the current folder and all of its subfolders.
mdfile.py can be used as a standalone utility to convert a markdown file into a PDF documents. It uses pandoc to perform the actual conversion. Yaml frontmatter can be used to specify options for pandoc. Check out the source code for mdfile.py for supported tags. Here’s a sample pdf file generated from this markdown file.
Sometimes it is desirable to copy markdown files to the destination. Default behavior is to not copy the markdown files. This behavior can be overwritten using the following yaml frontmatter.
Check out the installation information available with the source code.