Docusaurus 2 Beta
docusaurus.io
docusaurus.io
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.
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.
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 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:
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.
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.
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
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?
I would personally love asciidoc support too. Here's hoping.
[1]: https://docusaurus.canny.io/feature-requests/p/asciidoc-supp...
I'd love a search indexer that runs locally and incrementally, so that I can search without building/publishing.
> Bad Request Description: Could not process this request.