Love docusaurus and since this is a chance to surface something to the devs that isn't worth creating an issue for:
Would an "internal" mode as an option make any kind of sense? I know most people who are using docusaurus are doing so for public facing docs and they don't mind exposing github edit links.
Wondering if a flag could be set that would cater the options for corp/internal documentation somehow. I'm not a dev but I greatly appreciate being able to roll out a PRPL enabled react app that only requires me to edit MD files to adjust content.
if you dont want your docs public facing you can put a password wall on it, but thats a feature of your hosting provider (eg netlify), not so much docusaurus.
right now probably my biggest pain point is the mobile nav. i know acemarke already raised the thing about desktop right-panel subheadings disappearing on mobile, but for me the bottom right Floating Action Button menu is not intuitive for most people. i dont know how to fix it and we're just living with it for now but it is really confusing my users :(
but otherwise the customizability is great. i've been able to swizzle the blog layout to present a little more professionally https://docs.temporal.io/blog and i feel comfortable maintaining it if the interface ever changes. thanks to docusaurus (and gatsby)
i know theres a chance i dont have enough context on how to fix it but if its a react or design problem i would be interested to pitch in.. regardless thank you for stepping up to maintain docusaurus!
ok this is specific to acemarke's issue on the right sidebar stuff.. that's actually not the issue I have, my issue is more about my LEFT sidebar (the more important stuff) disappearing on mobile. i see now that it works on the docusaurus own site so i may have my own config wrong...
In the past, I've been a big fan of automatic documentation generators (jsdoc, openapi, etc), because keeping a markdown file full of function names and arguments up to date by hand was painful- but I don't like that those systems have little room for prose content like guides or tutorials.
Does Docusaurus support both types of information? The examples I've browsed so far seem to involve hand-edited API docs (example: Babel - https://raw.githubusercontent.com/babel/website/main/docs/pa...). I'd love to see a system that supported building and showing API docs and prose guides in one site, or at least allowed automated cross-linking in a way that could be kept up to date.
Do you have any good examples of this in action and showing configuration?
I've been wrestling with this as we work on finalizing the new "RTK Query" APIs for Redux Toolkit. I'd love to have some auto-generated TS API docs embedded in the hand-written Markdown pages. My biggest questions are things like how to present reasonable details on some of our typedefs, which can get insanely complex and readers don't need to see all the internal sub-types.
I recently opened up an RTK issue asking for suggestions on TS API ref integration:
You can embed doc generated by other tools in a Docusaurus site, as a plain page or an iframe. Some people embed Javadoc, OpenAPI or Redoc in Docusaurus.
You can also generate md to make that doc native. I've seen people generating docs from a GraphQL schema for example
Back to docusaurus, one weakness is the lack of API documentation tools. Check to see if the programming language for your project has a docusaurus (or a markdown) API generator.
For Python, if you use docusaurus, there's no API documentation generation is nowhere near Sphinx.
What is Docusaurus? It is not very clear from the announcement nor from docusaurus’ homepage. Would love an explanation from someone who uses it. Thank you.
It is a simple markdown-and-folder-structure based react app with PRPL that increasingly powers most of the high quality docs pages you see. For example:
Excellent short answer. What's PRPL? (Google tells me it's a furniture company or an embedded systems foundation, neither of which make sense in this context)
It's the same general wheelhouse of documentation tools as mdbook, i.e. take a pile of markdown and produce high quality documentation. One of the standout features of Docusaurus is that it's based on React so it builds a SPA for your documentation (while still being good about pre-rendering, etc. for good SEO). If you load up a Docusaurus site and start clicking around to read docs it feels like a native app without clunky refreshes, etc. It's very extensible and can be turned into very custom and slick documentation portals.
It also supports MDX which is a a version of markdown that embeds React controls and allows interesting client-side interactivity in your documents. This is very handy for frontend libraries and tools which typically have a showcase or component library which you can interact directly from the docs.
It'd be great if the Docusaurus team added mdBook and Bookdown to their comparison, with an emphasis on code example execution or including code from larger programs. I find that feature of mdBook invaluable (its marker-approach makes documenting how a library works very easy, and keeps the code examples up-to-date as the library evolves) and Bookdown's include code & its output is also good.
Just a shame one package doesn't include every one of these features.
Started as a kind of static site generator in v1 but transitioned to JAMstack (SPA calling to the API) oriented towards creating documentation sites from Markdown. It’s from Facebook so uses React components extensively.
This looks great, I looked on the API but I'm not sure if I'm missing this, is it possible to serve documentation to Docusaurus and have it generate from that served documentation? I've been working on, what I consider, a pretty powerful auto documentation tool and it'd be cool to integrate with this to produce self-hosted doc sites from our auto generated documentation.
I suppose we could generate separate markdown files as well and pass them to the CLI!
Either way I think I'll be adding support for Docusaurus in the near future, cool stuff!
The use case is we automatically generate documentation on the fly, so I'd want to be able to then also automatically update their documentation site with our new docs we've generated.
From what you're saying it sounds like the best route for us to support Docusaurus sites is to generate the markdown files and let them update their site themselves, which is fine I just wanted to make sure I wasn't missing anything myself.
Just been going through a bunch of docs as code solutions trying to find something i like.
I’m troubled by how slow and complicated some build process are. Docusaurus wasn’t the worst offender here although it has more moving parts than i’d like.
If you’re still using Sphinx it might be worth a quick scan of the latest tools, the search facilities are quite good in some nowadays.
So far hugo has my attention the most. Setting up other devs is as simple as checking out the repo (hugo binary is tiny and doesnt need to change often so could even just be vendored into the repo if you wanted).
1 command to checkout even if you’re a dev from another team.
1 to build, and build is fast with live reload.
Docsy theme gets out of the way and just works. I think doks theme looks more user friendly to my eye but the build process is encumbered by mandatory npm deps.
The end result is a little bit different. Docusaurus builds an SPA, page state is preserved when navigating and it makes it easy to interleave React components inside your doc.
Hugo is a more traditional SSG. Definitively faster to build than any Webpack/Babel alternative.
I have good hopes that SPA SSGs will become faster with esbuild, swc, sucrase.
I use Docusaurus for internal documentation/websites , Code documentation. Makes beautiful documentation sites; Works great with node.js build pipelines. Check it out if you haven't yet.
I remember there was a ShowHN post a couple of months ago of a product with a really beautiful web page that used Docusaurus. If I recall correctly, they offered some kind of service related to AWS. Their docs were on GitHub and used a custom dark theme with pink buttons. I can't remember their name. Didn't find them in the docusaurus.io examples. Anyone else remembers this product and its name?
I wanted to love Docusaurus because I'm more of a React guy and I like MDX, but I think Vuepress is better for writing a good documentation.
Something in Docusaurus feels off. When you install it, you're not ready to go, there are a lot of things to clean and remove because it seems to be very tied to Facebook's use.
What theme are you using with Docusaurus? The classic theme (default). I am curious what you are seeing that is Facebook-specific that you are cleaning up. Would love to hear the feedback. Thanks!
You can definitively remove it ("blog: false" in preset config).
If you remove it, you also need to remove the links to the blog, because it would lead to 404 errors.
Docusaurus is fail-fast by default and try to prevent you to deploy broken sites, I understand how it can be annoying in some cases but consider it an useful feature
I read this as 'Nanosaurus 2' beta and memories came flooding back of struggling to control a flying velociraptor with a mouse as one of my first experiences ever with a game on OSX in the Apple Stores.