New Docs Website

[LPGhatguy]

MkDocs has served us well for almost two and a half years. We use it in all of our open source libraries across Roblox, as well as some internal ones.

Site Generator Wishlist

• Should build an entire website, not just a docs page
  • MkDocs isn't suitable for building a website for a project that has docs instead of just being docs. An official Roact website is in the cards and docs should be integrated into it.
• Should support components, so we can re-use blocks easily.
  • MDX would be awesome for this
• Should preserve UI state across pages to make navigation faster and less cumbersome
• Should use technologies that compose well
  • It should be easy to write new components that doesn't conflict with existing components, like via CSS modules.
  • It should be easy to plug in interactive components for demos, playgrounds, etc.
• Should accept a mix of handwritten and machine-generated documentation
  • We may want to attach a Lua doc generator to the generator to automatically generate some pages, but not all of them.
• Stretch: should work offline or in spotty network conditions

Contenders

• Docusaurus
• Something we build ourselves?