Webify

A python utility for creating static websites and PDF documents from markdown and yaml files.


Faisal Qureshi
https://faisalqureshi.github.io/

Versions

v1.7

  • YAML front-matter in md files is now available as context during rendering.

v1.6 Initial release

Introduction

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](https://jekyllrb.com/. 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 any machine that supports docker.

Example sites

I have used Webify to generate the following sites:

Usage

Webify supports templating through Mustache. Context for Mustache is stored in YAML data files.

Webify is used as follows:

python webify.py /path-to/src-folder /path-to/dest-folder

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 favourite web hosting site.

How does it work?

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:

  1. Markdown file is converted into an HTML snippet, which as incorporated into a Mustache template;
  2. Markdown file is converted to a standalone HTML file;
  3. Markdown file is converted to a PDF file; and
  4. Markdown file is converted into a beamer slideshow (PDF).

Yaml front matter included in a Markdown file is used to control how a Markdown file will be converted.

Example yaml header for option 1 above

---
render: /path/to/mustache/template/file

In this case the contents of this markdown files replace the '{{{body}}}' tag of mustache template.

Example yaml header for option 2 above

---
template: /path/to/optional/pandoc/html5/template/file

This is akin to using the following pandoc command

pandoc -t html5 --mathjax --highlight-style=pygments this-file.md -o this-file.html

Example yaml header for option 3 above

---
to: pdf
template: /path/to/optional/pandoc/latex/template/file

This is akin to using the following pandoc command

pandoc -t latex --mathjax --highlight-style=kate -V graphics:true this-file.md -o this-file.pdf

or

pandoc --template=/path/to/optional/pandoc/latex/template/file --mathjax --highlight-style=kate -V graphics:true this-file.md -o this-file.pdf

Example yaml header for option 4 above

---
to: beamer
template: /path/to/optional/pandoc/beamer/template/file

This is akin to using the following pandoc command

pandoc -t beamer --mathjax --highlight-style=kate -V graphics:true this-file.md -o this-file.pdf

or

pandoc --template=/path/to/optional/pandoc/beamer/template/file --mathjax --highlight-style=kate -V graphics:true this-file.md -o this-file.pdf

Folder /_partials

The _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:

  • nav.yaml
  • nav.md
  • footer.html
  • header.html

It is possible to included the contents of the rendered nav.md, footer.html and header.html files using {{{nav_md}}}, {{{footer_html}}} and {{{header_html}}} mustache keys.

.webifyignore

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.

A note about yaml files

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.

Converting markdown files to pdf documents

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.

---
files:
    - include-in-header: /path/to/file
    - include-before: /path/to/file
    - include-after: /path/to/file
to: beamer or pdf
template: /path/to/file 

Check out the pdf file generated from this markdown file.

Copying markdown files to destination

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.

---
copy-to-destination: True

Docker

You can use the following docker file to setup a docker container ready to run webify. This allows webify to work on any platform where docker is available.

FROM ubuntu:16.04

RUN apt-get update
RUN apt-get install -y texlive-full
RUN apt-get upgrade -y
RUN apt-get install -y python-pip python-dev build-essential
RUN pip install --upgrade pip 

RUN apt-get install -y haskell-platform
RUN apt-get install  -y pandoc
RUN pip install numpy
RUN pip install pyyaml
RUN pip install pystache
RUN pip install pypandoc
RUN pip install watchdog

You can map host folders and use webify as follows

Host$ docker run -it -v /path-to/webify:/webify -v /path-to/src:/src -v /path-to/dest:/dest webify

Last updated 2018-02-02 20:41
© Faisal Qureshi
Site generated using © Webify