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
Copy link
Copy Markdown
Owner

@maxkapur maxkapur commented May 23, 2026

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
32 tasks
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