6 ms·
We are using Docusaurus (https://docusaurus.io/ https://docusaurus.io/ ). - it is easy to configure/customise - looks really great out of the box - s
by navaneethpk 5y ago
We are using Docusaurus (https://docusaurus.io/ 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 https://github.com/ToolJet/ToolJet/tree/develop/docs and here is the live documentation: https://docs.tooljet.com/ https://docs.tooljet.com/
- grodriguez100 5y agoAspect 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 5y agoI think it is because we have explicitly set the height of the images (https://github.com/ToolJet/ToolJet/blob/develop/docs/docs/intro.md?plain=1#L9 https://github.com/ToolJet/ToolJet/blob/develop/docs/docs/in...). Will fix it.
- gompertz 5y agoSort of curious, is there key differences between Docusauras and Hugo that would make it worth switching??
- newaccount74 5y agoYour docs even support dark mode! Did that come out of the box or did you add that?
- navaneethpk 5y agoIt 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 5y agoYou 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 5y agoThanks, I will try creating a custom react component for handling the modes.
- lelandfe 5y ago> live documentation: https://docs.tooljet.io 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?
- navaneethpk 5y agoYou are right, placing the navigation on the sidebar is more useful than the links to GitHub and Slack.
- dsmmcken 5y agoUpdate to a more recent version, they re-worked the nav to be one menu on mobile.
- navaneethpk 5y agoYour 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 5y agoThat 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 https://docs.tooljet.com
- lelandfe 5y agoMuch better, thanks!
- stavros 5y agoOh huh, I completely missed the second hamburger button and was perplexed as to why their documentation only had three links to other sites.
- daviesliu 5y agoDocusaurus 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 https://juicefs.com/docs/community/introduction [2] https://github.com/juicedata/juicefs/blob/main/docs/en/how_to_setup_object_storage.md https://github.com/juicedata/juicefs/blob/main/docs/en/how_t...
- navaneethpk 5y agoHaven'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 5y agoYes, 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!
- dsmmcken 5y agoNot 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.
- kaycebasques 5y agoWhat was your motivation(s) for migrating away from Sphinx?
- shafyy 5y agoI'm also using Docusaurus for Fugu (https://docs.fugu.lol 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!
- stavros 5y agoIt doesn't support search unless you rely on (pay for) Algolia? Wow, instant pass from me.
- shafyy 5y agoYou 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 https://docusaurus.io/docs/search
- stavros 5y agoAh phew, thanks. The site made it sound like they only supported Algolia.
- navaneethpk 5y agoWe 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 https://github.com/typesense/typesense-docsearch-scraper
- shafyy 5y agoYes, that looks like a good solution! Thanks!
- dsmmcken 5y agoWe 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/ 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 5y ago+1 for Docusaurus. We're using it at Warrant (https://docs.warrant.dev/ 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.