Skip to content

OpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub

Add check for YAML header syntax in docs README files

Christophe Bliard04ec392d1420
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index 4f20f7e14c7..9fef6f9dfd3 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -28,3 +28,12 @@ jobs:
steps:
- uses: actions/checkout@v5
- run: script/docs/check_readme_case
+ docs-readme-yaml-header-syntax-check:
+ name: Check README.md YAML header syntax in documentation
+ runs-on: [ubuntu-latest]
+ steps:
+ - uses: actions/checkout@v5
+ - uses: ruby/setup-ruby@v1
+ with:
+ bundler-cache: true
+ - run: script/docs/check_readme_yaml_header_syntax
diff --git a/script/docs/check_readme_yaml_header_syntax b/script/docs/check_readme_yaml_header_syntax
new file mode 100755
index 00000000000..b88df4c8560
--- /dev/null
+++ b/script/docs/check_readme_yaml_header_syntax
@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Script to check YAML header syntax in README files
+# Checks for proper YAML front matter between --- lines
+# Exits with error code 1 if any issues are found
+
+# Function to check YAML header syntax
+check_yaml_header() {
+ local file="$1"
+ local yaml_header=""
+
+ # skip when no header YAML is found
+ if head -n1 "$file" | grep --invert-match --quiet "^---"; then
+ return 0
+ fi
+
+ yaml_header=$(sed -n '/^--- *$/,/^--- */p' "$file")
+ yaml_error=$(echo "$yaml_header" | ruby -ryaml -e "
+ begin
+ YAML.safe_load(STDIN.read, permitted_classes: [Date, Time])
+ rescue => e
+ puts e.to_s.delete_prefix('(<unknown>): ')
+ end")
+
+ if [ -n "$yaml_error" ]; then
+ echo "ERROR: invalid YAML syntax in $file"
+ echo "YAML header:"
+ echo "$yaml_header"
+ echo "YAML error:"
+ echo "$yaml_error"
+ echo
+ return 1
+ fi
+
+ return 0
+}
+
+# Main script logic
+DOCS_DIR="docs"
+ERRORS_FOUND=0
+
+echo "Checking YAML header syntax in $DOCS_DIR README files..."
+
+# Find all README.md files in the docs directory
+while IFS= read -r -d '' file; do
+ # Check if file has proper YAML header
+ if ! check_yaml_header "$file"; then
+ ERRORS_FOUND=1
+ fi
+done < <(find "$DOCS_DIR" -name "README.md" -type f -print0)
+
+if [ "$ERRORS_FOUND" -eq 1 ]; then
+ echo ""
+ echo "🔴 Found YAML header syntax errors in README files."
+ echo "Please fix the issues above."
+ exit 1
+else
+ echo "🟢 All README files have correct YAML header syntax."
+ exit 0
+fi