Future Documentation Plans

GitBook has proven excellent in some ways but has frustrating limitations that make it unsuitable as a long-term solution for SA5's docs.


Rapid updates via a web-based docs editor

Redirects tracking as docs are re-organized

Custom domain

Attributes copy structure



Template options & styling control

Poor to none

Alternatives we're Exploring

  1. Docusaurus:

    • Pros: Open-source, supports versioned documentation, integrates well with React, and offers a rich set of plugins.

    • Cons: Requires some familiarity with React for advanced customizations.

  2. MkDocs:

    • Pros: Open-source, written in Python, and has a wide range of plugins. It's lightweight and easy to set up.

    • Cons: Might require familiarity with Python for some customizations.

  3. Sphinx:

    • Pros: Highly extensible, open-source, and written in Python. It's especially popular for technical and software documentation.

    • Cons: Has a steeper learning curve compared to some other options.

  4. VuePress:

    • Pros: Built on Vue.js, it offers a great balance between writing content and using Vue components. It's also optimized for performance.

    • Cons: Requires knowledge of Vue.js for advanced customizations.

  5. Jekyll:

    • Pros: Widely used static site generator, integrates seamlessly with GitHub Pages, and has a large community.

    • Cons: Written in Ruby, which might not be familiar to everyone.

  6. Hugo:

    • Pros: Extremely fast static site generator written in Go. It has a rich ecosystem and can handle large sites with ease.

    • Cons: Templating can be complex for beginners.

  7. Read the Docs:

    • Pros: Hosted solution that integrates well with GitHub, Bitbucket, and GitLab. It's especially popular for open-source projects.

    • Cons: More suited for technical documentation.

Last updated