- Status: accepted
- Deciders: Chris Simon
- Date: 2024-11-29
To build Contextive documentation using Starlight.
So far, Contextive documentation has been kept in a few places:
- Extension/plugin README files, visible in their web marketplaces and plugin installation experiences
- Markdown files in a
wikifolder in the repository, accessible via the Github UI
As the size of the documentation increases, it would be beneficial to have a more comprehensive documentation system that supports a few goals:
- Expandable to document new tools in the Contextive ecosystem, such as browser plugins etc.
- Use the Diátaxis approach to technical documentation authoring
- Align with Contextive branding
- Flexible hosting (not reliant on github)
- Configuration and content version controlled alongside contextive source code
- Ease of content creation for small team of devs (i.e. no need to be maintained by folk outside of git)
- Publishable to free/low cost static site hosting
- Availability of visually appealing and easy to customise templates/themes
- Support internationalisation in the future
- Support ineline code-samples
Documentation Specific Systems:
Other Static Site Generators:
To build Contextive documentation using Starlight.
Docusaurus was the other main contender, and both are very compelling options. The following analyses and experience reports were considered:
- https://blog.logrocket.com/starlight-vs-docusaurus-building-documentation/
- https://www.tinybird.co/blog-posts/new-docs (although they did not choose Starlight, they included a comprehensive comparison)
- https://barnabas.me/blog/2023/06/starlight/
- Simple & configurable template to get started
- Ease of applying accessible contextive branding using color theme editor
- Extensible via a range of technologies in the future (React, Vue, Svelte) due to being based on Astro
- Less mature, so less broad ecosystem of extensions and examples, although it is possible to use Astro plugins
- Good, because easy to get started
- Good, because built on Astro so flexible future pathway
- Good, because great documentation on how to customise
- Bad, because less examples and less mature ecosystem
- Good, because easy to get started
- Good, because broad range of examples and mature ecosystem
- Good, because good documentation on how to configure
- Bad, because locked to React
- Good, because flexible future pathway
- Bad, because would require more effort to setup documentation specific template
- Good, because F# keeps it in the broad Contextive language ecosystem
- Bad, because immature range of templates and extension examples