Pandoc Simple Template
Argp / Docs / Simple Template / Pandoc
Demo: https://st.argp.in/pandoc/
Pandoc is the universal document converter. This project uses Pandoc to generate static web pages from markdown files using Make. The source directory contains markdown source files. Make is configured to check for the folders and create them under html directory and generate HTML files from the source using Pandoc using templates in template directory.
The main part is Makefile and template directory. Easy way to get started is to clone the repository and edit the files as desired. After placing the source files in source directory, run make command to generate HTML files.
You can open the generated files directly in your web browers. Alternatively, you can installed Caddy or any other web server and point it to html directory. Caddy server is recommended because it ships as a single binary file which can be easily installed. Usage is also very simple with minimal configuration. To run Caddy and serve the files run the following command.
By default Make will generate sitemap.txt containing sitemap of all pages in html directory. To configure the baseurl for sitemap, change the BASEURL variable at the top of Makefile. To change the filename you can edit the SITEMAP variable under Files section. If you don’t want it to generate sitemap automatically, then remove $(SITEMAP) from default target’s prerequisite list.
Make uses tree command to generate sitemap.html containing list of all HTML files in form of a tree. By default, navigation.html contains a link to this file. If you don’t want it to generate this file, then remove $(TREE) from default target’s prerequisite list and remove the <a> tag from navigation.html.
Make looks for files in static directory and copies the contents into html folder. This folder can be used to put files like robots.txt, CSS, Javascript, images or basically any static content. Note that even if a single file is changed, Make will copy all of the contents to html file.
For navigation, it template uses template/navigation.html file. The contents of the file are directly pasted in header tag above h1 tag. To change the links you can directly edit the file. After editing the file if you will run make, it will automatically update all of the HTML files.
If you want to use CI/CD services to generate the static site automatically, you can use the Pandoc docker image I maintain. It is configured to work well with this project.
# Sample Gitlab CI
image: ankitrgadiya/pandoc
pages:
script:
- make all
- mv html public
artifacts:
paths:
- public
only:
- master# Sample Travis CI
sudo: required
services:
- docker
before_install:
- docker pull ankitrgadiya/pandoc
script:
- |
docker run \
-v $TRAVIS_BUILD_DIR:/dir \
-it ankitrgadiya/pandoc \
/bin/sh -c "cd dir && make"
deploy:
- provider: pages
skip-cleanup: true
github-token: $GITHUB_TOKEN
local-dir: html
on:
branch: masterBSD 3-Clause License.