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:
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.
I like being able to test that the code in my documentation is valid and runs, and to show the output without having to copy and paste it.
Hope htat's useful!
When I looked at Docusaurus I had the impression it would work very well for JavaScript projects where you could runt he code in-browser, but wasn't designed to document other language code?
We use MDX which basically compiles markdown to React components and allows to interleave components inside md content. So you can do similar things like having one doc importing the other. Maybe not as flexible (like importing only a few lines of the other doc).
You can display real production source code in code blocks in any language without having to copy-paste and it can stay in sync.
The live playground allows you to display js code blocks and print the result in the browser. I don't see how this could work with other languages.
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)
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.
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.
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 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?
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.
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.
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
60 comments
[ 3.4 ms ] story [ 123 ms ] threadWould 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.
Thanks again for the great work!
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.
Unfortunately we have a few config options that are only found in code blocks and we need to extract those
(and of course, https://react-typescript-cheatsheet.netlify.app/ haha)
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)
Yes we agree on that. Something I'll try to fix asap
https://github.com/facebook/docusaurus/issues/2220
https://github.com/facebook/docusaurus/pull/4273
https://deploy-preview-4273--docusaurus-2.netlify.app/classi...
I'd like to complete this PR asap. Any feedback on this UX is welcome for sure (in the PR preferably)
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.
You can mix guides/tutorials with generated API docs.
For example, I really like having simple API docs in the `readme.md` file, but then also in-depth docs elsewhere.
MDX + remark really let you do anything you want. It's the ultimate documentation stack.
[1]: https://api-extractor.com/pages/setup/generating_docs/
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:
https://github.com/reduxjs/redux-toolkit/issues/1046
You can also generate md to make that doc native. I've seen people generating docs from a GraphQL schema for example
Pluses:
- Very active project
- Nice theme out of the box / configuration. Better than any static site generator I've used thus far
- React components / pages
- Configurability, both by settings, plugins. I was able to add a (non-react) custom element to the static build output
- The sidebar, which supports nesting
- Table of contents on the right side. Highlights current section + supports nesting
- Algolia search adds a ton of value. There's a plugin for it: https://docusaurus.io/docs/search
- Dark / light mode
- Can sorta host API docs, if you can generate Markdown for your API, docusaurus can show it: https://social-embed.git-pull.com/docs/lib/api, https://social-embed.git-pull.com/docs/wc/api/classes/oembed...
- Supports namespacing between releases (e.g. v1.1, v1.2) and multiple languages
No drawbacks to share compared to your previous stack?
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.
Sphinx uses sphinx.ext.autodoc (https://www.sphinx-doc.org/en/master/usage/extensions/autodo...). The dream would be getting a python API like this ported to docusaurus: https://libtmux.git-pull.com/api.html
This can supposedly do it via exporting the API to markdown: https://github.com/NiklasRosenstein/pydoc-markdown
https://developers.cloudflare.com/ https://reactnative.dev/docs/getting-started
more:
https://docusaurus.io/showcase/
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.
Just a shame one package doesn't include every one of these features.
It's be complicated for us to provide a deep comparisons with every single existing doc tool. I've never used mdBook myself.
Bookdown/rMarkdown/Knitr is best explained at https://rmarkdown.rstudio.com/articles_intro.html#knitr-for-... and the user docs are at https://bookdown.org/yihui/rmarkdown/r-code.html and https://bookdown.org/yihui/rmarkdown/language-engines.html.
I like being able to test that the code in my documentation is valid and runs, and to show the output without having to copy and paste it.
Hope htat's useful!
When I looked at Docusaurus I had the impression it would work very well for JavaScript projects where you could runt he code in-browser, but wasn't designed to document other language code?
You can display real production source code in code blocks in any language without having to copy-paste and it can stay in sync.
The live playground allows you to display js code blocks and print the result in the browser. I don't see how this could work with other languages.
https://web.dev/apply-instant-loading-with-prpl/
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.
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 settled on mkdocs for perfectmediaserver.com but hugo was up there too. mdbook is another great contender.
There are lots of almost what I want options. In the end mkdocs-material was close enough and I needed to ship.
I would personally love asciidoc support too. Here's hoping.
[1]: https://docusaurus.canny.io/feature-requests/p/asciidoc-supp...
> Bad Request Description: Could not process this request.
I'd love a search indexer that runs locally and incrementally, so that I can search without building/publishing.
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!
Or is it strictly an offline cli tool?
Docusaurus is a SSG, does not need a server in production and it's not a goal. If something happens live, then it can only happen on your dev computer
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.
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.
Maybe it's just me though.
I'll give it another shot and see if I have the same feeling, if so I'll write a feedback
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
Example of just using the blog: https://blog.johnnyreilly.com/ https://blog.developersam.com/
Can you list any of those things that are tried to Facebook's use?