Markdown Manual

This is a template that uses Pandoc to auto-generate PDF and HTML manuals based on markdown content.

It can be easily integrated into existing repositories and deployed via gh-pages (see below).

Please install the most recent Pandoc package to get best results on your local computer.

PDF generation

PDF files are generated using LaTeX, so a working LaTeX engine needs to be installed on your system already (e.g. texlive incl. extra fonts). The manual uses the Eisvogel template.

cd manual
make pdf

Example

PDF file generated from this repo and deployed to its gh-pages branch

HTML generation

The HTML template is based on the great mdBook theme, which was simplified and adjusted a bit to suit the needs of a manual.

cd manual
make html

Examples

HTML files generated from this repo and deployed to its gh-pages branch
Hosted website at your-organization.github.io/repository-name (here: libre.solar/md-manual-template/)

Automatic deployment with Travis CI

Using the configuration in .travis.yml, the manual is rebuilt after each commit and automatically published using GitHub pages.

In a new repository you have to prepare the gh-pages branch in advance:

git checkout --orphan gh-pages
git rm -rf .
echo "My GitHub Page" > index.html
git add index.html
git commit -m "First pages commit"
git push origin gh-pages

You can find the atomatically deployed example manual of this repository here: https://libre.solar/md-manual-template/.