WordPress to Quarto Migration

markdown
quarto
personalproject
Author

Jisell Howe

Published

November 14, 2022

Three years ago, I made a plan to create a portfolio and blog website with a custom domain. It was late December of 2019 when jisellhowe.com was first launched on WordPress.

I set up everything to make it happen as quick as possible (WordPress site, backup service, hosting service, plugins, etc.) While I felt accomplished at the time, I didn’t realize then that I would later despise all of it.

Feeling overwhelmed by the WordPress editor and the guilt of maintaining (paying for) a site that I had largely avoided posting to after a while, I wondered if I would ever find a more cost effective and streamlined solution.

It turns out I have, and I came across it by chance from a LinkedIn post.

At first, I thought it was too good to be true. What is Quarto? How can it connect to GitHub? Does that really result in a website that is close to being free to maintain?

However, upon investigating further, I was able to migrate from WordPress and a paid hosting plan to Quarto and GitHub pages with a custom domain at a significantly lower cost.

There are some key steps I took to make this a reality.

  1. Set up a folder in a web browser called “Website Migration.” It really comes in handy in saving pertinent website links mentioned below.

  2. Review a webinar and corresponding presentation on how to get started with Quarto. Save these links to the folder created in Step 1.

  3. Exploring a method of exporting static HTML from my WordPress site seemed to be a bit of a dead end. What I ended up doing to migrate all my existing posts was the following:

    • Use the workflow of creating a Quarto blog post and then copy/paste all the text from the “preview” of my WordPress posts into RStudio. Doing so preserves all or most of the formatting. I did this for each post. Yes, it did take a little while.

    • Save each picture with a numbered prefix in the same folder as the post. I put references to myself in my post text (i.e. “IMG1”), so I knew where to put my images.

    • Remove links to other blog posts in the blog post content for now. Or, make note of them for later, so they can be linked properly once the new website is up. I did this because I didn’t know the exact website links I’d have once I got it all onto GitHub.

  4. Set up a repository on GitHub pages.

  5. Configure GitHub and the Quarto YAML file to have files go to Docs.

  6. Download/Configure GitHub Desktop, so it talks to the repository you created on GitHub Pages.

  7. Once all posts are migrated, render with Quarto and publish it to the basic GitHub Pages site you have without the custom domain yet (USERNAME.github.io).

  8. Look at the DNS settings of the custom domain at the place where you bought it. For me, it was within a portal at BlueHost. Add DNS information (A, AAAA, CNAME, and later TXT for verification) to the DNS settings in the portal where you bought the domain (i.e. BlueHost). I did it in multiple ways, so my domain with “www” in front (subdomain) and without it in front (apex domain) would both work properly.

    Here is a simplified table of the kinds of DNS records you’ll need to have with respect to the GitHub documentation.

DNS Record Type Host Record Points To/Value
CNAME www USERNAME.github.io
A @ See GitHub for IP addresses to add
AAAA @ See GitHub for values to add
TXT _github-pages-challenge-USERNAME.example.com See GitHub for Value
Important

Make note of the DNS records referenced in the table and links above in case you need to add them again. In my case, I had to configure them twice because cancelling my hosting plan wiped out all the DNS settings for my domain, including the records I had personally added. I had to watch for the DNS settings to propagate again after doing so. Having these DNS settings exactly right will allow GitHub to recognize the custom domain properly.

  1. Go to the settings part of GitHub pages to add the custom domain. It should then generate the CNAME file on the GitHub side, so the two places talk to each other. Once GitHub considers it correctly configured, check the box to enforce HTTPS.

  2. Verify DNS settings globally in a variety of ways (A, AAAA, CNAME, and TXT). Once you see the correct values show up for what you set in your DNS settings earlier, the website is propagated globally. The TXT one especially showing up correctly allows for further verifying that custom domain on your GitHub account for security purposes.

  3. Cancel any hosting plan as now the custom domain is verified and cleared to work with GitHub Pages. Keep the domain itself. Just cancel the hosting plan.

You are now seeing the results of my Quarto blog with a custom domain that was created with RStudio and GitHub Pages! Is it perfect? No, not quite. I am still learning how to incorporate various Markdown techniques and YAML configurations to make the most of my new blogging experience.

There are also some things that do not make this new site 100% equivalent to the old one:

No comments on individual posts or any sort of way to handle email from the website.

This is fine because sometimes I got random comments to “approve” before, and I wasn’t really interested in continuing that. I also wasn’t interested in any implications in “collecting user data” just to get a subscribe feature working. I am able to immediately link to all my social accounts in my blog.

No scrolling or fancy theme effects or plugins.

This is fine because I didn’t like paying for themes and plugins that would eventually break. I didn’t like placing “short codes” in the typical places where certain website elements would live in WordPress. It made it that much more of a challenge to troubleshoot things later. I still don’t know why some of my “published” blog posts disappeared from the front end of my old WordPress site.

In contrast, this Quarto blog has been so easy to troubleshoot any issue. Even the GitHub part wasn’t too bad once I figured out what needed to happen. I know the purpose of just about every file, each setting, and what it does. In addition to it being very easy for the whole to thing build and deploy, I am impressed with the aesthetic options. I paid for a WordPress plugin to make my blog posts show up in a certain layout, and Quarto offered a very similar aesthetic right off the bat for free.

No SEO tools.

This is fine because it’s a personal blog/portfolio. Even though I did see the value of the SEO plugin I had, I don’t necessarily care that much if my personal website/blog is not 100% optimized for search. That said, I can make use of the editing tools in my IA Writer Markdown editor. IA Writer offers “Syntax Highlighting” tools to help spot weak verbs, redundancies, and more. I know that’s not the same as SEO, but since I really only plan to post blog posts and links from a social platform, I’m not all that concerned. Plus, I could do with a little less judgment from those red, yellow, and green emojis in the Yoast SEO app anyway. If you use Yoast, you know exactly what I’m talking about.

No automatic website backup services.

This is fine because now my rendered files are on GitHub pages. I can also easily place any of my Quarto files there or even pursue something like Dropbox etc. Also, for some reason, I kept having failed backups with my WordPress site anyway. To pay a significant amount of money for something to fail and not really have time to fix it is the major reason why I scaled so far back on what I needed in a website.

Throughout this migration process, I have learned so much on what the most critical parts are in creating a website. I can’t say I had the same experience with WordPress because there was so much automatically done on the back end that resulted in a ton of bells and whistles that I didn’t really need. WordPress certainly has its place, but it is too much for my needs at this time. In the end, this was an excellent project that resulted in a significantly cheaper alternative for managing a website. There is also a huge sense of accomplishment from actually figuring out how to do it.