feat: add Antora and Vale with CI

.github/styles/config/vocabularies/CleanDocs/accept.txt

@@ -0,0 +1,10 @@
+Antora
+Taskfile
+QAware
+Eimer
+Krause
+Lunr
+Kroki
+Jekyll
+AsciiDoc
+ADR

.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+# Reference: https://docs.antora.org/antora/latest/publish-to-github-pages/
+
+name: Publish
+on:
+  push:
+    branches: [main]
+  pull_request: ~
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+      - name: Install npm dependencies
+        run: npm ci
+      - name: Generate Site
+        run: >-
+          npx antora
+          --asciidoc-sourcemap
+          --stacktrace
+          --fetch
+          --clean
+          antora-playbook.yml
+        env:
+          ANTORA_LOG_FAILURE_LEVEL: warn
+          ANTORA_LOG_LEVEL: info
+
+      # Only publish if on main
+      # Anyway run until here to check if antora builds
+      - name: Upload Artifacts
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/site
+        if: github.ref == 'refs/heads/main'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+        if: github.ref == 'refs/heads/main'

.github/workflows/verify.yml

@@ -0,0 +1,17 @@
+# Reference: https://github.com/errata-ai/vale-action
+
+name: Verify
+on:
+  push:
+    branches: [main]
+  pull_request: ~
+
+jobs:
+  vale:
+    name: vale
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: errata-ai/[email protected]
+        with:
+          fail_on_error: true

.gitignore

@@ -1,2 +1,12 @@
 .vscode/
+.idea/
+clean-documentation-template.iml
+
 .DS_Store
+
+node_modules/
+build/
+
+# Vale
+.github/styles/*
+!.github/styles/config/

.nvmrc

@@ -0,0 +1 @@
+v20

.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+# Reference: https://pre-commit.com
+
+default_install_hook_types:
+  - pre-commit
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-json
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+
+  - repo: https://github.com/errata-ai/vale
+    rev: v3.7.0
+    hooks:
+      - id: vale
+
+#  # TODO: Add hook which checks the file(path)s under docs => only lowercase allowed
+#  - repo: local
+#    hooks:
+#      - id: antora-files-lowercase-only
+#        name: antora lower-case filenames only
+#        entry: filenames and folders must be lower-case for Antora
+#        language: fail
+#        # TODO: Make regex work
+#        # https://regex101.com/r/iRCDJL/1
+#        files: '^(docs/(modules/ROOT/)?).*[^a-z0-9._/-]'

.vale.ini

@@ -0,0 +1,13 @@
+# Reference: https://github.com/errata-ai/vale-action
+# Reference: https://vale.sh/docs/topics/config/
+
+StylesPath = .github/styles
+MinAlertLevel = suggestion
+
+Packages = Google
+Vocab = CleanDocs
+
+[*.adoc]
+BasedOnStyles = Vale, Google
+# Customizations
+Google.Acronyms = OFF

Brewfile

@@ -0,0 +1,2 @@
+brew "go-task"
+brew "pre-commit"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alexander Eimer, Alex Krause
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.adoc

@@ -2,8 +2,11 @@
 
 ////
 TODOs:
+* nav.adoc's are missing
 * Add repo descriptions
-* Add antora and vale code
+* Use dockerized build => CI and local use for antora build
+  https://github.com/qaware/clean-documentation-template/pull/1#discussion_r1736311093
+* Add jekyll startpage just like https://github.com/ahus1/intellij-asciidoc-plugin.ahus1.de/tree/main/startpage
 ////
 
 This repo shows how
@@ -12,15 +15,109 @@
 https://github.com/aeimer[Alexander Eimer (@aeimer)]
 think how AsciiDoc, Antora and vale can be used to document your software and product better.
 
+[.text-center]
+****
+You can find the rendered Antora docs
+https://qaware.github.io/clean-documentation-template[here]
+****
+
+== Structure
+
+This repo has two main parts, the first can be found under
+xref:templates/[templates]
+and provide standalone files which can be used within the next part.
+
+The second part shows how to set up a working Antora and all the by us suggested  tooling.
+Almost any other files not under the `templates` directory belongs to this part.
+The templates provided are our suggestion to use within the documentation structure.
+
+== Content
+
+From a technical perspective the following components are used.
+
+Antora::
+#TODO#
+
+Antora Lunr::
+#TODO#
+
+Antora Collector::
+#TODO#
+
+Antora Assembler::
+#TODO#
+
+Antora Kroki::
+#TODO#
+
+Vale::
+#TODO#
+
+Pre-Commit::
+#TODO#
+
+== Differences to the real world
+
+As this is a template which is contained within one repo, there are some differences to a real world setup.
+
+* As
+https://docs.antora.org/antora/latest/playbook/#where-is-a-playbook-stored[suggested by Antora]
+the playbook and the configuration files are stored in a separate repository.
+Having a "docs" repo with the playbook, config and some documentation content together works for some setups well, always look at your use-case.
+If in doubt start small and adapt if you grow.
+
+* You probably want to have different repos as source defined in the `antora-playbook.yml` with branches or tags as references which state to use.
+
+== Using the Taskfile
+
+https://taskfile.dev[`Taskfile`]
+is a `Makefile` on steroids.
+You need to install Taskfile globally to use it.
+
+[source,bash]
+----
+# Install required dependencies via Brewfile
+brew bundle
+
+# Alternatively, install at least Taskfile (manually)
+brew install go-task
+
+# Show all tasks available
+task
+
+# Render documentation
+task generate
+
+# Render documentation and open in browser
+task generate open
+# or
+task g o
+
+# Open rendered documentation with http server
+task serve
+----
+
 == Useful links
 
+* https://diataxis.fr[Diátaxis]
 * https://antora.org[Antora]
+** https://gitlab.com/antora/antora-collector-extension[Antora collector] +
+A hook plugin to run custom code while generating the docs.
+It can be used to auto-generate `nav.adoc` files for dynamic content.
+** https://gitlab.com/antora/antora-assembler[Antora assembler] +
+A plugin which has pure AsciiDoc as output and has all the Antora magic removed.
+It can be used to generate PDFs with the whole content.
 * https://vale.sh[Vale]
 * https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoctor Quick Reference]
 * https://nick.groenen.me/notes/one-sentence-per-line/[One sentence per line rule]
 * https://github.com/joelparkerhenderson/architecture-decision-record[Joels ADR]
-* https://www.blameless.com/blog/what-are-blameless-postmortems-do-they-work-how[blamess.com]
-* https://github.com/dastergon/postmortem-templates/blob/master/templates/postmortem-template-srebook.md?plain=1[github.com/dastergon/postmortem-templates^]
+* https://www.blameless.com/blog/what-are-blameless-postmortems-do-they-work-how[blameless.com]
+* https://github.com/dastergon/postmortem-templates/blob/master/templates/postmortem-template-srebook.md?plain=1[dastergon/postmortem-templates^]
+* https://ahus1.de[Alexander Schwartz]
+** https://www.ahus1.de/post/content-pipeline-antora[Talk about Antora] +
+=> https://github.com/ahus1/antora-extensions-demo[Demo repo to the talk]
+** https://www.ahus1.de/post/documentation-site-antora[Another talk about Antora] +
+=> https://github.com/ahus1/intellij-asciidoc-plugin.ahus1.de[IntelliJ AsciiDoc Plugin documentation]
 
 == Support
 

Taskfile.yml

@@ -0,0 +1,99 @@
+# https://taskfile.dev
+
+version: '3'
+
+env:
+  VALE_CONFIG_PATH: .vale.ini
+
+vars: {}
+
+tasks:
+  default:
+    desc: If running only "task" print all available tasks
+    cmd: task --list-all
+    silent: true
+
+  setup:
+    desc: Install everything needed
+    run: once
+    deps: [brew]
+    cmds:
+      - pre-commit install
+      - task: vale-sync
+
+  brew:
+    desc: Install tool dependencies with brew
+    internal: true
+    run: once
+    platforms: [darwin, linux]
+    cmd: brew bundle --no-lock --verbose
+    status:
+      - brew bundle check --verbose
+
+  vale-sync:
+    desc: install tool-internal dependencies
+    internal: true
+    run: once
+    deps: [brew]
+    cmd: vale sync
+    status:
+      - test -d .github/styles/Google
+
+  generate:
+    desc: Generates documentation with antora
+    aliases: [g, gen]
+    deps:
+      - npm-install
+    env:
+      ANTORA_LOG_FAILURE_LEVEL: warn
+      ANTORA_LOG_LEVEL: info
+    cmd: >-
+      npx antora
+      --asciidoc-sourcemap
+      --stacktrace
+      --fetch
+      --clean
+      antora-playbook.yml
+
+  open:
+    desc: Open the documentation via browser (also see serve)
+    aliases: [o]
+    cmd: open build/site/index.html
+
+  serve:
+    desc: Serves the static files with a local http server (also see open)
+    aliases: [s]
+    dir: build/site
+    cmd: npx http-server -o .
+
+  npm-install:
+    desc: Install npm packages
+    internal: true
+    preconditions:
+      - node -v | grep -E "^$(cat .nvmrc)"
+    cmd: npm install
+
+  vale-lint:
+    desc: check adoc-files
+    aliases: [vl, lint]
+    deps: [setup]
+    run: once
+    cmds:
+      - find . -name "*.adoc" -not -path "./node_modules/*" | sort | xargs vale --no-wrap
+
+  pre-commit:
+    desc: run pre-commit checks
+    aliases: [pc]
+    deps: [setup]
+    run: once
+    cmds:
+      - pre-commit run --all-files
+
+  validate:
+    desc: run all quality checks
+    aliases: [v]
+    deps: [setup]
+    run: once
+    cmds:
+      - task: vale-lint
+      - task: pre-commit