mindoc

About

mindoc is a template for a single self-contained, very mobile-friendly HTML document. A Pandoc template is included and is the most useful of the three template files.

mindoc is deliberately tiny. It uses a subset of Pure.css modules loaded from a CDN, with added or modified styles and JavaScript inlined.

It was designed for publishing single essays and course syllabi, but might also be suitable for very simple documentation of other kinds.

mindoc has been tested with Pandoc 1.19.2.1.

Installation

Get a blank HTML template here or the Pandoc template here (right-click and choose “Save Link As…”, “Download Linked File”, “Download Linked File As…”, etc.). All three files can be found in the dist directory of the project repository.

Usage

Simply edit mindoc-blank.html, or use mindoc-pandoc.html with Pandoc’s --template option:

pandoc mydocument.md --template mindoc-pandoc.html -o mydocument.html

Pandoc’s stdout can be piped to a utility like html-minifier:

pandoc mydocument.md --template mindoc-pandoc.html | html-minifier -c -minifier.conf -o mydocument.html

Use Grunt with a plugin like grunt-panda to automate document conversion:

grunt.initConfig({

    panda: {
      options: {
        pandocOptions: [
          '--template=lib/mindoc/dist/mindoc-pandoc.html',
          '--to=html5',
          '--section-divs',
          '--smart',
          '--variable=lang:en'
        ]
      },
      files: {
        src:  'src/mydocument.md',
        dest: 'dist/mydocument.html'
      }
    },

});

Features

Pandoc template variables

mindoc adds the following additional template variables to Pandoc’s default html template, along with minimal styling. You can use these additional variables in a YAML metadata block in your Markdown document:

Template variable Value appears in:
description Content of HTML tag meta name="description"
headnote Document, preceding value of variable published
published Document, preceding value of variable license
license Document, preceding value of variable title
version Document, preceding value of variable date
abstract Document, preceding the table of contents (if any)

headnote is useful for prepending a distribution notice (for example, “Draft copy. Please do not redistribute without permission”).

published can be used to prepend publication information.

Multiple authors

mindoc also adds the variables affiliation and email for document authors, and handles multiple authors (the following example is modified from Pandoc’s documentation):

---
author:
- name: Author One
  affiliation: University of Somewhere
  email: foo@bar
- name: Author Two
  affiliation: University of Nowhere
  email: bar@foo
---

Passing values of template variables to Pandoc with Grunt

As with other Pandoc commands and variables, you can pass the values of template variables to Pandoc using Grunt with a plugin like grunt-panda:

grunt.initConfig({

    pkg: grunt.file.readJSON('package.json'),

    panda: {
      options: {
        pandocOptions: [
          '--template=lib/mindoc/dist/mindoc-pandoc.html',
          '--to=html5',
          '--section-divs',
          '--smart',
          '--variable=lang:en',
          '--variable=description:<%= pkg.description %>',
          '--variable=version:<%= pkg.version %>',
          '--variable=headnote:"Draft copy."'
        ]
      },
      files: {
        src:  'src/mydocument.md',
        dest: 'dist/mydocument.html'
      }
    },

});

Here the values of the Pandoc template variables description and version are taken from values in the file package.json and inserted using Grunt template strings, whereas the value of headnote is specified explicitly.

Pure.css classes

mindoc also adds the following Pure.css classes to HTML elements in Pandoc output:

Examples

  1. You’re looking at one. View the Markdown source that produced this page.
  2. A course syllabus for “Historicizing ‘Digital Humanities’”
  3. Author’s preprint version of an article; and another