Pangolin Notebook is a simple static site generator for creating a notebook written using Pandoc-flavored Markdown, with citations, mathematics, auto-generation of previews, and hosting with GitHub Pages.
Author: Michael Hucka
Repository: https://github.com/mhucka/pangolin-notebook
License: Unless otherwise noted, this content is licensed under the MIT License.
- Introduction
- Installing Pangolin Notebook
- Using Pangolin Notebook
- Getting help and support
- Contributing — info for developers
- Copyright and license
- Acknowledgments
Pangolin Notebook grew out of a desire for a simple way to write a collection of documents, with the following criteria:
- write in plain text using a simple notation such as Markdown
- include citations, with references stored in BibTeX format
- include mathematics written in TeX notation
- auto-generate previews while editing on a local computer
- use GitHub Pages to host the formatted results
- use GitHub to store the source files and allow collaboration with other people
There exist other, similar systems, but I encountered a limitation or source of frustration in every one I tried. Ultimately, I was led to create Pangolin Notebook. Admittedly, it's another variation on a common theme, but if you're looking for the same features, maybe this particular formulation will be useful to you too.
The "Pangolin" in the name is a loose acronym for PANdoc-based Github dOcuments in htmL usIng markdowN. (By the way, pangolins are the most trafficked mammals in the world because stupid humans mistakenly think that eating them provides health benefits. Please learn more about them and the cruel way people treat them, and help stop their hunting before they are driven to extinction.)
Before you can use Pangolin Notebook, you will need the following software installed on your computer (using whatever method you prefer on your computer):
- Pandoc version 2.1 or later, with LaTeX and BibTeX support
- GNU Make
- fswatch (if you want to use Pangolin Notebooks' auto-rebuild approach)
- Common Unix/Linux utility programs such as
bash,ls,cp,sed, etc.
The basic approach is to create a fresh directory for your notebook, add the Pangolin Notebook source files into a subdirectory of that directory, and do some final configuration steps. In more detail, the following steps should get you started:
- Create a directory for your notebook and
cdinto it git initgit submodule add https://github.com/mhucka/pangolin-notebook.git./pangolin-notebook/setup
The setup step will create a new subdirectory called docs in which your notebook files are meant to be located. It will also create a few files as starting templates to help you understand the format.
The step of running setup above will copy a file named pangolin.yml into your notebook directory. This file needs to be edited to set certain variables. You can edit it using any text editor. The file contains comments that explain the variables; only four variables must be set because Pangolin Notebook cannot figure them out itself:
content-pages– this contains a list of the files that constitute the top-level pages of your notebook. You need to update this variable every time you add a new notebook page.sitename– a short name for your sitecopyright– a license for others to quote or use your contentnotebook-url– the online URL (e.g.,https://yourlogin.github.io/yournotebookif you're using GitHub Pages)
There are some additional variables in pangolin.yml that you can set, such as feedback-url if you want to point people to (e.g.,) an issue tracker, and bib-style if you want to use a different reference style file.
Writing documents is a matter of creating and editing in Pandoc-flavored Markdown format (optionally writing references in BibTeX format and creating figures in any web-viewable format you choose), then running make in your notebook directory to (re)generate the HTML files for your notebook contents. The latter process can be automated using the make autorefresh command, which uses a combination of JavaScript inserted into every HTML page and fswatch to let you keep a web browser open on your notebook and have it be refreshed automatically each time you save changes to your files.
When you create new files in your docs directory, you need to update the value of the variable content-pages in the file pangolin.yml. The order in which the files are listed is the order in which they will appear in the table of contents on the front page of your notebook.
To generated formatted output, you can manually run the following command in your notebook directory:
make
The index.html file will be placed at the top level of your notebook directory, and the formatted output for all other pages will be placed in the docs directory. Normally, the process should only recreate those files that need to be recreated based on whether the corresponding source .md files have changed. If you need to force the regeneration of everything, use make force.
Pangolin Notebook includes an auto-refresh facility that puts JavaScript code into every HTML page to detect that the underlying file has been changed. (It only does this for files on your local computer, not for files located anywhere else—it will not do this on GitHub Pages, for example.) This is meant to work in conjunction with a simple auto-re-make scheme to let you view the formatted HTML in a browser as you edit. To take advantage of this, run the following command in your notebook directory:
make autorefresh
Then open a notebook page in your browser, and try editing the corresponding Markdown file. After a second or two, the page in your web browser should refresh to show the changed version.
... more forthcoming ...
... more forthcoming ...
If you like this software, don't forget to give this repo a star on GitHub to show your support!
If you find an issue, please submit it in the GitHub issue tracker for this repository.
I would be happy to receive your help and participation if you are interested. Everyone is asked to read and respect the code of conduct when participating in this project.
Copyright (c) 2017 by Michael Hucka and the California Institute of Technology.
The original files in this project are licensed under the MIT License. This project makes use of files from other projects such as Bootstrap. Please see the file LICENSE for complete copyright and license details.
The code for detecting changes in a page was originally created by S. Fuchs and described in a blog entry. The JavaScript CRC check function used here was posted to Stack Overflow by user "Alex". The image of the illustration of a Pangolin used on this page came from Wikimedia and was originally created by Joseph Wolf and published in the Proceedings of the Zoological Society of London, 1865.
