Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Docusaurus 2 Beta

docusaurus.io

Post reply on HN
Print view View original

41–50 of 61 posts

Re: Docusaurus 2 Beta

#41

Post by jimarcey »

thiht wrote: post #38

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.

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!

Re: Docusaurus 2 Beta

#42

Post by acemarke »

vaughan wrote: post #34
abought wrote: post #18

Earlier quoted context omitted.

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…

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/

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

Re: Docusaurus 2 Beta

#43

Post by [deleted] »

abought wrote: post #18
slorber wrote: post #2

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

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…

[deleted]

Re: Docusaurus 2 Beta

#44

Post by PaulWaldman »

gnat wrote: post #39
ricopags wrote: post #6

Earlier quoted context omitted.

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/

Excellent short answer. What's PRPL? (Google tells me it's a furniture company or an embedded systems foundation, neither of which make sense in this context)

Push, Render, Pre-Cahce, and Load. It was coined by the Google Chrome team has a framework for making pages load faster.

https://web.dev/apply-instant-loading-with-prpl/

Re: Docusaurus 2 Beta

#45

Post by slorber »

swyx wrote: post #20
slorber wrote: post #15

Earlier quoted context omitted.

Yes! We also accept an editUrl callback for maximum customizability

btw i couldnt find docs on editUrl... the algolia searchbox on docusaurus needs some fixing

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

Re: Docusaurus 2 Beta

#46

Post by slorber »

swyx wrote: post #36
slorber wrote: post #16

Earlier quoted context omitted.

Thanks! Yes we agree on that. Something I'll try to fix asap

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!

We have an issue and a pending PR with a design proposal.

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)

Re: Docusaurus 2 Beta

#47

Post by thiht »

jimarcey wrote: post #41
thiht wrote: post #38

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.

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!

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

Re: Docusaurus 2 Beta

#48

Post by slorber »

pbowyer wrote: post #33
qbasic_forever wrote: post #30

Earlier quoted context omitted.

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 s…

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…

Do you have a link to these features? I believe we somehow support those already.

It's be complicated for us to provide a deep comparisons with every single existing doc tool. I've never used mdBook myself.

Re: Docusaurus 2 Beta

#49

Post by slorber »

Grimm1 wrote: post #28

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…

I don't understand what you mean sorry

Re: Docusaurus 2 Beta

#50

Post by slorber »

thiht wrote: post #38

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.

That looks weird to me.

Can you list any of those things that are tried to Facebook's use?

Post reply on HN