Static site generation for researchers | an interview with Wonseok Shin

Wonseok Shin

Wonseok Shin is the creator of jemdoc+MathJax

Here is our fourth interview with interesting people in the MathJax community. This time we had the pleasure to talk to Wonseok Shin (Stanford University) about jemdoc and jemdoc+MathJax.

You recently extended jemdoc to create jemdoc+MathJax. Can you tell us a bit about jemdoc and your work on it?

jemdoc is an open-source static site generator that allows you to create simple websites. It is composed of just a single Python script, so it is extremely lightweight and portable.

jemdoc was developed by Jacob Mattingley while he was a Ph.D. student at Stanford University. I guess he developed jemdoc to create his personal academic website easily. In fact, jemdoc is most commonly used to create university professors’ personal websites that introduce their research and teaching experiences. (If you google “jemdoc”, you will see a bunch of professors’ websites.) It is also being widely used to create university course websites.

In addition to being lightweight and easy to use, the ability to load LaTeX equations has been one of the reasons for jemdoc’s popularity in academia. However, the original jemdoc loads LaTeX equations as PNG images, which can be pixelated on high-resolution displays or upon magnifying the webpage.

I have modified the original jemdoc to support MathJax. The modified jemdoc is called jemdoc+MathJax. If you are already a jemdoc user, you don’t have to change anything in your *.jemdoc files. By simply replacing jemdoc with jemdoc+MathJax and processing your *.jemdoc files again, you create a new website in which all PNG equation images are replaced with beautiful MathJax-rendered equations.

Why choose jemdoc’s markup language over other lightweight markup solutions like markdown or textile and how does jemdoc fit into this ecosystem?

To me, it made perfect sense to implement MathJax support in jemdoc than in other markup solutions, because jemdoc is already being widely used in academia, where mathematics is the primary language to communicate ideas and therefore equation rendering is highly demanded.

For general users, the biggest difference between jemdoc and other markup solutions could be that it creates an entire website (including a navigation sidebar) rather than a single webpage. Therefore, if you want to create an entire website from scratch, jemdoc can be a better choice than other markup solutions.

Being able to generate an entire website makes it very easy to migrate from one web server to another, because you can simply move the HTML files to the new web server. Again, this is a useful feature for people in academia. For example, if you create your personal website as an undergraduate in one university and seek for more advanced degrees in another university, you can easily move your entire website from old university’s web server to new university’s by moving the HTML files.

Can you tell us a little bit about your background?

I did my Ph.D. degree in Electrical Engineering at Stanford University, and I am currently a postdoctoral scholar in the same university. I have developed my programming skills through my previous experience as a software engineer at a startup company, and also through my doctoral research in which I studied electromagnetic phenomena by numerical simulation (which involved a lot of programming).

Around the time I was finishing up the Ph.D. degree, I felt a need for a neat personal website to introduce my research more efficiently to my fellow researchers. I tested several static site generators, and jemdoc stood out with the built-in LaTeX equation support because I needed to use equations to describe my research. However, I was disappointed with the quality of the rendered equations in jemdoc. I knew about MathJax already, and really wanted to use it, but failed to find an existing MathJax implementation in jemdoc. So I spent some time to implement MathJax in jemdoc myself.

Originally, the MathJax support was a personal project that I intended to use only for my personal website. I uploaded the modified code at Github anyway for my own convenience. One day a complete stranger who saw my Github repository contacted me and asked if I could teach him how to use MathJax in jemdoc. That was when I realized other people’s interest in using MathJax in jemdoc. So I polished the code, added concrete examples for the additional features I implemented, and named the project jemdoc+MathJax.

Who do you see as the primary users for jemdoc+MathJax?

The primary users would be the previous jemdoc users. As I mentioned earlier, you don’t have to change anything in your *.jemdoc files. By simply using jemdoc+MathJax instead of jemdoc to process your *.jemdoc files, you create a new website with nicer-looking equations.

People who want to create a simple website with lots of equations, such as mathematicians, scientists, and engineers in academia, will also find jemdoc+MathJax useful, even if they haven’t used jemdoc previously.

Mathematical markup is not naturally “lightweight”. What are your thoughts on the future of mathematical markup on the web?

I think mathematical markup will become more popular in the future. Massive open online courses (MOOCs) such as Coursera and EdX will be major driving forces. There, students need to submit their homework solutions on the web. However, assigning math and science homework problems is currently difficult in MOOCs, because most homework problems in these subjects require equations as answers, which are hard to input on the web. With an easy-to-use mathematical markup system, testing students’ knowledge on math and science subjects in MOOCs will become much easier.

With static site generators, hosting becomes easy but web-based authoring isn’t straight forward. Any tips for jemdoc users who want the best of both worlds?

Unfortunately, there is no web-based authoring system for jemdoc currently. Using jemdoc requires some familiarity with UNIX-like operating systems.

However, if you have a bit of experience on UNIX-like operating systems, using jemdoc is quite straightforward. You first write down the contents of webpages in jemdoc’s Markup language, which is similar to Markdown, and store them as text files, typically with “.jemdoc” as the filename extension. (Each .jemdoc file describes a single webpage in your website.) Then you process the .jemdoc files with jemdoc to convert them to HTML files. The generated HTML files constitute your website. You can simply upload the HTML files to your web server’s dedicated folder under your account to make your website running.

Detailed usage of jemdoc can be found in jemdoc’s official website at http://jemdoc.jaboc.net. Note that the official website itself is created completely by jemdoc.

What are your (near or long) term plans for your work on jemdoc+MathJax?

I use jemdoc+MathJax for my personal academic website, and I don’t see a particular feature that I need immediately, partly because jemdoc itself is already a pretty mature system with many useful features. There were some lacking features such as drawing underscores in the original jemdoc, and I have already added those features in jemdoc+MathJax, whose usage are explained in detail in the example files included in the jemdoc+MathJax package.

I will respond to any bug reports and feature suggestions as much as possible. Also, jemdoc+MathJax is open-source and the source code is publicly available as a GitHub project at https://github.com/wsshin/jemdoc_mathjax. I hope other people contribute to jemdoc+MathJax, as I did to the original jemdoc, to implement useful features.

Posted in COMM | Comments Off

Changes to the MathJax CDN

With the release of MathJax v2.4, we have switched CDN providers. The MathJax CDN is now combining Google Cloud Storage and CloudFlare.

The majority of page authors and developers will not have to do anything — http://cdn.mathjax.org continues to work as expected.

However:

Important changes for SSL users

The MathJax CDN now provides SSL access at cdn.mathjax.org.

NOTE: The direct Rackspace address will be retired on July 31, 2014.

If you have been using the address

https://c328740.ssl.cf1.rackcdn.com/…

you should switch to

https://cdn.mathjax.org/…

See the MathJax documentation for more information.

Posted in News | 4 Comments

American Physical Society continues as MathJax Supporter

The American Physical Society (APS) continues to support the MathJax project as a MathJax Supporter.

Founded in 1899, the APS has long been furthering innovation in academic communication. As an influential supporter of SGML-based math notation in the 1990s and an early adopter of MathML, APS continues to push for innovation in electronic commmunication of math and science. APS is the largest society of professional physicists in the US and involved in several activities to advance and diffuse the knowledge of physics, including a strong publication program with landmark titles such as Physical Review Letters, the Physical Review journals, and Reviews of Modern Physics.

“APS will be launching full text HTML for our math-intensive journal content later this summer.” says Mark Doyle, Director of Journal Information Systems at APS. “MathJax is one of the key components we will be using and its maturity is now at the point where we can provide the high quality experience our readers expect.”

“As one of the original MathJax sponsors, APS has been providing both support and important feedback for our development at MathJax”, comments Peter Krautzberger, MathJax manager. “Thanks to the dedicated of sponsors such as APS, MathJax is able to deliver a reliable, high-quality solution for science and math on the web.”

We look forward to continuing the collaboration with APS, and welcome their ongoing support for the MathJax project.

Posted in News | Comments Off

Cambridge University Press continues as MathJax Supporter

Cambridge University Press continues to support the MathJax project as a MathJax Supporter.

Cambridge University Press dates from 1534 and is part of the University of Cambridge. Following the University’s mission, CUP works to disseminate knowledge in the pursuit of education, learning and research at the highest international levels of excellence. The publishing program of CUP comprises of over 45,000 titles by authors from over 100 countries. Cambridge Journals employs MathJax to deliver high-quality, accessible mathematics in over 300 peer-reviewed journals.

“Cambridge is providing more and more of its content digitally and MathJax helps us ensure that our key titles in Mathematics are well displayed.” said Chris Fell, Digital Publishing Director at Cambridge University Press.

“As a MathJax sponsor, CUP provides the MathJax team with important support and feedback for our development,” comments Peter Krautzberger, MathJax manager. “Thanks to dedicated sponsors like CUP, we can keep MathJax the high-quality, reliable, and flexible rendering solution it is today.”

We look forward to continuing the collaboration with CUP, and welcome their ongoing support for the MathJax project.

Posted in News | Comments Off

The Optical Society of America continues as MathJax Supporter

The Optical Society (OSA) continues to support MathJax as a MathJax Supporter.

Founded in 1916, OSA is a leading scientific society in optics and photonics and home to thousands of accomplished academic, industry, and business leaders. Uniting220,000 scientists and professionals in 175 countries, OSA promotes research, real-world applications and achievements in the field. As part of its publishing program, OSA delivers high-quality, peer-reviewed content in a state-of-the-art and web-standards-compliant way, incorporating full-text HTML in all of its journals.

“As a long-term MathJax sponsor, OSA is providing important support and feedback for our development,” comments Peter Krautzberger, MathJax manager. “Thanks to the dedication of sponsors such as OSA, we can keep MathJax the reliable, high-quality rendering solution it is today.”

Scott Dineen, senior director of OSA’s journal production operations, adds that “OSA relies on MathJax for accurate display of the MathML equations in our online journals. We’re pleased to be a MathJax supporter and excited to be involved with the ongoing development of this valuable tool.”

The MathJax team looks forward to continuing the collaboration with OSA and welcomes their ongoing support for the MathJax project.

Posted in News | Comments Off