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/.