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.