12 ms·

Docusaurus 2 Beta

101 points by marche101 5y ago

slorber 5y ago
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
tony 5y ago
I moved from 11ty / eleventy to docusaurus here: https://social-embed.git-pull.com/ https://social-embed.git-pull.com/ 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 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/lib/api, https://social-embed.git-pull.com/docs/wc/api/classes/oembedelement https://social-embed.git-pull.com/docs/wc/api/classes/oembed... - Supports namespacing between releases (e.g. v1.1, v1.2) and multiple languages
- slorber 5y ago
  Thanks for the feddback No drawbacks to share compared to your previous stack?
  - tony 5y ago
    I inherited 11ty from a boilerplate, but to be fair to them, people do amazing stuff with it: Example https://web.dev/how-we-build-webdev-and-use-web-components/ https://web.dev/how-we-build-webdev-and-use-web-components/. 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/autodoc.html 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 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://github.com/NiklasRosenstein/pydoc-markdown
ta1234567890 5y ago
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.
- ricopags 5y ago
  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: https://developers.cloudflare.com/ https://developers.cloudflare.com/ https://reactnative.dev/docs/getting-started https://reactnative.dev/docs/getting-started more: https://docusaurus.io/showcase/ https://docusaurus.io/showcase/
  - nindalf 5y ago
    How does it compare with say, mdbook?
    - qbasic_forever 5y ago
      Some good info here: https://docusaurus.io/docs/#comparison-with-other-tools https://docusaurus.io/docs/#comparison-with-other-tools 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.
      - pbowyer 5y ago
        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.
devsatish 5y ago
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.
- slorber 5y ago
  Thanks for the feedback
CraigJPerry 5y ago
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.
- slorber 5y ago
  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.
- alexktz 5y ago
  I tried dozens in the space and it sounds like you have too. 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.
david38 5y ago
Any chance for AsciiDoctor support?
- slorber 5y ago
  We'll see how to provide alternate markdown parsers. Can ASCII Doctor be rendered by React?
- stock_toaster 5y ago
  Looks like there is a feature request for it here[1]. I would personally love asciidoc support too. Here's hoping. [1]: https://docusaurus.canny.io/feature-requests/p/asciidoc-support https://docusaurus.canny.io/feature-requests/p/asciidoc-supp...
vlovich123 5y ago
Overloaded with traffic or a bug in the WebServer? > Bad Request Description: Could not process this request.
- slorber 5y ago
  It's a static site with cloudflare/netlify. It should work fine unless major CDNs have technical issued
dassmario 5y ago
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?
- slorber 5y ago
  I don't know but I'm curious maybe QuestDB?
  - dassmario 5y ago
    Nope, it wasn't in the Docusaurus showcase then (https://docusaurus.io/showcase https://docusaurus.io/showcase) and isn't there now either, unfortunately.
bfrog 5y ago
I recently ported some docs to docusaurus, love it. Wish it had a builtin search indexer so it didn't need to jump out to another site for that.
- vaughan 5y ago
  Yeh this is missing right now. I'd love a search indexer that runs locally and incrementally, so that I can search without building/publishing.
- jimarcey 5y ago
  Have you seen the community plugins - https://docusaurus.io/community/resources/#community-plugins https://docusaurus.io/community/resources/#community-plugins. There are some search options there that may be of use to you.
Grimm1 5y ago
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!
- slorber 5y ago
  I don't understand what you mean sorry
  - Grimm1 5y ago
    Is there a way to keep Docusarus running like a live service and make an API request to it to generate documentation pages? Or is it strictly an offline cli tool?
    - slorber 5y ago
      not sure to understand, any concrete use-case to share? 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
      - Grimm1 5y ago
        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.
lostgame 5y ago
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.
thiht 5y ago
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. Maybe it's just me though.
- jimarcey 5y ago
  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!
  - thiht 5y ago
    I remember removing the /blog part was tedious, because there were links in a lot of places. And once I removed it, it didn't build anymore. I'll give it another shot and see if I have the same feeling, if so I'll write a feedback
    - slorber 5y ago
      For sure, our init template contains a blog. 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
      - thiht 5y ago
        I didn't know about the config parameter, is it recent? I don't remember finding it when I tried to remove it.
        slorber 5y ago
        not new, we have many sites that are just using the blog, or just using the docs. Example of just using the blog: https://blog.johnnyreilly.com/ https://blog.johnnyreilly.com/ https://blog.developersam.com/ https://blog.developersam.com/

Docusaurus 2 Beta

101 points by marche101 5y ago

slorber 5y ago

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

tony 5y ago

I moved from 11ty / eleventy to docusaurus here: https://social-embed.git-pull.com/ https://social-embed.git-pull.com/ 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 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/lib/api, https://social-embed.git-pull.com/docs/wc/api/classes/oembedelement https://social-embed.git-pull.com/docs/wc/api/classes/oembed... - Supports namespacing between releases (e.g. v1.1, v1.2) and multiple languages

slorber 5y ago
Thanks for the feddback No drawbacks to share compared to your previous stack?
- tony 5y ago
  I inherited 11ty from a boilerplate, but to be fair to them, people do amazing stuff with it: Example https://web.dev/how-we-build-webdev-and-use-web-components/ https://web.dev/how-we-build-webdev-and-use-web-components/. 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/autodoc.html 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 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://github.com/NiklasRosenstein/pydoc-markdown

ta1234567890 5y ago

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.

ricopags 5y ago
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: https://developers.cloudflare.com/ https://developers.cloudflare.com/ https://reactnative.dev/docs/getting-started https://reactnative.dev/docs/getting-started more: https://docusaurus.io/showcase/ https://docusaurus.io/showcase/
- nindalf 5y ago
  How does it compare with say, mdbook?
  - qbasic_forever 5y ago
    Some good info here: https://docusaurus.io/docs/#comparison-with-other-tools https://docusaurus.io/docs/#comparison-with-other-tools 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.
    - pbowyer 5y ago
      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.

devsatish 5y ago

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.

slorber 5y ago
Thanks for the feedback

CraigJPerry 5y ago

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.

slorber 5y ago
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.
alexktz 5y ago
I tried dozens in the space and it sounds like you have too. 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.

david38 5y ago

Any chance for AsciiDoctor support?

slorber 5y ago
We'll see how to provide alternate markdown parsers. Can ASCII Doctor be rendered by React?
stock_toaster 5y ago
Looks like there is a feature request for it here[1]. I would personally love asciidoc support too. Here's hoping. [1]: https://docusaurus.canny.io/feature-requests/p/asciidoc-support https://docusaurus.canny.io/feature-requests/p/asciidoc-supp...

vlovich123 5y ago

Overloaded with traffic or a bug in the WebServer? > Bad Request Description: Could not process this request.

slorber 5y ago
It's a static site with cloudflare/netlify. It should work fine unless major CDNs have technical issued

dassmario 5y ago

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?

slorber 5y ago
I don't know but I'm curious maybe QuestDB?
- dassmario 5y ago
  Nope, it wasn't in the Docusaurus showcase then (https://docusaurus.io/showcase https://docusaurus.io/showcase) and isn't there now either, unfortunately.

bfrog 5y ago

I recently ported some docs to docusaurus, love it. Wish it had a builtin search indexer so it didn't need to jump out to another site for that.

vaughan 5y ago
Yeh this is missing right now. I'd love a search indexer that runs locally and incrementally, so that I can search without building/publishing.
jimarcey 5y ago
Have you seen the community plugins - https://docusaurus.io/community/resources/#community-plugins https://docusaurus.io/community/resources/#community-plugins. There are some search options there that may be of use to you.

Grimm1 5y ago

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!

slorber 5y ago
I don't understand what you mean sorry
- Grimm1 5y ago
  Is there a way to keep Docusarus running like a live service and make an API request to it to generate documentation pages? Or is it strictly an offline cli tool?
  - slorber 5y ago
    not sure to understand, any concrete use-case to share? 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
    - Grimm1 5y ago
      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.

lostgame 5y ago

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.

thiht 5y ago

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. Maybe it's just me though.

jimarcey 5y ago
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!
- thiht 5y ago
  I remember removing the /blog part was tedious, because there were links in a lot of places. And once I removed it, it didn't build anymore. I'll give it another shot and see if I have the same feeling, if so I'll write a feedback
  - slorber 5y ago
    For sure, our init template contains a blog. 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
    - thiht 5y ago
      I didn't know about the config parameter, is it recent? I don't remember finding it when I tried to remove it.
      - slorber 5y ago
        not new, we have many sites that are just using the blog, or just using the docs. Example of just using the blog: https://blog.johnnyreilly.com/ https://blog.johnnyreilly.com/ https://blog.developersam.com/ https://blog.developersam.com/