Improving the tooling/framework used for the doc (Jekyll currently)

[bjohansebas]

I’ve been talking with @crandmck about migrating the website to a newer technology that can save us from unnecessary work (for example, copying and pasting content to make it available in other languages, improving accessibility, JavaScript logic that doesn’t add much value to the documentation content, styles like text line spacing, etc.). This is work that can very likely be handled by the framework we choose to use.

While the focus so far has been on the content rather than the technical aspects, I think it’s time to make this change so we can finally focus solely on the content.

The important thing here is to choose a tool that is strong in several aspects, such as:

• i18n
• Accessibility
• Ease of creating/modifying content
• Preferably good Markdown support

Possible technologies that could be used for this change:

• Docusaurus
• Astro Starlight
• Hugo
• Eleventy
• VitePress

With all this in mind, I’d like to invite @expressjs/express-tc, @expressjs/docs-wg, and all members of this community to help us choose a good tool for the documentation.

[UlisesGascon]

This is a bold move, and I think it's a good moment to do it 👏 👏.

I have only a small amount of experience with Hugo and Eleventy. I’ve never used Astro, Starlight, or VitePress... but I am a great fan of Docusaurus, mainly because it is widely adopted by other projects in the foundation, such as Jest. We can learn a lot from their base code (https://github.com/jestjs/jest/tree/main/website), as they also support multiple versions of their product. This is something we should consider, like express@3, express@4, and express@5... as a requirement when doing the decision.

That said, I’m not very opinionated on the framework used.

[carlosstenzel]

I like the idea of using Docusaurus too

[chrisdel101]

I honestly don’t have any experience with these documentation generators (if that’s the word for them) but they all look good. I think Jekyll I works okay, but is quite inefficient and i also dislike the copy paste ideology and would love to get rid of it!
I guess I wonder how we even start this? Would we work on it along side the prod site until it’s ready?
It’s a good and exciting discussion to have

[joeyguerra]

I feel like whoever is managing the website should just pick one and use it. So often we discuss tech when most of the time it's a matter of preference. And I feel like the person who's doing the work should be able to say what they want to use for the work. Sure, collaborate, think out loud, and give people an opportunity to discuss. But make sure to value making progress.

+1 fo Docusaurus. ;)

[bjohansebas]

The only thing I don’t like about Docusaurus is that it doesn’t provide a fallback for content when it’s not available in another language, which would mean we’d end up copying and pasting (I don’t want that). Astro Starlight does handle that fallback, I need to take a closer look at the others.

Examples of how they behave in i18n when content doesn’t exist yet.

• Astro: https://biomejs.dev/uk/guides/getting-started/
• Docusaurus: https://www.electronjs.org/es/docs/latest/tutorial/navigation-history
• Please, if you have examples of how i18n works in the other technologies, share them.

I don’t want you to take this comment as me preferring one technology over another, I’m just valuing something that I think is important, which is i18n support.

[bjohansebas]

I have been researching and creating a list of the advantages of some of them:

Docusaurus:

Pros:

• It is widely used within the foundation.
• Design/Accessibility: It has a predefined design (saves us time).
• Supports Markdown/MDX.
• Fast to compile.
• Can be deployed on GitHub Pages (no need for new infrastructure).
• It has i18n support with Crowdin (if we end up needing it).

Cons:

• It is very React-centric.
• It doesn't do fallback for content in other languages when it doesn't exist.

---

Astro Starlight:

Pros:

• Design/Accessibility: It has a predefined design (saves us time).
• Supports Markdown/MDX.
• Can be deployed on GitHub Pages (no need for new infrastructure).
• Fast to compile.
• I18n: Good support, does fallback for content when it doesn't exist in other languages (we wouldn't have to copy and paste to complete the i18n).

Cons:

• It uses Astro, which is relatively new.

---

Eleventy:

Pros:

• Fast to compile.
• Supports Markdown/MDX, Liquid, EJS, Pug, etc.
• Can be deployed on GitHub Pages (no need for new infrastructure).
• Has i18n support (Not sure if it does fallback for content).

Cons:

• It doesn't have a predefined design (We want to focus on content, not accessibility).

If I had to choose, it would be Starlight or Docusaurus

[wesleytodd]

I do not consider myself an expert in this space, so if in y'alls opinion another direction is better I am all good with that, but my vote goes to Docusaurus. I dislike the coupling to React in a general sense, but it is certainly the highest likelihood of having contributors easily on boarded to contribute.

[bjohansebas]

A brief summary of how this migration will be done, there is no start date yet. If anyone wants to expand on it, for me that's fine, but I think this is the necessary information.

1. Choose the new tool (The website captains will choose it, we still need some time)(@expressjs/docs-captains)
2. We will create a list of tasks to be done to achieve this migration, so we can divide the tasks. (@expressjs/docs-wg)
3. We will create a new separate branch (@bjohansebas)
4. Once there are changes to review, we will open a draft PR. (Anyone with write permissions will be able to do it)

Note: We will follow the same process of creating PRs, not pushing directly to the branch.