Zola migration - #97
Draft
maxkapur wants to merge 12 commits into
Draft
Conversation
Diff here shows an example. Main changes: - yml to toml - sort_order and hidden (my custom attributes) move to [extra] - permalink becomes an entry in aliases
Just to understand how to do this. Will likely need others
This shows that the /assets/ path maps correctly
maxkapur
marked this pull request as draft
May 23, 2026 17:02
Seems like the GH upload pages action depends on the normal version of tar
Owner
Author
|
Before I get too attached to this, want to remind myself that Hugo has native support for KaTeX server-side rendering: https://gohugo.io/functions/transform/tomath/ You have to use a specific tag like |
maxkapur
added a commit
that referenced
this pull request
Jul 25, 2026
Here goes nothing--big merge to migrate from Jekyll to Hugo. Contents below are the to-do list from the github issue for posterity. ---- Yesterday we fiddled with Zola (#97) and today we fiddle with Hugo. This WIP includes ~~the same demo posts/pages from before~~ all posts and pages. Trying to maintain clean separation between the theme and content. TODOs (many copy/pasted from that PR since they still apply): - [x] KaTeX server-side rendering: See example in formats masterpost. - [x] `$$ ... $$` delimiters will need updating to use the custom shortcode. We can regex this - [x] Try to apply the IBM Plex Math font to rendered KaTeX for overall cohesion. Is it possible to avoid the KaTeX fonts and CSS entirely? - [x] Check formatting of the formats masterpost closely for parity. - [x] Pagination. Set it up before fiddling with CSS! - [x] Header/footer, can we port the `sort_order` custom functionality? Yes! `weight` key - [x] Appropriate handling of `hidden: true` posts. See comments in `migrate.py`. The weird convention I evolved on the Jekyll site was: - [x] For standalone pages, hidden means "don't include it in the menu/navbar." In Hugo, I set it up so instead *inclusion* in the navbar is explicit, by setting `menus = ["main"]` in frontmatter. The `params.hidden` key is dropped in the migration. - [x] For posts, hidden means "don't include it in the list of posts on the home page." On the new site, I think I'm going to show just the 5 most recent post titles (without content) on the home page. We retain the `params.hidden` key, and will use it to mean "suppress this from the home page." They can still show in full on `/posts` which will include previews. The old "browse" view will go away or perhaps be relegated to the styled atom feed. - [x] Old pages also had `katex: true` frontmatter element to indicate pages where it's needed, but migration script flagged that I was actually quite inconsistent in using this. Probably we can just drop it since katex CSS is needed on the homepage anyway and it'll be in cache. - [x] Update `/colophon/` :) - [x] Update README - [x] CSS migration. I would prefer to get away from Sass. The definitions should be easy to port. But let's see if we can structure the new CSS in a way that's easier maintain, e.g. https://jacobb.nyc/writing/how-i-write-css-in-2024. Scaffold is there but I haven't actually written the styles. Problems I have spotted: - [x] Line height variance when footnote - [x] Weird paragraphing spacing when list elements have multiple paragraphs - [x] Done, but needs verification: Support legacy URLs for pages and posts. See CLS Korea for an example of how the `aliases:` frontmatter field works and note interaction with Jekyll's `permalink:` (which we are now going to implement as an aliases). - [x] Make sure that posts and pages use the same template, handling presence/absence of date information appropriately. This was annoying to maintain separately in previous version. - [x] Review licensing. CC license in the repo root is more appropriate for content than code; we might want to apply a separate license to the theme. - [x] Any weird interaction with DNS path forwards or other GitHub pages sites mounted on subpaths? WIP; see Python script to query repos with pages from GitHub API - [x] Relative link syntax - [x] Atom/RSS feed location--will it resolve at the same path? If not, can we clone it to that path to support legacy subscribers? Same path; built custom Atom template since Hugo uses RSS 2.0 by default - [x] Atom/RSS feed unique post IDs. See if we can make this a permanent part of frontmatter - [x] Expand lint steps. Investigate https://discourse.gohugo.io/t/tutorial-how-to-check-broken-links-in-hugo/54750 - [x] Check posts that have KaTeX named anchors ("tags"?) and see if there are any internal hyperlinks that broke - [x] Favicon. Also include in Atom `<icon>`: https://validator.w3.org/feed/docs/atom.html - [x] Understand how Hugo separates summary from content. It seems to respect the `<!--more-->` separator, but not my convention of omitting it when the post is supposed to be its own summary (i.e. appear in full on the homepage) - Easy workaround is to set `summaryLength = 99999` in settings so that the automatic summary for posts without the delimiter is just the whole post - [x] Some `<!--more-->` separators need manual audit: I included it inline in some paragraphs to cut off a footnote (footnotes styled weird on the old homepage). Hugo will only respect the separator if it's on its own line, and unclear how it will behave with footnotes. Investigate - [x] Work around surprising behavior where if a post has a date in filename and in frontmatter, this causes the *slug* to parse to null. Bug affects me on the P&B interview writeup+local mirror which have the same date in filename but custom datetimes in frontmatter to force a sort order: gohugoio/hugo#14971 - Option A: Explicit slug on those posts (can add to migrate.py) - [x] Option B: Forbid explicit dates (check added to `migrate.py`) and use weight to break ties in sort order - [x] "Read more" link - [x] Menu configuration to make it easy to control links in header vs. footer nav `migrate.py` script, grown slowly during this process, automates *most* of the migration steps. Here are a few migrations I did manually: - [x] Set dates and lastmods for the plain pages. Unlike posts, these never had date info in Jekyll so I pulled it in from git. - [x] Make image references in `content/posts/2025-12-19-perfect-match-integer-programming.md` relative. (For some reason I used absolute URLs generated via `{{ site.baseurl }}` to embed images in this post and no others.) - [x] Remove stray Jekyll comments in about.md, colophon.md, and projects.md pages - [x] Correct inline KaTeX in `content/posts/2024-09-24-bimatrix-game-equilibrium.md` (paragraph beginning and ending in inline KaTeX regex matched as display KaTeX) - [x] Convert redundant dates to weights (Option B above) Ideas that can happen after migrating: - Move images into directories alongside the content that references them instead of `/static/assets/images`. - Atom feed style - Sitemap style (currently, due to pagination, there is no easy way to find the URL for a post by ctrl+Fing its title in the website)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Just messing around with a Zola migration. Only copied a few posts and pages into this version of the site; lots of posts will need manual attention to migrate. Adding issues here as I think of them:
{{ site.email }}don't work for content pages in Zola (only works in templates); you need to define shortcodes for this (seemailto()example)$$ ... $$delimiters... Probably we can still make it work but server-side compilation is a bit tricker. Example from a template that does it: https://github.com/aterenin/academic-paper/blob/eb68d9364d8e9d2f960e38acfe8b1aa276b79277/.github/workflows/deploy.yml#L44 I would prefer to use Deno or something to execute the JS locally and avoid the Node dependency. Local builds and GH action builds should work the same waysort_ordercustom functionality?hidden: trueposts. Maybe they should become pages in the end? Part of the motivation for that, IIRC, was to be able to render the formats masterpost as a post (not a standalone page) to make sure the styles were cascaded in the same way. But the current Zola scaffold uses the same template for posts and pages (plan is to just add conditional logic to account for different frontmatter), so this might not be necessary.