For more than four years, I used fastpages for my personal site, sayak.dev, because it offered a really easy way to do blogging. When its creator, Hamel, posted about its deprecation in favor of Quarto, I was anxious. Migrations always make me anxious. But I still continued with fastpages anyway.
But entering into this year, I decided to finally switch to Quarto for apparently no specific reason. I think I just wanted a fresh look for my website but didn’t want something too fancy. Quarto provides a perfect balance between simplicity and visual aesthetics. So, I knew I would use Quarto eventually I migrate from fastpages.
Hamel provides an excellent Quarto migration guide for fastpages users here. However, I had to take care of a few additional things to make it all work and successfully migrate sayak.dev to Quarto. In this post, I want to provide a detailed account of what I did and some personal preferential bits in the hope that it will be beneficial for someone else. Let’s get started 💫
Bit 0: Go through the original migration guide
This post assumes that you’re here because you’re migrating your fastpages website to Quarto. So, it’s a must that you first read Hamel’s migration guide in detail.
Bit 1: Install nbdev from source
While running the nbdev_migrate --path posts step, you might encounter compatibility problems. This is, luckily, easily mitigated by installing nbdev from source:
pip install git+https://github.com/fastai/nbdevBit 2: Use a separate repository for dev
I found it it’s better and more convenient to use a separate repository while doing the initial developments related to the migration. For example, my website code is hosted at https://github.com/sayakpaul/portfolio/, but I maintained another repository during the initial development.
This especially comes in handy for setting up the GitHub Actions, previewing the site with GitHub Pages, etc. This way, you can also ensure that everything looks hunky-dory before you move the contents to the actual serving repository (“portfolio” in my case).
Bit 3: Connect with GitHub Actions and Pages
Most of us (if not all) want to automate the website publishing process after a change is pushed to the serving repository. So, we should definitely set up a workflow that does this for us. Refer to the official Quarto documentation to use the recommended worflow file. It covers most use cases and it worked like a charm in my case. I didn’t have to touch a single thing in the workflow. Refer here for connecting your site with GitHub Pages.
Bit 4: Pay attention to branch names
If you used another repository as suggested in “Bit 2”, be careful about the branch names when moving the contents over to the actual repository. You need to configure a repository branch name in the following places, for example:
- The publishing worfkflow
- The “_quarto.yml” configuration
This is important to note because fastpages defaults to “master” while recent GitHub repositories default to “main”.
Bit 5: Careful copying
(Only applicable if you used another repository as per “Bit 2”)
When you’re satisfied with the migrated content, you may wish to copy over all the elements in the original repository. Some things I found to be useful to keep in mind while performing this step (assuming both the backup and original repositories are locally cloned):
- Clear out the original repository contents, first:
rm -rf * .gitignore .github. This will remove all the files and folders along with the.gitignorefile. You can add any other hidden files to the mix as needed. But don’t accidentally delete the.gitfile. - Copy over the contents from your backup repository:
cp -r backup_repo/* original_repo/ && cp -r backup_repo/.github original_repo/. Finally, copy the.gitignorefile:cp backup_repo/.gitignore original_repo/. You can copy any additional hidden file as needed, but not the.gitfile.
I know that this step is slightly involved and can potentially be made simpler.
Bit 6: Configuring a custom domain
(Only applicable if you’re serving from a custom domain)
I struggled with this step a little. After setting up the CNAME on my repository here and configuring the GitHub Pages section as shown here, my site was not getting rendered at “sayak.dev”, yielding 404 errors. After some Google searches, I stumbled upon this thread, and it solved the problem!
And that’s it! I found the Quarto resources to be really self-sufficient and the migration process was way smoother than expected, thanks to the amazing resources.