From 58690a38306f26f8be9ef4b318d6229a3814259d Mon Sep 17 00:00:00 2001 From: Keith Hazelton Date: Fri, 26 May 2023 06:51:34 -0500 Subject: [PATCH] Update its.adoc --- its.adoc | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/its.adoc b/its.adoc index 8639cf8..7ffb3ca 100644 --- a/its.adoc +++ b/its.adoc @@ -7,3 +7,29 @@ Static site generators as documentation substrate . Docusaurus . Antora . Hugo + + +=== Documentation-as-DevOps + +==== One Option + +. Review Evolveum Documentation: https://docs.evolveum.com/, and their writing processes: https://docs.evolveum.com/about/writing-documentation/, https://docs.evolveum.com/about/asciidoc/ +. Migrate existing content from Confluence XHTML to asciidoc: https://docs.asciidoctor.org/asciidoctor/latest/migrate/confluence-xhtml/ +. Create and edit new and existing files with asciidoc, push to a github repo +. Include PlanntUML, C4, and output from additional diagramming tools with the asciidoctor extension for kroki: https://github.com/ggrossetie/asciidoctor-kroki, https://kroki.io/ +. Create an Antora site to host the asciidoc files +. Anrtora Assembler: add-on library and extension that assembles content from multiple pages into aggregate documents, converts them to the specified output format, and publishes them alongside other files in the site https://gitlab.com/antora/antora-assembler +. Follow Antora guidance to create a pipeline to rebuild the site whenever content is added, edited, or deleted: https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&ved=2ahUKEwiB5IfittT-AhWVk4kEHR9zBwQQFnoECBcQAQ&url=https%3A%2F%2Fdocs.antora.org%2Fantora%2Flatest%2Fpublish-to-gitlab-pages%2F&usg=AOvVaw3vOCafAF8DhwsRqTQbeFcm + +==== DevOps approach to Documentation: Reference materials +- Evolveum documentation site: https://docs.evolveum.com +- Asciidoc: https://asciidoc.org +- Markdown: https://www.markdownguide.org/ +- Antora: https://antora.org/ "multi-repository documentation site generator for tech writers writing in AsciiDoc" +- Github Pages or Gitlab Pages (Auto Re-Publication on commit to repo) +- https://pages.github.com, https://docs.gitlab.com/ee/user/project/pages/ +- Gitlab Demo ‘source’: https://gitlab.com/antora/demo +- Gitlab Demo published version: https://antora.gitlab.io/demo/docs-site/component-b/2.0/index.html +- Pros and Cons of Markdown vs Asciidoc: https://www.slant.co/versus/1903/23065/~markdown_vs_asciidoc +- Jeff Sandberg, "I wish asciidoc was more popular": https://pdx.su/blog/2023-02-05-asciidoc-and-markdown/ +