5 ms·

Oh sweet, it's the first time I work on something and someone else post the link to Hacker News :D

ricopags 5y ago
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. Thanks again for the great work!
- swyx 5y ago
  this already exists - set the editUrl in your docusaurus config. https://github.com/temporalio/documentation/blob/master/docusaurus.config.js#L188-L211 https://github.com/temporalio/documentation/blob/master/docu... 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.
  - slorber 5y ago
    Yes! We also accept an editUrl callback for maximum customizability
    - swyx 5y ago
      btw i couldnt find docs on editUrl... the algolia searchbox on docusaurus needs some fixing
      - slorber 5y ago
        It's a Docsearch reco from Algolia to not index code blocks. Unfortunately we have a few config options that are only found in code blocks and we need to extract those
swyx 5y ago
thanks for all your hard work on Docusaurus!! happy users here https://docs.temporal.io/ https://docs.temporal.io/ (and of course, https://react-typescript-cheatsheet.netlify.app/ 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 https://docs.temporal.io/blog and i feel comfortable maintaining it if the interface ever changes. thanks to docusaurus (and gatsby)
- slorber 5y ago
  Thanks! Yes we agree on that. Something I'll try to fix asap
  - swyx 5y ago
    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!
    - slorber 5y ago
      We have an issue and a pending PR with a design proposal. https://github.com/facebook/docusaurus/issues/2220 https://github.com/facebook/docusaurus/issues/2220 https://github.com/facebook/docusaurus/pull/4273 https://github.com/facebook/docusaurus/pull/4273 https://deploy-preview-4273--docusaurus-2.netlify.app/classic/docs 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)
      - swyx 5y ago
        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...
abought 5y ago
This looks interesting! 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/parser.md 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.
- vaughan 5y ago
  Combining TypeScript's API Extractor (Microsoft) with Docusaurus is great. 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/ https://api-extractor.com/pages/setup/generating_docs/
  - acemarke 5y ago
    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: https://github.com/reduxjs/redux-toolkit/issues/1046 https://github.com/reduxjs/redux-toolkit/issues/1046
- deleted 5y ago
  [deleted]
- slorber 5y ago

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. Thanks again for the great work!

swyx 5y ago
this already exists - set the editUrl in your docusaurus config. https://github.com/temporalio/documentation/blob/master/docusaurus.config.js#L188-L211 https://github.com/temporalio/documentation/blob/master/docu... 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.
- slorber 5y ago
  Yes! We also accept an editUrl callback for maximum customizability
  - swyx 5y ago
    btw i couldnt find docs on editUrl... the algolia searchbox on docusaurus needs some fixing
    - slorber 5y ago
      It's a Docsearch reco from Algolia to not index code blocks. Unfortunately we have a few config options that are only found in code blocks and we need to extract those

swyx 5y ago

thanks for all your hard work on Docusaurus!! happy users here https://docs.temporal.io/ https://docs.temporal.io/ (and of course, https://react-typescript-cheatsheet.netlify.app/ 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 https://docs.temporal.io/blog and i feel comfortable maintaining it if the interface ever changes. thanks to docusaurus (and gatsby)

slorber 5y ago
Thanks! Yes we agree on that. Something I'll try to fix asap
- swyx 5y ago
  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!
  - slorber 5y ago
    We have an issue and a pending PR with a design proposal. https://github.com/facebook/docusaurus/issues/2220 https://github.com/facebook/docusaurus/issues/2220 https://github.com/facebook/docusaurus/pull/4273 https://github.com/facebook/docusaurus/pull/4273 https://deploy-preview-4273--docusaurus-2.netlify.app/classic/docs 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)
    - swyx 5y ago
      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...

abought 5y ago

This looks interesting! 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/parser.md 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.

vaughan 5y ago
Combining TypeScript's API Extractor (Microsoft) with Docusaurus is great. 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/ https://api-extractor.com/pages/setup/generating_docs/
- acemarke 5y ago
  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: https://github.com/reduxjs/redux-toolkit/issues/1046 https://github.com/reduxjs/redux-toolkit/issues/1046
deleted 5y ago
[deleted]
slorber 5y ago