This is the architecture documentation for the personal profile (Website, CV, several outputs more) of Dieter Baier.

You can check the outputs for example on:

The project is not just documentation.

It is a working example of:

  • Documentation as Code

  • Multi-target publishing

  • Reproducible builds

Introduction and Goals

Motivation

Maintaining a personal profile across multiple platforms (GitHub, GitLab, personal website, CV) leads to duplication and inconsistencies.

This project provides a unified solution based on the idea:

"Write once, publish everywhere."

Goals

  • Single source of truth for all profile information

  • Generation of multiple output formats:

    • HTML (website)

    • PDF (CV)

    • Markdown (README)

  • Environment-specific data injection (e.g. private contact details)

  • Fully reproducible builds

Quality Goals

Quality Description

Reproducibility

Same output regardless of environment

Maintainability

Clear structure and modular build pipeline

Automation

Fully automated generation and deployment

Flexibility

Different outputs from same source

Architecture Constraints

  • Use of AsciiDoc as primary authoring format

  • Use of Gradle as build system

  • No proprietary tools (open source only)

  • Docker support for reproducible environments

  • CI/CD via GitHub Actions

Technical constraints:

  • Pandoc required for Markdown conversion

  • Graphviz required for diagrams

System Scope and Context

Business Context

Diagram

Technical Context

  • Input: AsciiDoc files

  • Processing:

    • Asciidoctor

    • Pandoc

  • Output:

    • HTML

    • PDF

    • Markdown

Solution Strategy

Build Pipeline Strategy

Context

The project uses a GitHub Actions based pipeline to build and deploy documentation artifacts (README, site, architecture).

Goals

  • Minimize unnecessary builds

  • Ensure reproducibility

  • Reduce resource consumption (Green IT)

  • Keep pipeline maintainable and deterministic

Solution

The pipeline is structured into four logical stages:

Diagram
1. Immutable Build Environment
A Docker image is used as the build environment

  • Tagged using a hash of Dockerfile and .dockerignore

  • Built only when relevant files change

  • Cached using registry-based layer caching

2. Change Detection

File-based change detection is implemented using path filters.

Categories

  • README

  • Architecture

  • Site

This enables selective execution of build tasks.

3. Conditional Build Execution
Only required Gradle tasks are executed

  • buildReadme

  • buildArchitecture

  • buildSite

If no relevant changes are detected, the build step is skipped entirely.

4. Artifact-Based Deployment
Artifacts are

  • generated once

  • uploaded

  • consumed by a dedicated deploy stage

Deployment targets

  • GitHub profile README

  • GitLab profile README

  • GitHub Pages

  • personal domain

Consequences

Advantages

  • Reduced pipeline runtime

  • Lower resource consumption

  • Deterministic builds

  • Clear separation of concerns

Trade-offs

  • Increased pipeline complexity

  • Additional maintenance for path filters

Building Block View

Overview

The system consists of the following main building blocks:

Component Responsibility

Gradle

Orchestration of the build pipeline

Asciidoctor

Conversion of AsciiDoc to HTML/PDF

Pandoc

Conversion of DocBook to Markdown

Docker

Provides reproducible runtime environment

GitHub Actions

CI/CD execution

Internal Structure

Diagram

Runtime View

Build Process

Diagram

Architecture Decisions

ADR-001: Use AsciiDoc as single source

AsciiDoc provides:

  • rich structure

  • includes

  • flexibility for multiple outputs

ADR-002: Use Gradle for orchestration

Gradle allows:

  • task orchestration

  • dependency management

  • extensibility

ADR-003: Use Docker for reproducibility

Docker ensures:

  • identical environments

  • no local setup required

ADR-004: Use Pandoc for Markdown conversion

Pandoc provides:

  • reliable format transformation

  • high-quality Markdown output