Blog 1

Random Talk on Random Thoughts

A Quick Markdown Syntax Error Detection for Writing MathJax Equations in Octopress Posts (3)

| Comments | ∞

Background

I often write math in this blog. After typing lots of characters, syntax errors are inevitable, but no one wants them to be published. Unluckily, the rake generate command takes too long to run. In order to find them out more quickly, I quickly went over the Gemfile of the repository for this blog, and saw that the Markdown engine of Octopress is kramdown. Therefore, I used the command line version of this Markdown parser to convert my Markdown source file to an HTML document by a Vim Ex command.

:!kramdown % > %<.html

For this, I’ve written two posts describing the workflow of producing HTML web pages consisting of math expressions from Markdown source files using kramdown and MathJax.

Problem

In the first post in this series, I’ve made a list of steps in Vim. However, jumping to other files is laborious. More importantly, those steps involve browsing and copying of lines of HTML code of the <head>, which loads MathJax, in other HTML files. This can seriously slow down the editing process. Unhappily, this problem isn’t solved in the second post in this series.

Solution

Include the script in the content

There might be some option for the kramdown command line utility to use accept an HTML template files during the code conversion. However, I’m too lazy to search for them as I need to work on math.1

Remembering that I defered the loading of JavaScripts in order to boost the PageSpeed score of this site, I adpated the script to load MathJax instead of fancyBox in my draft markdown file.2

Put this at the bottom 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<script type="text/javascript">
(function() {
  function getScript(url,success){
    var script=document.createElement('script');
    script.src=url;
    var head=document.getElementsByTagName('head')[0],
    done=false;
    script.onload=script.onreadystatechange = function(){
      if ( !done && (!this.readyState || this.readyState == 'loaded' || this.readyState == 'complete') ) {
      done=true;
      success();
      script.onload = script.onreadystatechange = null;
      head.removeChild(script);
      }
    };
    head.appendChild(script);
  }

  getScript("https://cdn.mathjax.org/mathjax/latest/MathJax.js?" +
    "config=TeX-AMS-MML_HTMLorMML" +
    ",https://vincenttam.github.io/javascripts/MathJaxLocal.js",
    function(){});

})();
</script>

A problem with Vim’s folding arised

(Added on DEC 12TH, 2016)

This subsection can be omitted since appending the above code can be done with cat. Please see the next post in this series for the detailed description.

By default, with the plugin vim-markdown installed, the sections are folded. Before I can continue editing at the end of the file, I have to open the last fold, which contained more than 25 lines due to the script enabling MathJax at the bottom. As a result, I have to move back to the middle of the last fold by pressing k for a while. That annoys me. If the script is contained in a separate fold, it’s better. Therefore, adding a blank line and then a line consisting of three hyphens will fix this problem.

Inadequacies

(Added on SEP 3RD, 2015)

Now I realised that kramdown will leave the trailing two backslashes at each line inside <div> tags in Markdown source files untouched.

In the second post in this series, we know that <div> tag prevents kramdown from converting the code inside the tag to HTML, while in another old post about kramdown’s Markdown attributes, one can revert the above behaviour by simply adding an attribute markdown="1" to the <div> tag. These can be reflected in the above test.

Usually, in math environments inside a $\rm \LaTeX$ document, double backslashes \\ start a new line, and it’s the same in MathJax. Typing two backslashes in the Markdown source down will suffice. Unluckily, in the real Markdown source for Octopress posts, four \ are needed.

  1. For example, I have to think about multi-variable real-valued functions. ↩

  2. Refer to my old post Octopress, PageSpeed, jQuery and fancyBox in Blog 1 for details. ↩

Comments