Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Migrate to Zola #1522

Open
senekor opened this issue Mar 11, 2025 · 7 comments
Open

Migrate to Zola #1522

senekor opened this issue Mar 11, 2025 · 7 comments

Comments

@senekor
Copy link
Contributor

senekor commented Mar 11, 2025

Benefits:

  • better maintainability
  • link checking
  • auto-reloading development server

Downsides:

  • It might be necessary to duplicate the date of the post in the front matter (in date and path), because zola doesn't support template strings for the path or something similar. (Maybe we can only have path in the front matter and extract the date from it in our scripts?)

I think we should definitely do #1511 first, for maximum confidence in the transition. There is a good chance Zola will do some things differently. Ideally, we would incrementally change the output of our custom generator, until it matches the output of zola.
@senekor senekor mentioned this issue Mar 27, 2025
Merged
@senekor
Copy link
Contributor Author

senekor commented Apr 1, 2025

At this point, I see two big blockers for making the migration a no-op for the snapshot tests:

  • Zola calls our URLs "ugly" and doesn't support them: Support ugly urls getzola/zola#840. We can preserve support for old links with redirects, but the directory structure will be different.
  • The generated heading ids for internal links are different than before. I suspect this is because we use comrak and Zola uses pulldown-cmark. I might try to migrate the custom site generator to pulldown-cmark to reduce the final diff, but I also might decide it's not worth it.

I'm thinking I could create two throwaway commits containing the normally-ignored public/ directory. Then the diff can easily be viewed in GitHub's UI, making review of the final migration step more convenient.

@senekor
Copy link
Contributor Author

senekor commented Apr 6, 2025

I'm getting closer to finishing this, the site basically builds and deploys fine. A little more polishing is required

The biggest sticking point was the URLs. Zola won't generate a page with a path slug.html, it will always generate slug.html/index.html.

I knew slug.html will reliably redirect to slug.html/, so far so good. But I wasn't sure if slug.html#section-id redirects to slug.html/#section-id. Some local testing didn't work, so I got worried. I set up GitHub Pages on my fork to test it and it works. Notice that the below link doesn't have a / before the #, but the browser will insert it when following it:

https://senekor.github.io/blog.rust-lang.org/2025/04/03/Rust-1.86.0.html#target-deprecation-warning-for-1-87-0

However this redirection absolutely does not work when using Zolas aliases feature. So it's not an option to do something like this in the front matter:

path = "yyyy/mm/dd/slug"
aliases = ["yyyy/mm/dd/slug.html"]

This front matter would work in the sense that old links to slug.html would be redirected to slug/. However, section IDs would not be preserved, so the link slug.html#some-section would then be broken, because it only redirects to slug/.

That leaves us with two possibilities:

  • Keep everything consistent with slug.html/. It looks a little funky, but whatever.
  • Keep the old posts as slug.html/ and make new posts as slug/. People could technically get confused why the URL scheme is inconsistent, but all new posts would have nicer URLs.

@Manishearth do you have an opinion on this?

@Manishearth
Copy link
Member

I generally have a slight preference for consistency but the .html/ stuff is weird.

I'm fine with either option, overall I think I have a slight slight preference for the latter one.

We could also make all of them use the new URL scheme and hardcode some specific redirect pages for the old ones, potentially via an additional codegen step.

@senekor
Copy link
Contributor Author

senekor commented Apr 7, 2025

We could also make all of them use the new URL scheme and hardcode some specific redirect pages for the old ones, potentially via an additional codegen step.

Could you elaborate how that would work? I think Zolas aliases feature does that, but sadly it doesn't preserve the #section-id during redirect.

@senekor
Copy link
Contributor Author

senekor commented Apr 7, 2025

This is what a generated redirect page using Zolas aliases feature looks like:

<!doctype html>
<meta charset="utf-8">
<link rel="canonical" href="https://blog.rust-lang.org/2015/06/25/Rust-1.1.html/">
<meta http-equiv="refresh" content="0; url=https://blog.rust-lang.org/2015/06/25/Rust-1.1.html/">
<title>Redirect</title>
<p><a href="https://blog.rust-lang.org/2015/06/25/Rust-1.1.html/">Click here</a> to be redirected.</p>

@senekor
Copy link
Contributor Author

senekor commented Apr 7, 2025

Ok, I figured out a redirect template that preserves the section id with a little JavaScript. But Zola doesn't allow overriding this template. I opened an issues about it: getzola/zola#2847

@senekor senekor mentioned this issue Apr 7, 2025
Closed
@Manishearth
Copy link
Member

We could also make all of them use the new URL scheme and hardcode some specific redirect pages for the old ones, potentially via an additional codegen step.

Could you elaborate how that would work? I think Zolas aliases feature does that, but sadly it doesn't preserve the #section-id during redirect.

We'd manually plop in HTML files that either use META redirects (assuming fragments still work with them) or JS based redirects with a META redirect fallback (if fragments do not work).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@Manishearth @senekor