gesinn-it-docs-master-pub

Repository for centrally maintained, reusable AsciiDoc documentation snippets.

The snippets stored in this repository can be reused across multiple repositories (e.g. MediaWiki extensions) to ensure consistent documentation and avoid duplication.

Typically this repository is included as a Git submodule and the snippets are referenced using AsciiDoc include directives.

Concept

This repository implements a lightweight documentation reuse pattern based on:

• AsciiDoc include directives

• Git submodules

• optional CI-based README generation

Typical workflow:

docs-master (submodule)
        ↓
include:: directives in README-source.adoc
        ↓
CI resolves includes
        ↓
generated README.adoc

This allows common documentation sections to be maintained in a single place and reused across many repositories.

Adding the repository as a submodule

To use the documentation snippets in another repository, add this repository as a Git submodule.

git submodule add https://github.com/gesinn-it-pub/gesinn-it-docs-master-pub docs-master
git submodule update --init

This will add the snippets under:

docs-master/

The path docs-master/ is the typical convention used in repositories that depend on these snippets.

Using documentation snippets

Snippets can be included in AsciiDoc documents using the standard include directive.

Example

include::docs-master/general/project-structure/docker-compose.adoc[]

Repositories typically include snippets inside README-source.adoc.

Updating the submodule

To update the documentation snippets to the latest version:

git submodule update --init --remote

After updating the submodule, commit the updated reference:

git add docs-master
git commit -m "Update documentation snippets"

Repositories may also automate this process via CI.

Generating the README

Repositories using shared documentation snippets often maintain two README files:

README-source.adoc
README.adoc

README-source.adoc is the editable source file and may contain include directives referencing snippets from this repository.

GitHub does not resolve AsciiDoc include directives when rendering documents. Therefore the README must be flattened before it can be displayed correctly.

This is done using asciidoctor-reducer.

README-source.adoc
        ↓
asciidoctor-reducer
        ↓
README.adoc

The generated README.adoc is committed to the repository so that GitHub displays the fully expanded documentation.

Important

README.adoc is a generated file and should not be edited manually. All changes must be made in README-source.adoc.

GitHub Actions integration

README generation can be automated using GitHub Actions.

Example workflow:

name: Build readme

on:
  push:
    paths:
      - README-source.adoc
    branches:
      - '**'
  workflow_dispatch:

jobs:

  build:
    timeout-minutes: 10
    runs-on: ubuntu-latest

    steps:
      - name: Install asciidoctor-reducer
        run: sudo gem install asciidoctor-reducer --pre

      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          submodules: 'true'

      - name: Reduce readme
        run: asciidoctor-reducer -o README.adoc README-source.adoc

      - name: Add autogenerated header
        run: |
          printf "// THIS FILE IS AUTO-GENERATED.\n// Edit README-source.adoc instead.\n\n" | cat - README.adoc > README.tmp
          mv README.tmp README.adoc

      - name: Commit readme
        uses: EndBug/add-and-commit@v9
        with:
          message: "Update generated README [skip ci]"

The workflow performs the following steps:

1. Install asciidoctor-reducer

2. Checkout the repository together with its submodules

3. Resolve all include directives in README-source.adoc

4. Generate a flattened README.adoc

5. Add a header indicating that the file is generated

6. Commit the generated README back to the repository

CI configuration

Repositories typically run tests using a separate CI workflow.

Since README generation commits changes to the repository, the CI workflow should ignore documentation-only updates.

Example CI trigger configuration:

on:
  push:
    branches: [ master ]
    paths-ignore:
      - README-source.adoc
      - README.adoc
  pull_request:
    branches: [ master ]
    paths-ignore:
      - README-source.adoc
      - README.adoc
  workflow_dispatch:

This ensures that:

• documentation updates do not trigger the full test matrix

• CI runs only for actual code changes

• README generation does not cause unnecessary CI runs

Rationale

Using shared documentation snippets provides several advantages:

• avoids duplicated documentation across repositories

• ensures consistent wording and structure

• simplifies maintenance of common documentation sections

• allows centralized updates across multiple projects

This approach enables lightweight documentation reuse without requiring a full documentation framework.