[HN Gopher] Docusaurus 2 Beta
___________________________________________________________________
Docusaurus 2 Beta
Author : marche101
Score : 92 points
Date : 2021-05-12 16:58 UTC (6 hours ago)
(HTM) web link (docusaurus.io)
(TXT) w3m dump (docusaurus.io)
| tony wrote:
| I moved from 11ty / eleventy to docusaurus here: 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
|
| - 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
| slorber wrote:
| Thanks for the feddback
|
| No drawbacks to share compared to your previous stack?
| tony wrote:
| 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/.
|
| 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
| ta1234567890 wrote:
| 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 wrote:
| 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://reactnative.dev/docs/getting-started
|
| more:
|
| https://docusaurus.io/showcase/
| nindalf wrote:
| How does it compare with say, mdbook?
| qbasic_forever wrote:
| Some good info here:
| 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 wrote:
| 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.
| swiley wrote:
| Oh man! An SPA for viewing pages!
| mynegation wrote:
| 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.
| slorber wrote:
| Oh sweet, it's the first time I work on something and someone
| else post the link to Hacker News :D
| ricopags wrote:
| 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 wrote:
| this already exists - set the editUrl in your docusaurus
| config. https://github.com/temporalio/documentation/blob/mast
| er/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 wrote:
| Yes! We also accept an editUrl callback for maximum
| customizability
| swyx wrote:
| btw i couldnt find docs on editUrl... the algolia
| searchbox on docusaurus needs some fixing
| swyx wrote:
| thanks for all your hard work on Docusaurus!! happy users here
| https://docs.temporal.io/
|
| (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)
| slorber wrote:
| Thanks!
|
| Yes we agree on that. Something I'll try to fix asap
| swyx wrote:
| 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!
| abought wrote:
| 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/websi
| te/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 wrote:
| 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/
| david38 wrote:
| Any chance for AsciiDoctor support?
| slorber wrote:
| We'll see how to provide alternate markdown parsers. Can ASCII
| Doctor be rendered by React?
| stock_toaster wrote:
| 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-
| supp...
| lostgame wrote:
| 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.
| vlovich123 wrote:
| Overloaded with traffic or a bug in the WebServer?
|
| > Bad Request Description: Could not process this request.
| slorber wrote:
| It's a static site with cloudflare/netlify. It should work fine
| unless major CDNs have technical issued
| devsatish wrote:
| 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 wrote:
| Thanks for the feedback
| Grimm1 wrote:
| 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!
| bfrog wrote:
| 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 wrote:
| 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.
| CraigJPerry wrote:
| 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 wrote:
| 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 wrote:
| 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.
| dassmario wrote:
| 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 wrote:
| I don't know but I'm curious maybe QuestDB?
___________________________________________________________________
(page generated 2021-05-12 23:02 UTC)