Update : I've now ported my blog, again, to a new framework. See my new post.

Introduction

I've spent the past few weeks updating this blog from the python-based Pelican framework to the Javascript-based Gatsby framework. Overall, it's been a challenging but rewarding experience. I've learned a little bit about the React framework as well as Gatsby's plugin ecosystem. I thought a brief overview of some of the challenges I faced could be of use to other bloggers looking to make the switch.

• Starter Theme

  I chose a Gatsby blog theme from LekoArts. It's a nice, simple design with all the features I need for blog site. One complicating issue I found was that the theme ships as a "shadowed" theme plugin with a set of core and blog specific components. In order to modify the theme, I had to combine components from both plugins into a single local plugin.

• Theme UI

  The blog theme uses ThemeUI. This library enables the Light and Dark mode button at the top of the page as well as the responsive layout.

• GraphQL

  Based on my experience, this is the biggest feature enhancement over Pelican. GraphQL is a query language that you can embed within your templates in order to query your site for data. This is a big improvement over how site data is managed in a static site generator. The query language gives the user fine-grained levels of control of the data that each template components depends upon.

• MDX

  The blog uses MDX for markdown parsing. This is extended version of markdown that allows you to blend JSX and markdown in the same file. The only issue I had came from trying to incorporate Latex into my posts (discussed below). For Latex rendering, MDX depends on the remark-math module. As I explain below, I had some compatiblility issues between remark-math and other gatsby plugins.

• Latex Integration (Katex, Remark)

  This was the biggest challenge I faced in porting the site. I used the Katex library to parse Latex in Javascript. There is gatsby plugin for this. What I discovered through trial and error is that this plugin needs to be updated to reflect the latest changes in another plugin remark-math. I had to manually apply changes and fixes described in these two issue threads; 1 and 2. Essentially, I built a local verion of the gatsby-remark-katex plugin that includes code changes that will hopefully appear in a future release version of the plugin.

• Syntax Highlighting (Prism)

  The site uses Prism for syntax highlighting. Overall it works well. One of the nice features is the line highlighting in code snippets. For example, I can specify the specific lines that I want to emphasize in a snippet

  istrike = 0.04
  notional = 50000
  start = today()
  end = start + int(0.246575*365+0.5) # This is from Quantlib unittest
  var_swap = VarianceSwap(SwapType.Long, 0.04, 50000, start, end)
  

  The only remaining challenge is for me is to add Cython to the recognized language in Prism. This can be accomplished using the language extend api. I just need to get it done. In Prism's defence, highlighting support for Cython is poor everywhere.

• Publishing

  Publishing is fairly straightforward using the gh-pages node plugin.

Conclusion

Overall, I think porting the blog was a success. If nothing else, it gave me the opportunity to learn more Javascript. The Latex issue I encountered is typical of plugin-based systems, nothing unique to Gatsby. There may be some bugs in the near future, but hopefully I can get them fixed soon.