How to migrate programming blog from Wordpress to Jekyll

Codever Logo

(P) Codever is an open source bookmarks and snippets manager for developers & co. See our How To guides to help you get started. Public bookmarks repos on Github ⭐🙏

In this post, I will give my two cents on migrating a programming blog from Wordpress1 to Jekyll2, namely I will list and detail the main steps I took for migrating Codepedia.org.

Why?

Well, there were pains - I was experiencing performance issues (caused mainly by memory shortages on a 4GB machine) with the virtual private server from GoDaddy, where I used to host both Podcastpedia.org and Codepedia.org. Codingpedia was developed initially with Wordpress1, which I still think is a great tool, if you want to quickly start a blog and don’t have programming experience, but it kinda requires a LAMP2 stack, which it’s kinda performance killer from a number of visitors forward. Of course you can always add more hardware to support the website, but that has a limit too. Limited was also the budget I was ready to spend on hosting, by today’s standards.

Leaving Wordpress

To export Wordpress to Jekyll I used the Jekyll Exporter plugin3, which with one click should convert all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Jekyll. Well for it did not work with the click, but the salvation came from its command-line usage:

php jekyll-export-cli.php > jekyll-export.zip

After seeing what got generated by the plugin, my approach for the migration was to first find a right Jekyll theme, you’ll find out below which one, and then add and adjust one by one the artifacts generated.

Exported posts

The posts are exported into the _posts folder and I could use them as they are:

  • they have permalinks set (very useful for the multi-author blog migration)
  • categories and tags - used later in Jekyll
  • they are in html code and are not converted to markdown

Exported pages

For page export a folder and an .md file is created with the page name, but I prefer creating a folder in the site’s root for each page, and place an index.html or index.md file in each page folder4.

Exported images

The images are exported into the wp-content directory under the root directory, and have the same tree structure as in Wordpress, so they are correctly referenced and one does not need to modify anything:

├── index.html
├── package.json
.........
└── wp-content
    └── uploads
        ├── 2013
        │   ├── 07
        │   │   ├── Template-150x150.png
        │   │   ├── Template-285x300.png
        │   │   ├── Template-360x270.png
        │   │   ├── Template.png
        │   │   ├── baby_working1-150x150.jpg
        │   │   ├── baby_working1-300x224.jpg
        │   │   ├── baby_working1-624x467.jpg
        │   │   ├── baby_working1.jpg
        ........
        ├── 2014
            │   ├── 01
            │   │   ├── 1-1-show-references-150x150.png
            │   │   ├── 1-1-show-references-300x251.png
            │   │   ├── 1-1-show-references-604x270.png
            │   │   ├── 1-1-show-references.png
            │   │   ├── 1-execute-jetty-run-from-eclipse-1024x737.png
            │   │   ├── 1-execute-jetty-run-from-eclipse-150x150.png
            │   │   ├── 1-execute-jetty-run-from-eclipse-300x215.png
            │   │   ├── 1-execute-jetty-run-from-eclipse-604x270.png
.........

The custom styles were not exported

Hello Jekyll

So what is Jekyll, exactly?

“Jekyll is a simple, blog-aware, static site generator. It takes a template directory containing raw text files in various formats, runs it through a converter (like Markdown) and our Liquid renderer, and spits out a complete, ready-to-publish static website suitable for serving with your favorite web server. Jekyll also happens to be the engine behind GitHub Pages, which means you can use Jekyll to host your project’s page, blog, or website from GitHub’s servers for free.”5

Hosting

I decided to host the website on GitHub Pages6, because is currently free, hosted directly from the GitHub Repository. Just edit, push, and your changes are live.

It matches perfectly our vision of sharing coding knowledge

Finding a theme

The first task was to find a proper Jekyll Theme7 - I was looking for one that was simple, neat, responsive, open-source and had good post samples for code, images and video embedding. After some research I got lucky and found Neo-HPSTR Jekyll Theme, thank you Aron, that fulfils all of the requirements and on top of that has nice social sharing features.

Code embedding

One concern that I had, was what would happen with all the code from the posts, because you know it is a programming blog… Well the exported code snippets are maintained, that is they surrounded and escaped correctly in <pre><code>...</code></pre> tags

<pre><code class="xml">&lt;div id="flags"&gt;
    &lt;a href="?lang=en"&gt;
        &lt;img alt="en" title="English" src="&lt;c:url value="/static/images/flags/en.png"/&gt;"&gt;
    &lt;/a&gt;
    &lt;a href="?lang=de"&gt;
        &lt;img alt="de" title="German" src="&lt;c:url value="/static/images/flags/de.png"/&gt;"&gt;
    &lt;/a&gt;
    &lt;a href="?lang=fr"&gt;
        &lt;img alt="fr" title="French" src="&lt;c:url value="/static/images/flags/fr.png"/&gt;"&gt;
    &lt;/a&gt;
    &lt;!--  TODO uncomment when the translation in Spanish is available
    &lt;a href="?lang=es"&gt;
        &lt;c:url value="/static/images/flags/es.png" var="url_flag_image" /&gt;
        &lt;img alt="es" title="Spanish" src="${url_flag_image}"&gt;
    &lt;/a&gt;
    --&gt;
    &lt;a href="?lang=ro"&gt;
        &lt;img alt="ro" title="Romanian" src="&lt;c:url value="/static/images/flags/ro.png"/&gt;"&gt;
    &lt;/a&gt;
&lt;/div&gt;</code></pre>

so they show nicely in the browser:

<div id="flags">
    <a href="?lang=en">
        <img alt="en" title="English" src="<c:url value="/static/images/flags/en.png"/>">
    </a>
    <a href="?lang=de">
        <img alt="de" title="German" src="<c:url value="/static/images/flags/de.png"/>">
    </a>
    <a href="?lang=fr">
        <img alt="fr" title="French" src="<c:url value="/static/images/flags/fr.png"/>">
    </a>
    <!--  TODO uncomment when the translation in Spanish is available
    <a href="?lang=es">
        <c:url value="/static/images/flags/es.png" var="url_flag_image" />
        <img alt="es" title="Spanish" src="${url_flag_image}">
    </a>
    -->
    <a href="?lang=ro">
        <img alt="ro" title="Romanian" src="<c:url value="/static/images/flags/ro.png"/>">
    </a>
</div>

On Wordpress I was using a syntax highlighter with line numbers and everything, but somehow I find it neater in Jekyll

When writing new posts I will definitely use one of the methods suggested in How to insert and highlight code in Jekyll blog post on Codepedia.org and if want to publish on Codepedia.org I recommend you use them too.

Migrate custom CSS

There are some custom styles from the old Wordpress theme I’d like to user further. Because Jekyll supports natively SASS8, I just moved the style to _wordpress.scss file and imported it into the _main.scss, which combines all the SASS files.

......
@import "dl-menu";
@import "page";
@import "wordpress";
.....

Multiple authors support

This was very important because of of our Coding Friend Program It is pretty well supported in Jekyll, once you are ready to get your hands a little bit dirty - for more details see my post How to handle multiple authors in Jekyll

Comments

Because I was uing Disqus for the comments, migrating them was straightforward - I just changed disqus_shortname in _config.yml. By default comments appear on all post and pages. To disable commenting on a post or page, add the following to its YAML Front Matter:

comments: false

You might also want to check Jekyll Installation Instructions from Disqus

Feed

It uses the theme’s own Atom implementation, which I adjusted for multiple authors - don’t forget to subscribe to it here

Another possibility would have been to use Atom (RSS) feeds for GitHub Pages9, which can automatically create an Atom feed for the Jekyll blog deployed on GitHub Pages.

Sitemaps

Unlike custom feed generation, I used Sitemaps for GitHub Pages10, which can automatically create sitemaps for the blog

If you decide you want to create your own sitemaps, a good starting point is Building a Better Sitemap.xml with Jekyll

Benefits

So far I am glad I did this move. Here are a summary of the benefits I reaped til now:

  • it just feels right, like it’s better suited for a programming blog
  • the generated static website is light years faster than what I had before
  • free hosting; edit, git push and is live via GitHub Pages
  • open source which is a perfect match with our mission
  • uses markdown11 which is very easy to read and write, especially for a programming blog
  • provides native SASS support8

I hope you’ve found this useful and after you will have migrated to Jekyll, join our Coding Friend Program so we can easier republish your articles or, even better, do it yourself with a pull request.

References

  1. https://wordpress.org/ ↩ ↩2

  2. https://jekyllrb.com/ ↩ ↩2

  3. https://wordpress.org/plugins/jekyll-exporter/ ↩

  4. https://jekyllrb.com/docs/pages/ ↩

  5. https://jekyllrb.com/docs/home/ ↩

  6. https://pages.github.com/ ↩

  7. https://github.com/jekyll/jekyll/wiki/themes ↩

  8. https://jekyllrb.com/docs/assets/ ↩ ↩2

  9. https://help.github.com/articles/atom-rss-feeds-for-github-pages/ ↩

  10. https://help.github.com/articles/atom-rss-feeds-for-github-pages/ ↩

  11. https://daringfireball.net/projects/markdown/ ↩

Subscribe to our newsletter for more code resources and news
About the Author

Adrian Matei (aka adixchen)

Adrian Matei (aka adixchen)
Life force expressing itself as a coding capable human being
Follow @adixchen
Read More

routerLink with query params in Angular html template

routerLink with query params in Angular html template code snippet Continue reading

How to not select attribute in mongoose schema

Published on April 21, 2023

Calculate life span and age in years in javascript/typescript

Published on March 31, 2023