=== DevOps Approach to Documentation
:hide-uri-scheme:

- - -
_2023-05-14 13:48:53 Draft documentation tool option comparisons_

==== I. Introduction

TBD

==== II. Requirements

What features of Confluence are used in our wiki content? Are there counterparts in the other options under consideration?

Specific Requirements

. A documentation entry system with source files under version control
. A process that creates a web accessible documentation site from the source repository
. Triggering site re-publication process on a push to the source repository (CI/CD pipeline)
. Support for one or more of the available markdown-based languages for document creation
. Essential features
.. Tables
.. Liats, nested lists, bullet or numbered style
.. Table of contents
.. Definition lists
.. Footnotes
.. Bibliographies
.. Callouts (e.g. NOTE, WARN...)
.. Task list items
.. Applicable site themes
.. Support for common diagram styles (via Kroki)
.. External file includes
.. Support for user-defined macros
.. Conditional markup
.. Host sites on GitHub Pages and GitLab
.. Support for reader comments
.. Supports full-text search
.. Renders typographic entities
.. Emoji support

==== III. Example of an end-to-end documentation system
. Hugo static site builder with Docsy module: 
.. https://www.docsy.dev/docs/get-started/docsy-as-module/example-site-as-template/
. Content in Github-flavored Markdown and/or Asciidoc
. Publish to Github Pages

==== IV. Reference Materials
- Evolveum documentation site: https://docs.evolveum.com
- Asciidoc: https://asciidoc.org  
- Markdown: https://www.markdownguide.org/
- Github Pages: https://pages.github.com (Auto Re-Publication on commit to repo)