[navaneethpk]

We are using Docusaurus (https://docusaurus.io/ ).

   - it is easy to configure/customise 
   - looks really great out of the box
   - solid documentation
   - fast

In our case, we just had to change the colors and font. Here is our Docusaurus code if that's helpful: https://github.com/ToolJet/ToolJet/tree/develop/docs and here is the live documentation: https://docs.tooljet.com/

[daviesliu]

Docusaurus is great! We migrated from Sphinx to Docusaurus[1] recently, the navigation is much better than before.

One thing that bothers us: we have not figure a way to name the anchor that both work in Github (`<span id='aws-s3'/>`) and Docusaurus (`{#aws-s3}`), for example [2]. Any ideas?

[1] https://juicefs.com/docs/community/introduction [2] https://github.com/juicedata/juicefs/blob/main/docs/en/how_t...

[dsmmcken]

Not a great solution, but you could create the links github style, then write a remark/rehype plugin that transforms them to Docusaurus style at build time. I would probably just live with it though.

[navaneethpk]

Haven't tried this but will it work on both GitHub and Docusaurus if the section "S3" is renamed as "Amazon S3" and then removing the "{#aws-s3}" part?

[daviesliu]

Yes, we can use `#amazon-s3` as the anchor, then the name could be long, for example, `#digitalocean-spaces-object-storage`), and it will not work in Chinese.

Your suggestion is better than current one, we will use that, thanks!

[kaycebasques]

What was your motivation(s) for migrating away from Sphinx?

[shafyy]

I'm also using Docusaurus for Fugu (https://docs.fugu.lol).

One thing that bothers me is that they offer a free Algolia integration for open-source projects, but they declined my application despite being open source.

So, search not working for now, need to have another look at that :-)

Edit: I just got an email from Algolia DocSearch saying that my documentation qualifies after all :-) If someone from that team read my comment and send the email, thanks! If not, it's a big coincidence, also good!

[navaneethpk]

We tried to use Typesense for the search bar. We could not wrap up the PR due to bandwidth issues but it should be a great alternative for Algolia. Link: https://github.com/typesense/typesense-docsearch-scraper

[shafyy]

Yes, that looks like a good solution! Thanks!

[stavros]

It doesn't support search unless you rely on (pay for) Algolia? Wow, instant pass from me.

[shafyy]

You can add your own search plugin or use another provider like Typesense. They just offer an optional free Algolia service for open-source projects on top. You can read more here: https://docusaurus.io/docs/search

[stavros]

Ah phew, thanks. The site made it sound like they only supported Algolia.

[lelandfe]

> live documentation: https://docs.tooljet.io

The two separate hamburger menus were hard to parse at first on mobile. Do your social media links really deserve higher placement than the navigation?

[stavros]

Oh huh, I completely missed the second hamburger button and was perplexed as to why their documentation only had three links to other sites.

[navaneethpk]

You are right, placing the navigation on the sidebar is more useful than the links to GitHub and Slack.

[dsmmcken]

Update to a more recent version, they re-worked the nav to be one menu on mobile.

[navaneethpk]

Your comment was super helpful. I just tried upgrading to 2.0.0-beta.9. The menu now looks great on mobile. The upgrade is causing some other issues, will fix those and deploy the docs. Thanks!

[navaneethpk]

That was a very low-hanging fruit. Could fix and deploy it in a few minutes. There are few other improvements too related to navigation in the latest Docusaurus. Deployed here: https://docs.tooljet.com

[lelandfe]

Much better, thanks!

[dsmmcken]

We also use Docusaurus. It has good defaults. If you are familiar with react, mdx (markdown + jsx) allows you to easily create and embed interactive react components.

It's technically still in beta with frequent updates, and the occasional breaking change.

For our site (https://deephaven.io/core/docs/), what I liked was the ease of adding your own plugins. We made a plugin that extracts all our code examples, and automatically tests them against new versions to notify us if any examples break or become stale.

[akajla]

+1 for Docusaurus. We're using it at Warrant (https://docs.warrant.dev/). In addition to what folks have already mentioned, it has good blogging support as well (markdown, post tags, SEO/social tags etc). Makes it much easier to manage both docs + blog from the same system.

[gompertz]

Sort of curious, is there key differences between Docusauras and Hugo that would make it worth switching??

[grodriguez100]

Aspect ratio of screenshots looks wrong when the docs are browsed from mobile phones. Is this a docusaurus issue or perhaps specific to your docs?

[navaneethpk]

I think it is because we have explicitly set the height of the images (https://github.com/ToolJet/ToolJet/blob/develop/docs/docs/in...). Will fix it.

[newaccount74]

Your docs even support dark mode! Did that come out of the box or did you add that?

[navaneethpk]

It comes out of the box. We are now trying to figure out how to switch screenshots based on the light/dark mode. The screenshots taken from light mode of ToolJet looks odd in Docusaurus' dark mode.

[dsmmcken]

You could build your own react image wrapper then use that component in the mdx and pass in two images, then display the appropriate one based on the current theme provider. Docusaurus makes using inline react components easy.

You could also write your own remark plugin, that does it for you, and would have the benefit of having more control over what happens on the github side if it was still standard markdown.

[navaneethpk]

Thanks, I will try creating a custom react component for handling the modes.