search

developmentseed / doc-seed

microsite template for reports and documentation
MIT License
3 stars 2 forks source link

Experience doc-seed vs Docusaurus #44

Open olafveerman opened 5 years ago

olafveerman commented 5 years ago

For AF Elections we needed a simple site for developer documentation. Even though we started with doc-seed, we ended up using Docusaurus. This post briefly captures its advantages and disadvantages.

The live site is here: http://devseed.com/af-elections-docs/docs/results

:+1: Docusaurus

  1. The first and second level navigation is manually configured. It's an extra step, but quicker and more intuitive than doc-seed's automatically generated menu. This also provides more flexibility in how one organizes the markdown files. -> https://github.com/developmentseed/af-elections-docs/blob/master/website/sidebars.json

  2. Contextual nav (right side) is auto-generated from markdown headings
    image

  3. Nice code highlighting with highlight.js, which was critical for the API-like documentation that we needed
    image

  4. It's a npm package :rocket:

:+1: Doc Seed

  1. The simple one-page is all we need. Docusaurus is very flexible and assumes a more complex site structure that we typically require. Removing the complexity takes time and I prefer doc-seed's simple structure.

Next time

The configurable navigation and code highlighting are great features of Docusaurus. If we bring that into doc-seed, I would use it for a similar documentation project next time.

cc @danielfdsilva @ricardomestre

danielfdsilva commented 5 years ago

This is good info! There are definitely some things we can borrow from it!

kamicut commented 5 years ago

Another data point: for Scoreboard, we used Docusaurus and integrated DocSearch by Algolia because it has an official integration. The process to apply was straightforward, I added my site (https://developmentseed.org/scoreboard) and my email and they gave me an api key by email to enter into Docusaurus

image

references

Relevant code: https://github.com/developmentseed/scoreboard/pull/326/commits/0df441465d7db2eb795e61ec4142d6129a33220d Scoreboard docseed: https://developmentseed.org/scoreboard