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)
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 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)
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!
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!
Readit News
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.
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.
(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
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/
You can also generate md to make that doc native. I've seen people generating docs from a GraphQL schema for example
Deleted Comment
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/
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?
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.
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
Can you list any of those things that are tried to Facebook's use?