You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Reacted by Carlos Fuentes, Bharadhwaj Reddy, Sukka and games-main
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.
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.
@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.
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.,
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!
FWIW - I've come around on using Docusaurus. I think their versioning system is fine. While a more complex, MDX component system would be really cool, it'd be a lot to build and maintain consistently. I still stand by the fact that undici's docs problems are not necessarily the site generator, and more the complexity of the API. But nonetheless I would support maybe a replatform to docusuarus if that means maintaining and contributing docs becomes simpler and easier 😄
Activity
Ethan-Arrowood commentedon Apr 17, 2024
🚀 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 commentedon Apr 18, 2024
@Ethan-Arrowood are you thinking of building a new framework, making it OSS and then use it here?
anfibiacreativa commentedon Apr 18, 2024
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 commentedon Apr 18, 2024
@mcollina , nope. just building the site for Undici.
Ethan-Arrowood commentedon Apr 24, 2024
Here is my current plan:
figmatldraw is easier)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 commentedon Apr 28, 2024
@Ethan-Arrowood I can contribute to the development of the site
mcollina commentedon May 3, 2024
Created the new repo at https://github.com/nodejs/undici-website.
Ethan-Arrowood commentedon May 3, 2024
I'm going to move new conversations to the repo.
I will also be pushing my draft work to a branch soon.
Ethan-Arrowood commentedon May 3, 2024
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 commentedon Aug 22, 2024
@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 commentedon Aug 22, 2024
If we can kill two birds with one stone, sounds great to me.
vramana commentedon Oct 20, 2024
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.xandmainbranches 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 commentedon Oct 21, 2024
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!
avivkeller commentedon Jul 14, 2025
Hey y'all! If you are willing to follow the same syntax as nodejs/node, you could make use of
nodejs/api-docs-tooling, once it's ready.(Currently, it looks like https://nodejs-api-docs-tooling.vercel.app)
GypsyS44 commentedon Aug 11, 2025
Ethan-Arrowood commentedon Aug 11, 2025
FWIW - I've come around on using Docusaurus. I think their versioning system is fine. While a more complex, MDX component system would be really cool, it'd be a lot to build and maintain consistently. I still stand by the fact that undici's docs problems are not necessarily the site generator, and more the complexity of the API. But nonetheless I would support maybe a replatform to docusuarus if that means maintaining and contributing docs becomes simpler and easier 😄
axetroy commentedon Apr 18, 2026
Please consider providing documentation for previous versions.
Due to historical reasons, we cannot upgrade to the latest version and occasionally need to refer to older versions of the documentation.
Currently, I can only clone the repository and switch to a specific version to view it.
teesodza7244 commentedon May 14, 2026