feat: generate YAML schema for config

.github/workflows/ci.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - develop
       - master
-      - '*'
+      - "*"
     tags:
       - "v*.*.*"
 
@@ -38,10 +38,10 @@ jobs:
             clang 18
             msvc >=14.40
             apple-clang *
-          standards: '20'
+          standards: "20"
           latest-factors: |
             msvc Optimized-Debug
-          factors: ''
+          factors: ""
           runs-on: |
             apple-clang: macos-15
           build-types: |
@@ -131,10 +131,10 @@ jobs:
         uses: alandefreitas/cpp-actions/[email protected]
         id: setup-cmake
         with:
-          version: '>=3.26'
-          check-latest: 'true'
-          update-environment: 'true'
-          trace-commands: 'true'
+          version: ">=3.26"
+          check-latest: "true"
+          update-environment: "true"
+          trace-commands: "true"
 
       - name: Setup Ninja
         uses: seanmiddleditch/gha-setup-ninja@v5
@@ -160,8 +160,8 @@ jobs:
         if: matrix.compiler != 'msvc'
         id: package-install
         env:
-          DEBIAN_FRONTEND: 'noninteractive'
-          TZ: 'Etc/UTC'
+          DEBIAN_FRONTEND: "noninteractive"
+          TZ: "Etc/UTC"
         with:
           apt-get: ${{ matrix.install }}
 
@@ -311,7 +311,7 @@ jobs:
         uses: alandefreitas/cpp-actions/[email protected]
         if: steps.llvm-cache.outputs.cache-hit != 'true' && steps.llvm-download.outputs.found != 'true'
         with:
-          cmake-version: '>=3.26'
+          cmake-version: ">=3.26"
           source-dir: ../third-party/llvm-project/llvm
           git-repository: https://github.com/llvm/llvm-project.git
           git-tag: ${{ matrix.llvm-hash }}
@@ -333,7 +333,7 @@ jobs:
         uses: alandefreitas/cpp-actions/[email protected]
         if: steps.llvm-cache.outputs.cache-hit != 'true' && steps.llvm-download.outputs.found != 'true'
         with:
-          cmake-version: '>=3.26'
+          cmake-version: ">=3.26"
           source-dir: ../third-party/llvm-project/runtimes
           build-dir: ${sourceDir}/build-libcxx
           build-target: ${{ matrix.libcxx-targets }}
@@ -351,12 +351,12 @@ jobs:
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: "20"
 
       - name: CMake Workflow
         uses: alandefreitas/cpp-actions/[email protected]
         with:
-          cmake-version: '>=3.26'
+          cmake-version: ">=3.26"
           cxxstd: ${{ matrix.cxxstd }}
           cc: ${{ steps.setup-cpp.outputs.cc || matrix.cc }}
           ccflags: ${{ matrix.mrdocs-ccflags }}
@@ -383,6 +383,9 @@ jobs:
           package-generators: ${{ matrix.mrdocs-package-generators }}
           package-artifact: false
 
+      - name: Check YAML schema
+        run: npx ajv compile -s docs/mrdocs.schema.json
+
       - name: Upload GitHub Release Artifacts
         if: ${{ matrix.is-main && matrix.compiler != 'clang' }}
         uses: actions/upload-artifact@v4
@@ -404,13 +407,13 @@ jobs:
         if: ${{ matrix.coverage }}
         uses: codecov/[email protected]
         with:
-          directory: './build'
+          directory: "./build"
           fail_ci_if_error: true
           gcov: true
           verbose: true
 
   releases:
-    needs: [ cpp-matrix, build ]
+    needs: [cpp-matrix, build]
     if: ${{ needs.cpp-matrix.outputs.releases-matrix != '[]' && needs.cpp-matrix.outputs.releases-matrix != '' }}
     strategy:
       fail-fast: false
@@ -444,7 +447,7 @@ jobs:
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: "18"
 
       - name: Setup Ninja
         uses: seanmiddleditch/gha-setup-ninja@v5
@@ -495,7 +498,7 @@ jobs:
           modules: url
           boost-dir: boost
           modules-scan-paths: '"test example"'
-          modules-exclude-paths: ''
+          modules-exclude-paths: ""
           trace-commands: true
 
       - name: Set up llvm-symbolizer
@@ -514,7 +517,7 @@ jobs:
                   exit 1
               fi
           fi
-          
+
           # Step 3: Ensure llvm-symbolizer is in your PATH
           llvm_bin_path=$(brew --prefix)/opt/llvm/bin
           PATH="$PATH:$llvm_bin_path"
@@ -525,12 +528,12 @@ jobs:
           else
               echo "llvm-symbolizer found at: $LLVM_SYMBOLIZER_PATH"
           fi
-          
+
           # Step 4: Export LLVM_SYMBOLIZER_PATH environment variable
           export LLVM_SYMBOLIZER_PATH="$LLVM_SYMBOLIZER_PATH"
           echo -e "LLVM_SYMBOLIZER_PATH=$LLVM_SYMBOLIZER_PATH" >> $GITHUB_ENV
           echo "Environment variable LLVM_SYMBOLIZER_PATH set to: $LLVM_SYMBOLIZER_PATH"
-          
+
       - name: Generate Landing Page
         working-directory: docs/website
         run: |
@@ -580,7 +583,7 @@ jobs:
             "adoc"
             "xml"
           )
-          
+
           # Generate the demos for each variant and generator
           for variant in single multi; do
             for generator in "${generators[@]}"; do
@@ -590,7 +593,7 @@ jobs:
               echo "Number of files in demos/boost-url/$variant/$format: $(find demos/boost-url/$variant/$format -type f | wc -l)"
             done
           done
-          
+
           # Compress demos for the artifact
           tar -cjf $(pwd)/demos.tar.gz -C $(pwd)/demos --strip-components 1 .
           echo "demos_path=$(pwd)/demos.tar.gz" >> $GITHUB_ENV
@@ -699,7 +702,7 @@ jobs:
           # Copy files: This step will copy the landing page and the documentation to www.mrdocs.com
           chmod 755 -R $(pwd)/build/website
           scp -o StrictHostKeyChecking=no -r $(pwd)/build/website/* [email protected]:/var/www/mrdox.com/
-          
+
           # Remove previous demos associated with this tag
           demo_dir="/var/www/mrdox.com/demos/${{ github.ref_name }}"
           ssh -o StrictHostKeyChecking=no [email protected] "rm -rf $demo_dir/boost-url; mkdir -p $demo_dir/boost-url"
@@ -738,7 +741,7 @@ jobs:
           token: ${{ github.token }}
 
   llvm-releases:
-    needs: [ cpp-matrix, build ]
+    needs: [cpp-matrix, build]
     if: ${{ needs.cpp-matrix.outputs.llvm-matrix != '[]' && needs.cpp-matrix.outputs.llvm-matrix != '' }}
     strategy:
       fail-fast: false
@@ -804,10 +807,10 @@ jobs:
         run: |
           # LLVM is be installed with the default compiler
           set -x
-          
+
           # Compress the LLVM installation
           cd ../third-party/llvm-project
-          
+
           # Use 7z on windows
           if [[ ${{ runner.os }} == 'Windows' ]]; then
               7z a -t7z -m0=lzma2 -mx=9 -mfb=64 -md=32m -ms=on ${{ matrix.llvm-archive-filename }} install
@@ -820,15 +823,15 @@ jobs:
         working-directory: ../third-party/llvm-project
         run: |
           set -x
-          
+
           # Ensure required commands exist
           for cmd in ssh-keyscan ssh-agent ssh-add scp; do
             if ! command -v $cmd >/dev/null; then
               echo "$cmd not found"
               exit 1
             fi
           done
-          
+
           # Add SSH key
           mkdir -p ~/.ssh
           ssh-keyscan dev-websites.cpp.al >> ~/.ssh/known_hosts
@@ -845,4 +848,3 @@ jobs:
           llvm_dir="/var/www/mrdox.com/llvm+clang"
           chmod 755 ${{ matrix.llvm-archive-filename }}
           scp -o StrictHostKeyChecking=no $(pwd)/${{ matrix.llvm-archive-filename }} [email protected]:$llvm_dir/
-

docs/modules/ROOT/attachments/mrdocs.schema.json

@@ -0,0 +1 @@
+../../../mrdocs.schema.json

docs/modules/ROOT/pages/config-file.adoc

@@ -13,6 +13,19 @@ include::partial$mrdocs-example.yml[]
 The xref:usage.adoc[Usage] page provides a detailed explanation of what to combine options from the configuration file and the command line.
 The <<config-options-reference>> section provides a detailed explanation of the options available.
 
+== YAML Schema
+
+To get linting and autocompletion in the config file, a schema for the config can be specified.
+In JetBrains IDEs, `# $schema: <url>` can be used to bind a schema to a file.
+In editors with plugins based on the https://github.com/redhat-developer/yaml-language-server[YAML language server], `# yaml-language-server: $schema=<url>` can be used.
+The schema for `mrdocs.yml` is provided xref:attachment$mrdocs.schema.json[here].
+The following shows an example of a file specifying an inline-schema that's compatible with JetBrains IDEs and editors using the YAML language server.
+
+[source,yaml]
+--------
+include::partial$mrdocs-schema-example.yml[]
+--------
+
 == Build Options
 
 A number of options can be used to specify with which compile options MrDocs should be run.

docs/modules/ROOT/partials/mrdocs-schema-example.yml

@@ -0,0 +1,6 @@
+# $schema: https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json
+# yaml-language-server: $schema=https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json
+
+source-root: ../include
+multipage: false
+generate: adoc