itsallcode · redcatbear · Sep 13, 2026 · Sep 13, 2026 · Sep 13, 2026 · Sep 13, 2026
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -3,7 +3,16 @@ name: Deploy GitHub Pages
 on:
   push:
     branches: ["main"]
+  pull_request:
+  release:
+    types: [published]
   workflow_dispatch:
+    inputs:
+      deploy:
+        description: "Deploy to GitHub Pages"
+        required: false
+        type: boolean
+        default: true
 
 concurrency:
   group: "pages"
@@ -13,6 +22,8 @@ jobs:
   build:
     permissions:
       contents: read
+      pages: write
+      id-token: write
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -24,15 +35,24 @@ jobs:
       - name: Build with Jekyll
         uses: actions/jekyll-build-pages@v1
         with:
-          source: ./doc
+          source: .
           destination: ./_site
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v5
         with:
           path: ./_site/
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: github-pages-preview
+          path: ./_site/
 
   deploy:
-    if: ${{ github.ref == 'refs/heads/main' }}
+    # Publishing on push to main, release or manual dispatch.
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && (inputs.deploy || inputs.deploy == null)) }}
     permissions:
       id-token: write
       pages: write

diff --git a/AGENTS.md b/AGENTS.md
@@ -108,8 +108,9 @@ Needs: impl, utest
 - **Detailed Skills**: See [`.agents/skills`](.agents/skills) for domain knowledge (ID syntax, keywords).
 - **Key Resources**:
   - `README.md`: General overview.
-  - `doc/developer_guide.md`: Detailed build and internal info.
+  - `doc/developer_guide/developer_guide.md`: Detailed build and internal info.
   - `doc/user_guide/user_guide.md`: Comprehensive tool usage.
+  - `doc/terminology.md`: Unified terminology for all documents.
   - `CONTRIBUTING.md`: Human-AI collaboration guidelines.
   - `doc/spec/system_requirements.md`: System requirements specification.
   - `doc/spec/design.md`: High-level design documentation.

diff --git a/CNAME b/CNAME
@@ -0,0 +1 @@
+openfasttrace.itsallcode.org
diff --git a/Gemfile b/Gemfile
@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+gem "github-pages", group: :jekyll
+gem "jekyll-remote-theme"
+gem "jekyll-include-cache"
+gem "faraday-retry"
diff --git a/README.md b/README.md
@@ -32,6 +32,7 @@ Sonarcloud status:
 **User Guides and Tools**
 
 * [📖 User Guide](doc/user_guide/user_guide.md)
+* [📚 Terminology](doc/terminology.md)
 * [🔌 Extending OpenFastTrace With Plugins](doc/plugins.md)
 * [💲 Command Line Usage](core/src/main/resources/usage.txt)
 * [🛠 IntelliJ Plugin (PyCharm, Clion, etc.)](https://github.com/itsallcode/openfasttrace-intellij-plugin)
@@ -52,8 +53,8 @@ Sonarcloud status:
 **Information for Contributors**
 
 * [🎟️ Project Board](https://github.com/orgs/itsallcode/projects/3/views/1)
-* [🦮 Developer Guide](doc/developer_guide.md)
-* [🔌 Plugin Developer Guide](doc/plugin_developer_guide.md)
+* [🦮 Developer Guide](doc/developer_guide/developer_guide.md)
+* [🔌 Plugin Developer Guide](doc/developer_guide/plugin_developer_guide.md)
 * [🎁 Contributing Guide](CONTRIBUTING.md)
 * [🤝 Code of Conduct](CODE_OF_CONDUCT.md)
 * [🤖 AI Agent Guide](AGENTS.md)
@@ -84,7 +85,7 @@ Pre-Built JAR files (called `openfasttrace-4.9.0.jar`) are available from the fo
 * [Maven Central](https://repo1.maven.org/maven2/org/itsallcode/openfasttrace/openfasttrace/4.9.0/openfasttrace-4.9.0.jar)
 * [GitHub](https://github.com/itsallcode/openfasttrace/releases/download/4.9.0/openfasttrace-4.9.0.jar)
 
-Check our [developer guide](doc/developer_guide.md#getting-the-openfasttrace-library) to learn how to use the OFT JAR as dependency in your own code with popular build tools.
+Check our [developer guide](doc/developer_guide/developer_guide.md#getting-the-openfasttrace-library) to learn how to use the OFT JAR as dependency in your own code with popular build tools.
 
 ## Installation
 
@@ -135,6 +136,6 @@ If you want to run OFT in a CI build, you can use the OFT wrapper script [oftw.s
 
 ## Development
 
-If you want to learn how to build OpenFastTrace, please check our [Developer Guide](doc/developer_guide.md).
+If you want to learn how to build OpenFastTrace, please check our [Developer Guide](doc/developer_guide/developer_guide.md).
 
 You would like to contribute to OFT? Please check out our [Contributor Guide](CONTRIBUTING.md) to get started. 
diff --git a/_config.yml b/_config.yml
@@ -0,0 +1,50 @@
+title: OpenFastTrace
+description: Requirement tracing suite for Agile Development
+source: doc
+destination: _site
+
+remote_theme: just-the-docs/just-the-docs
+
+plugins:
+  - jekyll-remote-theme
+  - jekyll-seo-tag
+  - jekyll-include-cache
+
+# Site settings
+url: "https://openfasttrace.itsallcode.org"
+baseurl: ""
+
+# Navigation bar logo
+logo: "/images/openfasttrace_logo.svg"
+
+# Aux links for the sidebar
+aux_links:
+  "OpenFastTrace on GitHub":
+    - https://github.com/itsallcode/openfasttrace
+
+# Heading anchor links
+heading_anchors: true
+
+# Search configuration
+search_enabled: true
+search:
+  tokenizer_separator: /[\s/]+/
+  rel_prefix: true
+
+# Footer content
+footer_content: ""
+
+# Color scheme
+color_scheme: light
+
+# Exclude list
+exclude:
+  - vendor
+  - .bundle
+  - .jekyll-cache
+  - .jekyll-metadata
+  - Gemfile
+  - Gemfile.lock
+
+include:
+  - CNAME
diff --git a/doc/CNAME b/doc/CNAME
@@ -0,0 +1 @@
+openfasttrace.itsallcode.org
diff --git a/doc/OFT-Ideas-and-Proposals.pdf b/doc/OFT-Ideas-and-Proposals.pdf
diff --git a/doc/about_us.md b/doc/about_us.md
@@ -1,3 +1,8 @@
+---
+layout: default
+title: About us
+nav_order: 7
+---
 
 # About us
 

diff --git a/doc/changes/changes.md b/doc/changes/changes.md
@@ -1,3 +1,9 @@
+---
+layout: default
+title: Changelog
+nav_order: 8
+---
+
 # Changes
 
 * [4.10.0](changes_4.10.0.md)

diff --git a/doc/changes/changes_4.0.1.md b/doc/changes/changes_4.0.1.md
@@ -4,7 +4,7 @@ Code name: Allow numbers after dots in specification item names
 
 ## Summary
 
-This release allows using specification item names with dots `.` followed by numbers, e.g. `req~SR.AB.1.1.1~1`. We also updated the relevant [section in the user guide](../user_guide/user_guide.md#specification-item-name). Thanks to [@RobertZickler](https://github.com/RobertZickler) for reporting this!
+This release allows using specification item names with dots `.` followed by numbers, e.g. `req~SR.AB.1.1.1~1`. We also updated the relevant [section in the user guide](../user_guide/introduction/concepts_and_terms.md#specification-item-name). Thanks to [@RobertZickler](https://github.com/RobertZickler) for reporting this!
 
 ## Bugfixes
 

diff --git a/doc/changes/changes_4.1.0.md b/doc/changes/changes_4.1.0.md
@@ -7,7 +7,7 @@ Code name: Third-party plugins
 This release adds support for loading third-party plugins from external JAR files. See the documentation for details:
 
 * [Installation](../plugins.md)
-* [Plugin developer guide](../plugin_developer_guide.md)
+* [Plugin developer guide](../developer_guide/plugin_developer_guide.md)
 
 The release also adds command line option `--log-level` that allows configuring the log level. Possible values are `OFF`, `SEVERE`, `WARNING`, `INFO`, `CONFIG`, `FINE`, `FINER`, `FINEST`, `ALL`. The default log level is `WARNING`.
 

diff --git a/doc/developer_guide.md → doc/developer_guide/developer_guide.md b/doc/developer_guide.md → doc/developer_guide/developer_guide.md
@@ -1,14 +1,21 @@
+---
+layout: default
+title: Developer Guide
+nav_order: 3
+has_children: true
+---
+
 # OpenFastTrace Developer Guide
 
 This document contains technical information for developers contributing to OpenFastTrace (short OFT).
 
-If you want to know more about how to contribute to OFT, please check out our [Contributor Guide](../CONTRIBUTING.md).
+If you want to know more about how to contribute to OFT, please check out our [Contributor Guide](../../CONTRIBUTING.md).
 
 ## Getting the OpenFastTrace Library
 
 ### Getting OFT via Maven
 
-To use OpenFastTrace as a dependency in your [Maven](https://maven.apache.org) project add this to your `pom.xml`:
+To use OpenFastTrace as a dependency in your [Maven](https://maven.apache.org) project add this to your `../../pom.xml`:
 
 ```xml
 <dependencies>
@@ -122,7 +129,7 @@ Build OFT:
 mvn -T 1C package -DskipTests
 ```
 
-This will build the executable JAR including all modules at `product/target/openfasttrace-$VERSION.jar`.
+This will build the executable JAR including all modules at `product/target/openfasttrace-<version>.jar`. (Please check for the latest version in the releases if you are downloading a pre-built JAR.)
 
 #### Specify Java Version
 
@@ -189,7 +196,7 @@ Import as a Maven project using *"File" &rarr; "Import..." &rarr; "Maven" &rarr;
 
 All subprojects come with formatter and save actions configuration for Eclipse.
 
-If you use a different IDE like IntelliJ, please import the formatter configuration [itsallcode_formatter.xml](itsallcode_formatter.xml).
+If you use a different IDE like IntelliJ, please import the formatter configuration [itsallcode_formatter.xml](../itsallcode_formatter.xml).
 
 ## Configure Logging
 
@@ -262,9 +269,9 @@ mvn package
 2. Create a new "prepare-release" branch.
 3. Update the version in
     * `openfasttrace-parent/pom.xml` (`revision` property)
-    * `README.md`
+    * `../../README.md`
     * `doc/developer_guide.md`
-4. Add changes in a new version to `doc/changes/changes.md` and `doc/changes/changes_$VERSION.md` and update the release date.
+4. Add changes in a new version to `../changes/changes.md` and `doc/changes/changes_$VERSION.md` and update the release date.
 5. Commit and push changes.
 6. Create a new pull request, have it reviewed and merged to `main`.
 

diff --git a/doc/plugin_developer_guide.md → ...developer_guide/plugin_developer_guide.md b/doc/plugin_developer_guide.md → ...developer_guide/plugin_developer_guide.md
@@ -1,6 +1,12 @@
+---
+layout: default
+title: Plugin Developer Guide
+parent: Developer Guide
+---
+
 # Plugin Developer Guide
 
-This guide describes how to develop [plugins](plugins.md) for OpenFastTrace (OFT).
+This guide describes how to develop [plugins](../plugins.md) for OpenFastTrace (OFT).
 
 ## Initial Setup
 

diff --git a/doc/images/openfasttrace_logo.svg b/doc/images/openfasttrace_logo.svg