TPA-RFC-37: Lektor replacement

consider a replacement, what that entails, what we could use for this, and whether it's worth it. see TPA-RFC-37 for drafting...

added Backlog label

assigned to @anarcat

mentioned in issue #28 (closed)

mentioned in commit tpo/tpa/wiki-replica@213ce599

mentioned in commit tpo/tpa/wiki-replica@2c4f5add

I think one of the bigger requirements for our SSG is going to be flexibility, whether that be through plugins, or an un-opinionated SSG that lets us structure content however we need to.

• A lot of the page redesigns require plugins to make lektor work the way we need it to
• i18n support becomes less important if we can implement it ourselves
• templates are easier to migrate if we can bring our own templating system (jinja has a cli tool)

mentioned in commit tpo/tpa/wiki-replica@ad74e514

unassigned @anarcat

@kez could you add those requirements to the wiki page?

also feel free to take this ticket if you want to tackle this... you should also document your metalsmith experiences here as well at some point. :)

also note overlap with TPA-RFC-38: wiki service (tpo/tpa/team#40909) itself overlapping with the documentation discussion, which should probably be moved ... somewhere...

marked this issue as related to tpo/tpa/team#40909

i spent some time over the weekend trying to see if i could make metalsmith build lektor sites, and i got pretty close. the proof of concept is over at https://gitlab.torproject.org/kez/metalsmith-lektor

the idea is that we could use metalsmith to build our lektor sites, while we slowly migrate away from lektor. i think it's possible, but it would take a decent amount of dev time. i have no time estimate, but i wanted to mention it here in case we decide that's useful.

I was talking with @lavamind about how Lektor is slow when you edit the community site and how easier and funnier it would be to have something like Hugo to Zola to power the Tor Project's websites, so he suggested me to comment on this issue about Hugo (which is the one I know the most) and how it could help.

I've used hugo a couple of times in the past, and it fast and works well even with sites with a lot of content. I'd be curious to see what kind of plugins you need to make the redesigned pages work, but hugo can probably check a couple of boxes @kez mention earlier.

• it has builtin i18n support.
• it supports theme out of the box, so the lego could be rebuilt for hugo with reusable partial, components, and a basic layout for every website.
• It builds really fast and has fast incremental live reload when you develop the website or the content.
• There's no such thing as plugins, but the template engine is pretty flexible and powerful, so generally you are able to do what you want and reuse the common bits when necessary
• It's a single binary packaged in most linux distributions, so no need to install python dependencies or package them
• It's also available as a docker container, so it's pretty easy to use in a CI job.

The downside :

• It doesn't support custom templating engine
• No matter the choice, it'll mostly imply to rewrite all the theme bits

Thanks for mentioning hugo! I'll definitely look into it, I know we use it for the research site.

Thanks! The two main features we need the most are i18n support and fast building when there is a lot of content.

added Roadmap::Future label and removed Backlog label

mentioned in issue blog#40049 (closed)

added TPA label

I recommend Docusaurus, not only for creating documentation, but for generating static sites as well. The pages load blazingly fast. It is used by many, such as for Rancher, K3s...

Advantages:

• Supports Javascript and Typescript, one of the two must be chosen.
• Documentation can be separated into versions (Versioning).
• Support for i18n, integration with CrowdIn is recommended.
• Uses markdown, so should be relatively easy to migrate.
• Content is structured in a simple way (easier fix for issues like this one).
• Table of contents is generated automatically (with anchor links, would fix this issue).
• The generated content works smoothly on mobile devices. No more design issues.
• Although Tor already has its own blog, Docusaurus generates a blog with easy-to-manage tags, authors and truncation. (Can be disabled)
• Admonitions.
• Code snippets organized in tabs, handy copy button and syntax highlighting.
• MDX plugins.
• Diagrams.
• Swizzling components for deeper customizations.
• Variety of ways for SEO.
• Documentation search with Algolia (and many other options).
• Easy contributions by community with the ‘Edit page’ link.
• Fewer modifications (themes) needed than Hugo.
• Entries can have a ‘Last updated by $author on $date.’ (Can be deactivated).

Disadvantages:

• May not be as fast as Hugo when building.
• Translation of content is recommended to be by full markdown files, to avoid loss of context and not in strings (as it is currently).
• The last modification of the entries may not be to the liking of some community contributors, who may not want their name displayed publicly at the end.

Algolia allows you to host your own content indexer, to avoid using theirs.

Also, it is easily configured to prevent building if something breaks (such as broken links or duplicated routes), this would allow cleaner builds with community contributions.