Skip to content

Zola migration - #97

Draft
maxkapur wants to merge 12 commits into
masterfrom
maxkapur.github.io-zola
Draft

Zola migration#97
maxkapur wants to merge 12 commits into
masterfrom
maxkapur.github.io-zola

Conversation

@maxkapur

@maxkapur maxkapur commented May 23, 2026

Copy link
Copy Markdown
Owner

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:

  • Jekyll interpolations like {{ site.email }} don't work for content pages in Zola (only works in templates); you need to define shortcodes for this (see mailto() example)
  • KaTeX syntax with $$ ... $$ 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 way
  • Check formatting of the formats masterpost closely for parity.
  • Header/footer, can we port the sort_order custom functionality?
  • Appropriate handling of hidden: true posts. 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.
  • 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
  • Change post path to match what we had before if possible? Right now Zola expects titles to be unique but this isn't true (but date+title is unique as serves as the Atom post ID)

maxkapur added 9 commits May 23, 2026 10:28
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
maxkapur marked this pull request as draft May 23, 2026 17:02
maxkapur added 3 commits May 23, 2026 12:04
Seems like the GH upload pages action depends on the
normal version of tar
@maxkapur

Copy link
Copy Markdown
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 {{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }} instead of $$ ... $$ delimiters but I was planning on changing the delimiters anyway, and this will integrate fully with the build/preview loop, unlike the post-processing thing I had envisioned for Zola. Zola is a lovely little SSG but maybe this project really does require the machinery of Hugo after all.

@maxkapur maxkapur mentioned this pull request May 24, 2026
36 tasks
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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant