For the past two weeks I’ve been working on transferring GraphGrid’s documentation site from Docsify to Docusaurus. Both of these open source documentation site generation tools are great but for our needs, switching to Docusaurus is a total upgrade.
With that total upgrade came a lot of excitement and ambitions to make our docs look and feel incredible.✨
Docsify, get your site up fast.. with some limitations
I did the initial work of creating our docs site with Docsify. At the time, our goal was to get our first docs site up quickly. Docsify is perfect for that. No build, no nonsense, just good ol’ markdown and HTML. Docsify has a lot of nice community-made plugins. However, because Docsify uses Vue, scalability and styling can be limited.
However, theres was one glaring detriment, Docsify is not SEO friendly. This is the main reason for switching to Docusaurus.
Docsify limited-to-none SEO support
Docsify does not generate static HTML files and uses hash routing (Google crawlers don’t really like that). As a single-page-application (SPA), that does not pre-render HTML, the search engine crawlers have to interpret javascript. This process slows the crawlers down because it uses a lot of its (the crawler’s) allocated budget.
Below is a helpful infographic posted on a GitHub forum about Docsify SEO by user SidVal. The infographic is from a writeup of an experiment by Bartosz Góralewicz, called "Can Google Properly Crawl and Index JavaScript Frameworks? A JS SEO Experiment."
Docsify is planning to add SEO support
There are plans for server-side rendering in Docsify version 5. I did reach out to Docsify’s community and there are ways around this until then, but unfortunately none of them work with the way we deploy our site. It would just be too much code and some hack-ish strategies to make it work. After accepting this fact, we decided to switch to another beloved, green-mascot having documentation site generator, Docusaurus.
Docusaurus has SEO AND style 😎
Docusaurus is more complex in that it has a build process, but worth it if you’re trying to create a customized, feature-rich site for your documentation.
Docusaurus uses MDX and React.. if that scares you, it’s okay! It’s still just as simple to initialize. Docusarus has excellent guides on styling and configuration. Even if you’re not very familiar with React, you can still set up a good-looking site without getting too much in the weeds. In addition, there are tons of plugins for low-code styling and quality of life features (Hi custom sidebars and live code snippets!).
Most importantly though, Docusaurus is SEO friendly! <3
HTML files are statically generated (unlike Docsify) for every URL so search engines can find and index your content. There is also a sitemap plugin called @docusaurus/plugin-sitemap that ships with the preset-classic version of Docusaurus by default. The sitemap.xml is autogenerated and will help crawlers crawl more accurately.
Conclusion
With all of this being said, both communities for Docsify and Docusaurus are quite active and helpful. If you’re planning on choosing a documentation site generator, take into account the tool’s SEO compliance and how easy it would be to configure. Also look into the available plugins. Will your docs site need charts, live code snippets, or other special features? There’s probably a plugin out there to use instead of having to build it out yourself! Be sure that your doc site generator supports your needs so that you can spend more time focused on content rather than building a documentation site.
Top comments (0)