atomic-server icon indicating copy to clipboard operation
atomic-server copied to clipboard

Explore alternatives to mdbook for documentation

Open joepio opened this issue 1 year ago • 0 comments

The current mdbook tool works decently, but has a couple of shortcomings:

  • Basic, dated design
  • No support for better codeblocks (e.g. for react / svelte), no support for filenames
  • No support for component previews

We should consider some alternatives.

Astro Starlight

  • Supports components and custom pages
  • Looks good out of the box
  • Uses Astro, which means we could use AtomicServer as data source (could be huge)

Challenges / questions

  • Both Existing URLs and structure should be kept. mdbook uses a SUMMARY.md to set the structure. This may require some redirect strategy.
  • Is the added benefit worth the effort?

joepio avatar Feb 01 '24 12:02 joepio