feat(docs): add mkdocs configuration for site documentation and navigation

Author: vp

.github/workflows/pages.yml

@@ -0,0 +1,72 @@
+name: Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  publish:
+    name: Build and publish landing site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Build site
+        shell: pwsh
+        run: |
+          ./docs/site/scripts/build-pages.ps1
+
+      - name: Verify static output
+        run: |
+          test -f .github/pages/index.html
+
+      - name: Publish to gh-pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          SITE_DIR="${GITHUB_WORKSPACE}/.github/pages"
+          TARGET_DIR="$(mktemp -d)"
+          REMOTE_URL="https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          if git ls-remote --exit-code --heads "${REMOTE_URL}" gh-pages >/dev/null 2>&1; then
+            git clone --depth 1 --branch gh-pages "${REMOTE_URL}" "${TARGET_DIR}"
+          else
+            git init "${TARGET_DIR}"
+            (
+              cd "${TARGET_DIR}"
+              git checkout --orphan gh-pages
+              git remote add origin "${REMOTE_URL}"
+            )
+          fi
+
+          find "${TARGET_DIR}" -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} +
+          cp -R "${SITE_DIR}/." "${TARGET_DIR}/"
+          touch "${TARGET_DIR}/.nojekyll"
+
+          (
+            cd "${TARGET_DIR}"
+            git add -A
+            if git diff --cached --quiet; then
+              echo "No site changes to publish."
+              exit 0
+            fi
+            git commit -m "docs: publish site for ${GITHUB_SHA}"
+            git push origin HEAD:gh-pages --force
+          )

.gitignore

@@ -57,6 +57,8 @@ dlldata.c
 
 # Benchmark Results
 BenchmarkDotNet.Artifacts/
+.github/pages/
+docs/site/reference/
 
 # .NET Core
 project.lock.json
@@ -423,4 +425,4 @@ FodyWeavers.xsd
 /.tmp/
 .claude
 _tmp**
-.temp**
+.temp**

.vscode/tasks.json

@@ -141,6 +141,49 @@
         "group": "test",
         "problemMatcher": "$msCompile"
     },
+    {
+        "label": "Docs - sync",
+        "type": "process",
+        "command": "pwsh",
+        "args": [
+            "-File",
+            "${workspaceFolder}/docs/site/scripts/sync-docs.ps1"
+        ],
+        "problemMatcher": []
+    },
+    {
+        "label": "Docs - landing page serve",
+        "type": "process",
+        "command": "pwsh",
+        "args": [
+            "-File",
+            "${workspaceFolder}/docs/site/scripts/serve-pages.ps1"
+        ],
+        "isBackground": true,
+        "problemMatcher": {
+            "pattern": [],
+            "background": {
+                "activeOnStart": true,
+                "beginsPattern": ".",
+                "endsPattern": "Serving on .*:8000/"
+            }
+        },
+        "presentation": {
+            "reveal": "always",
+            "panel": "dedicated",
+            "clear": false
+        }
+    },
+    {
+        "label": "Docs - landing page build",
+        "type": "process",
+        "command": "pwsh",
+        "args": [
+            "-File",
+            "${workspaceFolder}/docs/site/scripts/build-pages.ps1"
+        ],
+        "problemMatcher": []
+    },
     {
         "label": "WeatherForecast - build",
         "command": "dotnet",

README.md

@@ -12,15 +12,24 @@
 - [](#)
   - [Introduction](#introduction)
   - [Documentation](#documentation)
-  - [Feature Highlights](#feature-highlights)
-    - [Core domain and application](#core-domain-and-application)
-    - [Execution, messaging and modularity](#execution-messaging-and-modularity)
-    - [Presentation and host](#presentation-and-host)
-    - [Storage, scheduling and operations](#storage-scheduling-and-operations)
-    - [Common building blocks](#common-building-blocks)
+  - [Features](#features)
+    - [Common Infrastructure](#common-infrastructure)
+    - [Core Domain and Application](#core-domain-and-application)
+    - [Execution, Messaging and Modularity](#execution-messaging-and-modularity)
+    - [Security and Access](#security-and-access)
+    - [Presentation and Host](#presentation-and-host)
+    - [Storage, Scheduling and Utilities](#storage-scheduling-and-utilities)
+    - [Testing and Test Utilities](#testing-and-test-utilities)
   - [Libraries used (excerpt):](#libraries-used-excerpt)
   - [Example projects](#example-projects)
   - [Performance Benchmarks](#performance-benchmarks)
+  - [GitHub Pages](#github-pages)
+    - [Source structure](#source-structure)
+    - [Which Markdown files get into the site](#which-markdown-files-get-into-the-site)
+    - [Add a new documentation page](#add-a-new-documentation-page)
+    - [Local preview and build](#local-preview-and-build)
+    - [Publishing through GitHub Actions](#publishing-through-github-actions)
+    - [Typical workflow for docs updates](#typical-workflow-for-docs-updates)
   - [Collaboration](#collaboration)
   - [Commit Policy](#commit-policy)
   - [License](#license)
@@ -43,36 +52,40 @@ the [CHANGELOG](https://raw.githubusercontent.com/bridgingIT/bITdevKit/main/CHAN
 
 ## Documentation
 
-The best entry point into the current documentation set is the
-[Documentation Index](./docs/INDEX.md).
+The public documentation site is available at
+[bridgingit-gmbh.github.io/bITdevKit](https://bridgingit-gmbh.github.io/bITdevKit/).
 
-Recommended starting path:
+The best entry point into the current documentation set is the
+[Documentation](./docs/INDEX.md) and [Introduction to DDD in bITdevKit](./docs/introduction-ddd-guide.md).
 
-- [Domain](./docs/features-domain.md)
-- [Results](./docs/features-results.md)
-- [Requester and Notifier](./docs/features-requester-notifier.md)
-- [Modules](./docs/features-modules.md)
-- [Presentation Endpoints](./docs/features-presentation-endpoints.md)
+## Features
 
-Additional entry points:
+### Common Infrastructure
 
-- [Introduction to DDD in bITdevKit](./docs/introduction-ddd-guide.md)
-- [Testing Common XUnit](./docs/testing-common-xunit.md)
-- [Fake Authentication for Integration Tests](./docs/testing-fake-authentication.md)
-
-## Feature Highlights
+- [Common Extensions](./docs/common-extensions.md)
+- [Common Utilities](./docs/common-utilities.md)
+- [Common Serialization](./docs/common-serialization.md)
+- [Common Options Builders](./docs/common-options-builders.md)
+- [Common Mapping](./docs/common-mapping.md)
+- [Common Caching](./docs/common-caching.md)
+- [Common Observability Tracing](./docs/common-observability-tracing.md)
 
-### Core domain and application
+### Core Domain and Application
 
 - [Domain](./docs/features-domain.md)
 - [Domain Events](./docs/features-domain-events.md)
+- [Event Sourcing](./docs/features-event-sourcing.md)
 - [Domain Repositories](./docs/features-domain-repositories.md)
 - [Domain Specifications](./docs/features-domain-specifications.md)
+- [ActiveEntity](./docs/features-domain-activeentity.md)
+- [Domain Policies](./docs/features-domain-policies.md)
+- [Rules](./docs/features-rules.md)
 - [Results](./docs/features-results.md)
 - [Application Commands and Queries](./docs/features-application-commands-queries.md)
 - [Application Events](./docs/features-application-events.md)
+- [DataPorter](./docs/features-application-dataporter.md)
 
-### Execution, messaging and modularity
+### Execution, Messaging and Modularity
 
 - [Requester and Notifier](./docs/features-requester-notifier.md)
 - [Messaging](./docs/features-messaging.md)
@@ -81,16 +94,22 @@ Additional entry points:
 - [Modules](./docs/features-modules.md)
 - [Pipelines](./docs/features-pipelines.md)
 - [Filtering](./docs/features-filtering.md)
+- [Extensions](./docs/features-extensions.md)
+
+### Security and Access
+
+- [Entity Permissions](./docs/features-entitypermissions.md)
+- [Fake Identity Provider](./docs/features-identityprovider.md)
 
-### Presentation and host
+### Presentation and Host
 
 - [Presentation Endpoints](./docs/features-presentation-endpoints.md)
 - [Console Commands](./docs/features-presentation-console-commands.md)
 - [CORS Configuration](./docs/features-presentation-cors.md)
 - [Exception Handling](./docs/features-presentation-exception-handling.md)
 - [AppState](./docs/features-presentation-appstate.md)
 
-### Storage, scheduling and operations
+### Storage, Scheduling and Utilities
 
 - [StartupTasks](./docs/features-startuptasks.md)
 - [JobScheduling](./docs/features-jobscheduling.md)
@@ -99,15 +118,10 @@ Additional entry points:
 - [Storage Monitoring](./docs/features-storage-monitoring.md)
 - [Log Entries](./docs/features-log-entries.md)
 
-### Common building blocks
+### Testing and Test Utilities
 
-- [Common Extensions](./docs/common-extensions.md)
-- [Common Utilities](./docs/common-utilities.md)
-- [Common Serialization](./docs/common-serialization.md)
-- [Common Options Builders](./docs/common-options-builders.md)
-- [Common Mapping](./docs/common-mapping.md)
-- [Common Caching](./docs/common-caching.md)
-- [Common Observability Tracing](./docs/common-observability-tracing.md)
+- [Fake Authentication for Integration Tests](./docs/testing-fake-authentication.md)
+- [Testing Common XUnit](./docs/testing-common-xunit.md)
 
 ## Libraries used (excerpt):
 
@@ -158,6 +172,93 @@ dotnet run -c Release --project benchmarks/Common.Benchmarks/Common.Benchmarks.c
 
 For more details, see the `Common.Benchmarks` project in the `benchmarks/` folder.
 
+## GitHub Pages
+
+The repository includes a MkDocs-based GitHub Pages site with:
+
+- a landing page under `docs/site/`
+- curated technical docs synced from `./docs`
+
+Public site:
+[https://bridgingit-gmbh.github.io/bITdevKit/](https://bridgingit-gmbh.github.io/bITdevKit/)
+
+### Source structure
+
+- `docs/site/`
+  - the site-specific source pages such as the landing page, getting started pages, templates page, styling, and helper scripts
+- `docs/`
+  - the framework documentation source that is selectively imported into the public site
+- `.github/pages/`
+  - the generated static MkDocs output
+
+### Which Markdown files get into the site
+
+The sync step currently imports these files from `./docs` into the public site:
+
+- `INDEX.md`
+- `introduction-ddd-guide.md`
+- `common-*.md`
+- `features-*.md`
+- `testing-*.md`
+
+The following are intentionally excluded from GitHub Pages:
+
+- `docs/adr/`
+- `docs/presentations/`
+- `docs/specs/`
+- `src/**`
+
+### Add a new documentation page
+
+For a new Markdown page from `./docs` to appear in GitHub Pages:
+
+1. Add or update the Markdown file under `./docs`.
+2. Make sure its filename matches one of the currently imported patterns above.
+3. If it should appear in navigation, add it to [mkdocs.yml](./mkdocs.yml) under the appropriate section.
+4. Regenerate the site locally or push to `main` so GitHub Actions publishes it.
+
+### Local preview and build
+
+Preview the full site locally with Docker:
+
+```powershell
+pwsh -File ./docs/site/scripts/serve-pages.ps1
+```
+
+or use the VS Code Tasks for the same command.
+Build the full static site locally:
+
+```powershell
+pwsh -File ./docs/site/scripts/build-pages.ps1
+```
+
+That build command performs these steps:
+
+1. Synchronize the selected public docs from `./docs` into `docs/site/reference/`
+2. Build the MkDocs site in Docker
+3. Write the generated static site to `./.github/pages/`
+
+### Publishing through GitHub Actions
+
+The Pages workflow is defined in [pages.yml](./.github/workflows/pages.yml).
+
+On each push to `main`, it:
+
+1. checks out the repository
+2. runs `./docs/site/scripts/build-pages.ps1`
+3. verifies that `./.github/pages/index.html` was generated
+4. publishes the generated site to the `gh-pages` branch
+
+### Typical workflow for docs updates
+
+Typical documentation workflow:
+
+1. Edit or add Markdown under `./docs`
+2. If needed, update [mkdocs.yml](./mkdocs.yml) so the page is reachable in navigation
+3. Run `pwsh -File ./docs/site/scripts/serve-pages.ps1` to preview the result
+4. Run `pwsh -File ./docs/site/scripts/build-pages.ps1` to generate the final static output
+5. Commit and push to `main` to publish via GitHub Actions
+
 ## Collaboration
 
 Simply create a pull request with your ideas or contact us.