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

51–60 of 61 posts

Re: Docusaurus 2 Beta

#51

Post by slorber »

thiht wrote: post #47
jimarcey wrote: post #41

Earlier quoted context omitted.

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

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

Re: Docusaurus 2 Beta

#52

Post by slorber »

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…

You can embed doc generated by other tools in a Docusaurus site, as a plain page or an iframe. Some people embed Javadoc, OpenAPI or Redoc in Docusaurus.

You can also generate md to make that doc native. I've seen people generating docs from a GraphQL schema for example

Re: Docusaurus 2 Beta

#53

Post by thiht »

slorber wrote: post #51
thiht wrote: post #47

Earlier quoted context omitted.

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

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

I didn't know about the config parameter, is it recent? I don't remember finding it when I tried to remove it.

Re: Docusaurus 2 Beta

#54

Post by Grimm1 »

slorber wrote: post #49
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

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?

Re: Docusaurus 2 Beta

#55

Post by swyx »

slorber wrote: post #46
swyx wrote: post #36

Earlier quoted context omitted.

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)

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...

Re: Docusaurus 2 Beta

#56

Post by dassmario »

slorber wrote: post #17
dassmario wrote: post #14

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?

I don't know but I'm curious maybe QuestDB?

Nope, it wasn't in the Docusaurus showcase then (https://docusaurus.io/showcase) and isn't there now either, unfortunately.

Re: Docusaurus 2 Beta

#57

Post by pbowyer »

slorber wrote: post #48
pbowyer wrote: post #33

Earlier quoted context omitted.

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.

Sure. Here's mdBook's code embedding: https://rust-lang.github.io/mdBook/format/mdbook.html

Bookdown/rMarkdown/Knitr is best explained at https://rmarkdown.rstudio.com/articles_intro.html#knitr-for-... and the user docs are at https://bookdown.org/yihui/rmarkdown/r-code.html and https://bookdown.org/yihui/rmarkdown/language-engines.html.

I like being able to test that the code in my documentation is valid and runs, and to show the output without having to copy and paste it.

Hope htat's useful!

When I looked at Docusaurus I had the impression it would work very well for JavaScript projects where you could runt he code in-browser, but wasn't designed to document other language code?

Re: Docusaurus 2 Beta

#58

Post by slorber »

pbowyer wrote: post #57
slorber wrote: post #48

Earlier quoted context omitted.

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.

Sure. Here's mdBook's code embedding: https://rust-lang.github.io/mdBook/format/mdbook.html Bookdown/rMarkdown/Knitr is best explained at https://rmarkdown.rstudio.com/articles_intro.html#knitr-for-... and the user docs are at https://bookdown.org/yihui/rmarkdown/r-code.html and https://bookdown.org/yihui/rmarkdown/language-engines.html . I like being able to test that the code in my documentation is valid and runs,…

We use MDX which basically compiles markdown to React components and allows to interleave components inside md content. So you can do similar things like having one doc importing the other. Maybe not as flexible (like importing only a few lines of the other doc).

You can display real production source code in code blocks in any language without having to copy-paste and it can stay in sync.

The live playground allows you to display js code blocks and print the result in the browser. I don't see how this could work with other languages.

Re: Docusaurus 2 Beta

#59

Post by slorber »

Grimm1 wrote: post #54
slorber wrote: post #49

Earlier quoted context omitted.

I don't understand what you mean sorry

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?

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

Re: Docusaurus 2 Beta

#60

Post by slorber »

thiht wrote: post #53
slorber wrote: post #51

Earlier quoted context omitted.

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

I didn't know about the config parameter, is it recent? I don't remember finding it when I tried to remove it.

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.developersam.com/

Post reply on HN