Docusaurus – infrastructure to help manage open source websites | Hacker News Reader

Docusaurus – infrastructure to help manage open source websites

docusaurus.io

58 pointsjimarcey11 comments

We've used Docusaurus on http://bucklescript.github.io and https://reasonml.github.io/reason-react/. Some highlights:

- Fast dev workflow. The dependencies are kept relatively minimal, which is very appreciated. - Very little magic. Doesn't opt you into a particular e.g. css paradigm. I personally appreciate the sweet spot where things "Just Work", but thanks to simplicity and obviousness, rather than explicitly architecting (though I'm sure the team actually put lots of thoughts into the design). - Generates clean, idempotent static output, that you can manually introspect. A small source change leads to a small artifact change. A nice consequence derived from its simplicity. - Generates static sites that work without JS, naturally. You can also progressively enhance it through regular JS. - i18n! Super grateful we didn't need to handle that ourselves.

Haven't tried versioning, but we'd love to look into that as well.

Thank you Docusaurus team =)

Thanks @chenglou for being one of our earliest adopters. You and your team really helped improve the quality of Docusaurus for launch.

I'm excited to have been involved with this project! Docusaurus already powers the documentation of Relay, React Native, Jest, Prettier, Reason-React and many more

Huge congrats to the hard work of the core team: @JoelMarcey @ericnakagawa @hectorramos and our former intern Frank Li.

Hopefully your next open source launch will be made a bit easier with this tool, and allow you to focus on writing great documentation!

Thanks @EricVicenti! And congrats to you as well, especially since you were the one who brought this idea to us back in the summer. So happy you did. :)

Why did you guys not look at/adopt gatsbyjs ?

From first look, it seems that docusaurus comes with saner and simpler defaults for a site. Gatsbyjs has to have plugins installed just to get markdown working and then grok graphql syntax to fetch data from markdown.

I wonder if that was it.

Gatsby is a great tool for documentation as well. In fact, some of our open source projects use Gatsby (e.g., reactjs.org). We feel that Docusaurus serves a bit of a different audience. Docusaurus is focused on the fastest way to document a project. We wanted to provide a really quick way to get a site running with certain core functionality that folks might find useful. We can see Gatsby and Docusaurus possibly collaborating on some features. In fact, we could see integrating/adopting parts of Gatsby into Docusaurus under the hood. That is something that is worth exploring moving forward.

Wish it supported Asciidoc. For now jbake and hugo will be my preferred choices but definitely adding this to pinboard as well.

Tangential, but: thank you for the reminder about pinboard! I came across it a while ago when busy then forgot about it. Looks useful / worthwhile.

Hi @eitland! We wanted to start off relatively simply for the launch. Support for markdown and static assets, including images, css, raw HTML, etc.

However, we are definitely looking at supporting other formats moving forward. We just want to make sure we do not complicate Docusaurus too much by doing so. Trying to find a good balance.

Hi and thanks for answering!

I already bookmarked it the other day and anyway I'm happy for everybody who contributes to open source even if I choose to use another problem.

Looks pretty neat.

Reply on news.ycombinator.com