Oh sweet, it's the first time I work on something and someone else post the link to Hacker News :D
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