New docs website

[mcollina]

I think it's time to develop a new docs website.

This should be:

• fully (or mostly) statically generated
• hosted on Vercel (as part of the deal with the OpenJS Foundation for the Node.js website)
• support multiple versions (v5.x and v6.x)
• deployed from another repository (to support multiple versions)

[Ethan-Arrowood]

🚀 This has been on my mind for sometime.

I've evaluated a number of options including Docusaurus, Nextra, and more. I couldn't find any framework that really had all the features we need out-of-the-box. So... I started building it myself!

In a private repo, I have a Next.js site with MDX and Tailwind. I've wired everything up, and I figured out a way for use to have versioned docs by leveraging MDX's dynamic and extensible markdown-as-components system. Furthermore, I've leveraged the latest features of Next.js to statically generate as much of the site as possible during build time. I'm currently working on getting some base styles set up; I'm making sure it's responsive from the start too.

I've had limited time to work on this, and have also been struggling to sustainably work on open source projects. I'd be more than happy to share what I'm building and work on this in public, but I'd like to investigate crowd-funding this project so that it is sustainable for me.

[mcollina]

@Ethan-Arrowood are you thinking of building a new framework, making it OSS and then use it here?

[anfibiacreativa]

Thank you for opening the issue, @mcollina . I always see documentation as a low hanging fruit to introduce folks to OSS contributions. It's a way to break through and also learn about the technology while improving the docs. I also think that it needs a prompt from the core maintainers that they're looking forward to a refresher, because coming forward and saying "I think docs can be improved" as a newcomer to OSS can be intimidating.

[Ethan-Arrowood]

@mcollina , nope. just building the site for Undici.

[Ethan-Arrowood]

Here is my current plan:

• Implement some basic styles and write some contribution docs
• Create some rough designs (using figma tldraw is easier)
• Write a post announcing the site project
• Publish post and repo simultaneously + market on social media

As I mentioned previously, I'd really like to crowd-fund this work. I have my personal sponsorship/donation process figured out, but I'm not sure yet how to manage money for a project. I will keep investigating this and try to figure it out asap.

Stay tuned 🚀

[mertcanaltin]

@Ethan-Arrowood I can contribute to the development of the site

[mcollina]

Created the new repo at https://github.com/nodejs/undici-website.

[Ethan-Arrowood]

I'm going to move new conversations to the repo.

I will also be pushing my draft work to a branch soon.

[Ethan-Arrowood]

Design: nodejs/undici-website#1
My draft work: nodejs/undici-website#2

Didn't get as far in the styling as I would like, but I just am really struggling with time management atm.

[Ethan-Arrowood]

@nodejs/undici what are everyone's thoughts and opinions of using JSDoc comments and generating documentation from that?

Separately, we could use that for TypeScript type generation. I know many projects are finding major success doing that these days.

I've spent a little more time trying to work on the docs site, and I'm concerned of the complexity of hand writing markdown for everything (in addition to maintaining the full website).

In addition, I definitely want to produce many more examples. That is always most helpful.

[KhafraDev]

If we can kill two birds with one stone, sounds great to me.

[vramana]

I have started proof of concept for Undici website with version support using Docusaurus. Currently it's hosted on my server and here is the github repo.

I did not put a lot of effort into this. I copied the docs folder contents from v5.x, v6.x and main branches to generate the current site. I made a few adjustments so that the build doesn't break due to broken links and such. I have not focussed on design at this point.

If there is an interest from Undici team, I want to work further on this prototype. Do you have any specific things you want to see in this prototype? For example better content organization, automatic publishing whenever undici repo docs are updated, code samples in JS and TS, etc.,

[Ethan-Arrowood]

Thank you for the prototype. I think this is some good progress.

In general, I'm sure we could throw our current documentation content at any markdown site generator and it wouldn't make much of a difference from our current site. Its more about improving our content and tooling around it so it remains up to date. I really liked the composability of MDX so that we can share API references between version easy. I know from experimentation that versioned docs in Docusaurus is a poor experience. We'd immediately have out of sync docs and that would be not great as we need to maintain accurate docs across the major versions of the library.

You're welcome to continue prototyping. If you can improve upon at least some of our documentation issues, I'm sure many maintainers would be greatful!