Argp / Docs / Simple Template / 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
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.
Sitemap and Tree
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.
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
Make looks for files in
static directory and copies the contents into
html folder. This folder can be used to put files like
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 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: master
BSD 3-Clause License.