Skip to content

New docs website #3132

Closed
Closed

Description

@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)

Activity

  1. Ethan-Arrowood commented on Apr 17, 2024

    @Ethan-Arrowood
    Collaborator

    🚀 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.

  2. mcollina commented on Apr 18, 2024

    @mcollina
    SponsorMemberAuthor

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

  3. anfibiacreativa commented on Apr 18, 2024

    @anfibiacreativa
    Member

    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.

  4. Ethan-Arrowood commented on Apr 18, 2024

    @Ethan-Arrowood
    Collaborator

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

  5. Ethan-Arrowood commented on Apr 24, 2024

    @Ethan-Arrowood
    Collaborator

    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 🚀

  6. mertcanaltin commented on Apr 28, 2024

    @mertcanaltin
    Member

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

  7. mcollina commented on May 3, 2024

    @mcollina
    SponsorMemberAuthor
  8. Ethan-Arrowood commented on May 3, 2024

    @Ethan-Arrowood
    Collaborator

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

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

  9. Ethan-Arrowood commented on May 3, 2024

    @Ethan-Arrowood
    Collaborator

    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.

  10. pinned this issue on May 7, 2024
  11. Ethan-Arrowood commented on Aug 22, 2024

    @Ethan-Arrowood
    Collaborator

    @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.

  12. KhafraDev commented on Aug 22, 2024

    @KhafraDev
    Member

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

  13. vramana commented on Oct 20, 2024

    @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.,

  14. Ethan-Arrowood commented on Oct 21, 2024

    @Ethan-Arrowood
    Collaborator

    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!

  15. avivkeller commented on Jul 14, 2025

    @avivkeller
    Member

    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)

  16. GypsyS44 commented on Aug 11, 2025

    @GypsyS44
  17. Ethan-Arrowood commented on Aug 11, 2025

    @Ethan-Arrowood
    Collaborator

    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 😄

  18. axetroy commented on Apr 18, 2026

    @axetroy

    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.

  19. teesodza7244 commented on May 14, 2026

    @teesodza7244
  20. unpinned this issue on Jul 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions