Useful set up for working an HackMD file without having to edit through the browser.

hackmd-local.md

Setup

Before you do anything, you'll need to install the following pieces of software:

• pandoc for converting Markdown to HTML.
• entr for automagic conversion of Markdown to HTML upon changes to underlying Markdown.
• browser-sync for automagic refresh upon changes to underlying HTML.

And you need a web browser. Hopefully one is available to you.

The next step is to get yourself a local copy of MathJax v3, which can be achieved by executing

git clone https://github.com/mathjax/MathJax.git /tmp/mj-tmp
mv /tmp/mj-tmp/es5 <path-of-your-choosing>/mathjax
rm -rf /tmp/mj-tmp

Conversion of Markdown to HTML with MathJax

Once this has all been done, you can run the following command to convert the Markdown to HTML:

pandoc --standalone \
       --mathjax=<path-of-your-choosing>/mathjax/tex-svg-full.js \
       -f gfm \
       main.md \
       -o main.html

assuming you're markdown file is called main.md and it's located in the current directory.

If you want to customize the MathJax configuration, you can do so by creating a file called mathjax-header.html and passing it to pandoc with the --include-in-header option, e.g.

<script>
  MathJax = {
    tex: {
      inlineMath: [['$', '$']],
      displayMath: [['$$', '$$']],
    },
    loader: {
      load: ['[tex]/color', '[tex]/physics']
    },
    tex: {
      tags: 'ams',
      packages: {
        '[+]': ['color', 'physics']
      }
    },
    svg: {
      fontCache: 'global'
    }
  };
</script>

and then execute

pandoc --standalone \
       --mathjax=<path-of-your-choosing>/mathjax/tex-svg-full.js \
       --include-in-header=extras/mathjax-header.html \
       -f gfm \
       main.md \
       -o main.html

Making conversion run automatically

We can make use of entr or some other file watcher to make the conversion run automatically upon changes to the Markdown file. With entr, this can be achieved by running

ls main.md | entr sh -c 'pandoc --standalone --mathjax=<path-of-your-choosing>/mathjax/tex-svg-full.js --include-in-header=extras/mathjax-header.html -f gfm main.md -o main.html'

assuming you're markdown file is called main.md and it's located in the current directory.

Serving the HTML

Now that we have the HTML, we can serve it with browser-sync by running

browser-sync start --server --files main.html

which should open a browser window with the HTML file loaded. If you make changes to the HTML file, the browser should automatically refresh.