Migrate to Hugo from Jekyll

I had used Jekyll to generate this site for 1+ years. However, recently generating site took more than 10 seconds due to increasing site contents; this was really stressful when I like to check the generated site continuously (e.g. style updating).

Hence, from this article, I have migrated to Hugo, and this fast static site generator can build my site less than 1 second! Migrating to Hugo from Jekyll is not so difficult because there are many useful information on the Internet such as:

• Migrating to Hugo From Octopress
• Migrate to Hugo from Jekyll
• spf13/spf13.com

In particular, spf13/spf13.com, a repository of Hugo creator's website, is practically useful to understand what we have to do.

MathJax+Markdwon issue

In the TeX syntax, we frequently use _ (underline) to render subscripts. However, at the same time, underline also indicates italic font in Markdwon. This situation raises a mis-converting issue; when Markdown is first parsed, MathJax might not understand TeX formulas correctly.

One solution for the issue is introduced in Hugo official support page: MathJax Support - Issues with Markdown

OK, we can easily fix the issue, but I don't like this solution. Putting backticks (` ) at the head/tail of every TeX code is so annoying...

On that point, Jekyll is great; in Jekyll configuration, we can use kramdown (pure-Ruby Markdown convertor) as a Markdown parser, and it can correctly handle MathJax+Markdown mixed files.

Using kramdown as a Hugo Markdown convertor

Here, I have another solution. It just to use kramdown as a Hugo Markdown convertor. Usually, Hugo requires us to put articles in content/ directory, and it automatically converts them to .html files. However, we now create a intermediate directory like _content/.

First, I create Rakefile and define a task as:

require "kramdown"

namespace :converter do
  task :content do
    Dir::glob("_content/*").each do |src|
      # destination path will be "content/{filename}.html"
      dst_path = src[1..-1].sub(/(.*)\.md/, '\1.html')

      open(dst_path, "w") do |dst|
        content = open(src) { |f| f.read }

        # keep front matter
        content = content.sub(/(---.*---\n)/m, "")

        content = embedding_tweet(content)

        # write with concatenating front matter
        dst.write($1 + Kramdown::Document.new(content).to_html)
      end
    end
  end
end

As I mentioned before, kramdown can correctly handle MathJax+Markdown mixed files in default setting, so it works.

Next, you just need to run converter before running Hugo server: rake converter:content

After the rake command, we do not have to think about Hugo Markdown converter. Even if there are some mixed articles, hugo server will generate your site correctly based on html files obtained by the rake command.

Note that we can use this technique for the other preprocessing such as sass compiling. For more detail, you can see my actual Rakefile.

Conclusion

I have shown you another solution for the MathJax+Markdown issue. However, since my technique requires to run preprocessing, we cannot take advantage of fast incremental building from Hugo.

If we really want to fix the issue, we have to tackle Hugo original Markdown parser and develop Go implementation of kramdown.

  Share

Tweet

  Categories

Programming

  See also

2017-06-26

Deploying Static Site to GitHub Pages via Travis CI

2017-05-28

Hugo meets kramdown + KaTeX #gohugo

2017-04-30

Moving to GitHub Pages

  More

Last updated: 2022-06-11

  Author: Takuya Kitazawa

Takuya Kitazawa is a freelance software developer based in British Columbia, Canada. As a technologist specializing in AI and data-driven solutions, he has worked globally at Big Tech and start-up companies for a decade. At the intersection of tech and society, he is passionate about promoting the ethical use of information technologies through his mentoring, business consultation, and public engagement activities. See CV for more information, or contact at [email protected].

  Now   Gift a cup of coffee

  Disclaimer

• Opinions are my own and do not represent the views of organizations I am/was belonging to.
• I am doing my best to ensure the accuracy and fair use of the information. However, there might be some errors, outdated information, or biased subjective statements because the main purpose of this blog is to jot down my personal thoughts as soon as possible before conducting an extensive investigation. Visitors understand the limitations and rely on any information at their own risk.
• That said, if there is any issue with the content, please contact me so I can take the necessary action.