Migrating from blogdown/Hugo to jekylldown + al-folio

Before you start

1. Work on a copy. migrate_hugo() never writes into the source site, but be conservative anyway: leave your production repository untouched until the new site builds and looks right.
2. Diagnose your toolchain:

jekylldown::check()

A local Ruby/Jekyll is optional for this migration: knitting posts only needs R, and al-folio ships GitHub Actions workflows that build the site remotely. You only need Jekyll (plus bundle_install(), below) for local previews.

Step 1 – convert the site

library(jekylldown)

migrate_hugo(
  from  = "path/to/my-hugo-site",     # blogdown/Hugo site (read-only)
  to    = "path/to/my-new-site",      # created; must not exist yet
  theme = "al-folio",                 # fetched from GitHub (network needed)
  only_referenced = TRUE,             # skip static files nothing links to
  publications = "bib",               # the default; papers.bib from the DOIs (see below)
  theme_color = "red"                 # al-folio accent color (see below)
)

The Hugo config (config.toml/.yaml) is read first and drives the migration. What gets converted automatically:

• Posts under content/post/ (also posts/, blog/) are renamed to Jekyll’s YYYY-MM-DD-slug convention. .Rmd/.Rmarkdown sources go to _source/ and will be re-knitted by jekylldown; plain .md posts go straight to _posts/. Filename slugs are kept, so post URLs are preserved.
• Front matter (YAML or TOML) becomes Jekyll YAML: layout: post is added, draft: true becomes published: false, aliases becomes redirect_from (enable the jekyll-redirect-from plugin if you use it), and Hugo-only keys are dropped.
• Page bundle resources (images next to index.Rmd) are copied to assets/img/posts/<post>/ and relative image links are rewritten.
• Menu pages. Every page referenced by the Hugo menu ([[menu.main]]) – content/publications.md, talks.md, … – becomes an al-folio page in _pages/ with the same URL (permalink) and the menu position (nav_order). A menu entry pointing at the posts section repositions the theme’s blog page instead.
• The home page. content/_index.md becomes the body of al-folio’s about.md landing page; a {{< figure class="avatar" >}} shortcode turns into the theme’s profile picture.
• Site identity. Your name (from the home page title or params.author), url (from baseURL) and description are written into _config.yml, including jekyll-scholar’s author-highlighting names.
• Theme demo content is scrubbed: al-folio’s sample posts, news, projects, books, teachings and the Einstein pages are removed, so the site starts empty instead of generic.
• static/ is copied to the site root, so absolute URLs like /images/foo.png keep working. With only_referenced = TRUE only files actually referenced by the migrated content (plus favicons) are copied – old Hugo static/ folders accumulate junk.
• Shortcodes: {{< figure >}} and {{< youtube >}} are converted; everything else is left in place and listed in the migration report. A figure’s class/width/height become a kramdown attribute list, and the CSS rules behind those classes are ported from the Hugo theme’s sass (variables resolved) into the new site’s stylesheet, so images keep their original display size instead of rendering at natural size.
• Pandoc image attributes ({width=100%}) are rewritten as kramdown inline attribute lists ({: width="100%"}).

The report printed at the end lists what is left: posts with remaining shortcodes and content not referenced by the Hugo menu (dead pages, custom layouts/) – review that list before assuming it can be dropped.

Step 2 – review the posts

Knit everything (no Jekyll needed) and read the output:

build_site("path/to/my-new-site", local_jekyll = FALSE)

Things worth checking in _posts/*.md:

• Posts using HTML widgets (plotly, leaflet, …) render as static Markdown here; widgets that relied on blogdown’s HTML pipeline need rework (e.g. save a static image, or embed the widget’s HTML manually).
• Shortcodes flagged in the report need a manual equivalent (a Liquid include, plain HTML, or just Markdown).
• Draft posts were kept with published: false; delete or finish them.
• Posts needing pandoc-only features – citations (bibliography:), footnotes, cross-references – can opt in with knit_method: pandoc in the front matter (needs rmarkdown + pandoc). New posts can also be written in Quarto (new_post(format = "qmd")), which brings those features natively via the Quarto CLI.

Step 3 – adapt the al-folio configuration

migrate_hugo() fills in your identity (name, url, description) but al-folio’s rich _config.yml deserves a pass by hand:

• Check baseurl (usually "" for a user page) and browse the config for features you want (Google Analytics, comments, …).
• Social icons live in _data/socials.yml. migrate_hugo() fills it from the profile links found in your Hugo pages (GitHub, LinkedIn, ORCID, Google Scholar, ResearchGate, StackOverflow, …), plus your e-mail address and a CV/resume PDF link – check the migration report for what was recognized and add anything missing by hand.
• Publications: with publications = "bib" (the default) the DOIs on the page are extracted and fetched as BibTeX from doi.org, so al-folio’s jekyll-scholar renders the publications page with the theme’s badges and buttons – deterministic and reproducible (the DOI registry, not a heuristic parser, is the source of truth). Publications without a DOI are listed in the report; add them to _bibliography/papers.bib by hand. publications = "html" migrates your hand-written page as-is instead – that is also the automatic fallback when the page has no DOI or there is no network, but note that a page built around raw HTML (floats, flex <div>s) rarely survives kramdown intact.
• Accent color: al-folio defaults to purple. theme_color = "red" (or any palette name / hex value) sets it at migration time, and set_theme_color() changes it later – it needs the theme gems, so on a first machine run bundle_install() and then set_theme_color().

Step 4 – preview locally (optional)

al-folio manages its plugins with Bundler, so install its gems once into jekylldown’s isolated environment with bundle_install("path/to/my-new-site"), then serve:

serve_site("path/to/my-new-site")
# ... edit _source/*.Rmd; saving re-knits and reloads the browser
stop_server("path/to/my-new-site")

After bundle_install(), build_site() and serve_site() automatically use bundle exec jekyll, so the theme’s plugins are found.

Step 5 – deploy on GitHub Pages

1. Create a repository named youruser.github.io and push the new site to it (including _source/ – it is excluded from the Jekyll build but belongs in version control).
2. In the repository settings, enable GitHub Pages with GitHub Actions as the source: al-folio’s bundled workflow (.github/workflows/deploy.yml) builds and publishes the site on every push.
3. Your R workflow from then on: new_post("Title", dir = site), write, build_site(site) (or just knit via build_site(site, local_jekyll = FALSE)), commit, push. No more two-repository setup as with blogdown – the source and the built site live in one repo, built remotely.

Migration checklist

• migrate_hugo() ran clean; skipped posts (if any) handled
• posts knit with build_site(site, local_jekyll = FALSE)
• shortcodes from the report ported
• _config.yml reviewed (identity was set; check baseurl, extras)
• pages not in the Hugo menu (report’s manual list) triaged
• _data/socials.yml reviewed (filled from your Hugo pages)
• publications page: migrated version kept, or _bibliography/papers.bib filled instead
• repo pushed, GitHub Actions build green
• old site archived (not deleted) once the new one is live