chore: enhance documentation generation with link fixing and front matter updates

mokhld · mokhld · commit 8d20c5ce3b04 · 2025-04-07T22:12:16.000+01:00
- Added a JavaScript file to fix links in the generated documentation, ensuring they include the correct baseurl.
- Updated the fix-schema-links.sh script to handle absolute and relative links more effectively.
- Enhanced process-docs.sh to add front matter to root markdown files, improving navigation and organization.
- Adjusted the test-docs-generation.yml workflow to ensure proper execution of scripts and verification of documentation output.
diff --git a/.github/scripts/docs/create-jekyll-config.sh b/.github/scripts/docs/create-jekyll-config.sh
@@ -162,4 +162,33 @@ table {
 }
 EOF
 
+# Add Javascript to fix any remaining links
+echo "📝 Creating link-fixer JavaScript..."
+mkdir -p site-src/assets/js
+cat > site-src/assets/js/fix-links.js << 'EOF'
+document.addEventListener('DOMContentLoaded', function() {
+  // Fix all links that should have the baseurl
+  document.querySelectorAll('a[href^="/"]').forEach(function(link) {
+    if (!link.href.includes('/forms-engine-plugin') && 
+        !link.href.match(/^https?:\/\//) && 
+        !link.getAttribute('href').startsWith('/forms-engine-plugin')) {
+      const href = link.getAttribute('href');
+      link.href = '/forms-engine-plugin' + href;
+    }
+  });
+});
+EOF
+
+# Add it to the config
+echo "" >> site-src/_config.yml
+echo "# Custom scripts" >> site-src/_config.yml
+echo "head_scripts:" >> site-src/_config.yml
+echo "  - /assets/js/fix-links.js" >> site-src/_config.yml
+
+# Create custom includes directory to add baseurl meta tag
+mkdir -p site-src/_includes
+cat > site-src/_includes/head_custom.html << 'EOF'
+<meta name="baseurl" content="{{ site.baseurl }}">
+EOF
+
 echo "✅ Jekyll configuration files created successfully!"
diff --git a/.github/scripts/docs/fix-schema-links.sh b/.github/scripts/docs/fix-schema-links.sh
@@ -6,24 +6,27 @@ else
   SED_INPLACE=(-i "")
 fi
 
-# Use relative path from script directory
-BASE_DIR="../../../site-src"
-cd $(dirname "$0")
-echo "Working from $(pwd)"
+# Working directly in the site-src directory
+BASE_DIR="."
+echo "Working from $(pwd) - processing files in $BASE_DIR"
 
 echo "🔍 Starting comprehensive schema link fixing process..."
 
 # 1. Process all files recursively, with special handling for schema files
-find "$BASE_DIR" -type f -name "*.md" | while read file; do
+find "$BASE_DIR" -type f -name "*.md" | grep -v "node_modules" | while read file; do
   if [[ "$file" == *"/schemas/"* ]]; then
     echo -n "."
   else
     echo "Processing: $file"
   fi
 
-  # === Fix all .md links to match Jekyll's pretty permalinks ===
+  # === Fix all .md links to match Jekyll's pretty permalinks AND add baseurl ===
   sed "${SED_INPLACE[@]}" -E 's|\[([^]]+)\]\(([^)]+)\.md(#[^)]+)?\)|\[\1\]\(/forms-engine-plugin/\2\3\)|g' "$file"
   sed "${SED_INPLACE[@]}" -E 's|\[([^]]+)\]\(([^)]+)\.md\)|\[\1\]\(/forms-engine-plugin/\2\)|g' "$file"
+  # Fix plain / roots to include baseurl
+  sed "${SED_INPLACE[@]}" -E 's|\[([^]]+)\]\(\/([^)]+)\)|\[\1\]\(/forms-engine-plugin/\2\)|g' "$file"
+  # Fix relative links to be absolute with baseurl
+  sed "${SED_INPLACE[@]}" -E 's|\[([^]]+)\]\(\./([^)]+)\)|\[\1\]\(/forms-engine-plugin/\2\)|g' "$file"
 
   # === Specific handling for schema files ===
   if [[ "$file" == *"/schemas/"* ]]; then
diff --git a/.github/scripts/docs/process-docs.sh b/.github/scripts/docs/process-docs.sh
@@ -13,7 +13,7 @@ fi
 echo "🔄 Processing documentation files..."
 
 # Set the correct base path
-BASE_DIR="site-src"
+BASE_DIR="."
 
 # Define core schemas - these will be shown in navigation
 CORE_SCHEMAS=(
@@ -26,6 +26,80 @@ CORE_SCHEMAS=(
   "page-schema-v2"
 )
 
+# ====== NEW: Process root documentation files ======
+echo "🔧 Processing root documentation files..."
+# Convert INDEX.md to index.md for Jekyll compatibility
+if [ -f "INDEX.md" ] && [ ! -f "index.md" ]; then
+  echo "  Converting INDEX.md to index.md..."
+  cp "INDEX.md" "index.md"
+  
+  # Ensure index.md has proper front matter
+  if ! grep -q "^---" "index.md"; then
+    echo "  Adding front matter to index.md..."
+    temp_file="index.md.tmp"
+    echo "---" > "$temp_file"
+    echo "layout: default" >> "$temp_file"
+    echo "title: DXT Documentation" >> "$temp_file" 
+    echo "nav_order: 1" >> "$temp_file"
+    echo "permalink: /" >> "$temp_file"
+    echo "---" >> "$temp_file"
+    echo "" >> "$temp_file"
+    cat "index.md" >> "$temp_file"
+    mv "$temp_file" "index.md"
+  fi
+fi
+
+# Process all root markdown files
+for doc_file in $(find . -maxdepth 1 -name "*.md"); do
+  base_name=$(basename "$doc_file" .md)
+  
+  # Skip files that already have front matter
+  if grep -q "^---" "$doc_file"; then
+    echo "  Front matter exists in $doc_file"
+    continue
+  fi
+  
+  # Add front matter based on filename
+  case "$base_name" in
+    "index"|"INDEX")
+      nav_order=1
+      title="DXT Documentation"
+      ;;
+    "GETTING_STARTED")
+      nav_order=2
+      title="Getting Started"
+      ;;
+    "PLUGIN_OPTIONS")
+      nav_order=3
+      title="Plugin Options"
+      ;;
+    "CONTRIBUTING")
+      nav_order=4
+      title="Contributing"
+      ;;
+    "SCHEMA_REFERENCE")
+      nav_order=5
+      title="Schema Reference"
+      ;;
+    *)
+      nav_order=10
+      title=$(echo "$base_name" | sed 's/_/ /g')
+      ;;
+  esac
+  
+  echo "  Adding front matter to $doc_file..."
+  temp_file="${doc_file}.tmp"
+  echo "---" > "$temp_file"
+  echo "layout: default" >> "$temp_file"
+  echo "title: $title" >> "$temp_file"
+  echo "nav_order: $nav_order" >> "$temp_file"
+  echo "---" >> "$temp_file"
+  echo "" >> "$temp_file"
+  cat "$doc_file" >> "$temp_file"
+  mv "$temp_file" "$doc_file"
+done
+
+# ===== Continue with existing schema processing =====
 # Check if directories exist and display useful messages
 if [ ! -d "$BASE_DIR/schemas" ]; then
   echo "⚠️ Directory $BASE_DIR/schemas not found. Skipping schema processing."
diff --git a/.github/workflows/test-docs-generation.yml b/.github/workflows/test-docs-generation.yml
@@ -85,8 +85,10 @@ jobs:
       - name: Fix documentation links
         run: |
           echo "🔄 Fixing documentation links..."
-          chmod +x .github/scripts/docs/fix-schema-links.sh
-          .github/scripts/docs/fix-schema-links.sh
+          cd site-src
+          chmod +x ../.github/scripts/docs/fix-schema-links.sh
+          ../.github/scripts/docs/fix-schema-links.sh
+          cd ..
 
       - name: Create Jekyll configuration
         run: |
@@ -103,103 +105,36 @@ jobs:
           JEKYLL_ENV=production bundle exec jekyll build --destination ../_site
           cd ..
           
-          # Fix capitalization issues
-          echo "🔧 Fixing case sensitivity issues..."
-          if [ -f "_site/INDEX.html" ] && [ ! -f "_site/index.html" ]; then
-            echo "🔄 Renaming INDEX.html to index.html..."
-            cp "_site/INDEX.html" "_site/index.html"
-          fi
-          
-          # Fix unconverted markdown files - with proper paths
-          echo "🔧 Handling unconverted markdown files..."
-          for md_file in $(find _site -name "*.md"); do
-            html_file="${md_file%.md}.html"
-            dir_name=$(dirname "$md_file")
-            base_name=$(basename "$md_file" .md)
-            
-            echo "  Converting $md_file to HTML..."
-            
-            # Create a minimal HTML version of the markdown file that uses the baseurl
-            cat > "$html_file" << EOF
-          <html>
-          <head>
-            <title>$base_name</title>
-            <meta http-equiv="refresh" content="0; url='/forms-engine-plugin$dir_name/$base_name/'">
-          </head>
-          <body>
-            <h1>$base_name</h1>
-            <p>Redirecting to <a href="/forms-engine-plugin$dir_name/$base_name/">/forms-engine-plugin$dir_name/$base_name/</a></p>
-          </body>
-          </html>
-          EOF
-            
-            # Create directory and index.html for pretty URLs
-            mkdir -p "_site$dir_name/$base_name"
-            
-            # Create an index.html in the subdirectory with the actual content
-            cat > "_site$dir_name/$base_name/index.html" << EOF
-          <html>
-          <head>
-            <title>$base_name</title>
-            <link rel="stylesheet" href="/forms-engine-plugin/assets/css/just-the-docs-default.css">
-          </head>
-          <body>
-            <div class="main-content">
-              <h1>$base_name</h1>
-              <div class="content">
-                $(cat "$md_file" | sed 's|](/|](/forms-engine-plugin/|g')
-              </div>
-            </div>
-          </body>
-          </html>
-          EOF
-            
-            # Remove the original markdown file
-            rm "$md_file"
-          done
-          
-          # Ensure lowercase 'index' directory exists for assets
-          if [ -d "_site/INDEX" ]; then
-            echo "🔄 Creating lowercase version of INDEX directory..."
-            mkdir -p "_site/index"
-            cp -r "_site/INDEX/"* "_site/index/" 2>/dev/null || echo "No files to copy (empty directory)"
-          fi
-          
           # Verification steps
           echo "🔍 Verifying build results..."
           
           # Show root files explicitly
-          echo "📄 Files at site root after fixes:"
+          echo "📄 Files at site root:"
           ls -la _site/
           
           # Check for HTML files
-          echo "✓ HTML files generated from markdown and fixes:"
+          echo "✓ HTML files generated from markdown:"
           find _site -name "*.html" | grep -v "assets" | head -n 15
           html_count=$(find _site -name "*.html" | wc -l)
           echo "  Total HTML files: $html_count"
           
-          # List remaining markdown files (if any)
+          # Check if any markdown files remain in output (there shouldn't be any)
           md_files=$(find _site -name "*.md" | wc -l)
           if [ "$md_files" -gt 0 ]; then
-            echo "⚠️ WARNING: Still found $md_files markdown files in output:"
+            echo "⚠️ WARNING: Found $md_files markdown files in output (should be 0):"
             find _site -name "*.md" | head -n 10
           else
             echo "✅ No markdown files found in output (good!)"
           fi
           
-          # Check for previously failed files
-          for check_file in "features/configuration-based/PAGE_TEMPLATES" "features/configuration-based/PAGE_EVENTS" "features/code-based/PAGE_VIEWS"; do
-            if [ -f "_site/$check_file.html" ] || [ -d "_site/$check_file" ]; then
-              echo "✅ Successfully handled: $check_file"
+          # Check for specific problematic files to make sure they were converted
+          for check_file in "features/configuration-based/PAGE_TEMPLATES.html" "features/configuration-based/PAGE_EVENTS.html" "features/code-based/PAGE_VIEWS.html"; do
+            if [ -f "_site/$check_file" ]; then
+              echo "✅ Successfully converted: $check_file"
             else
-              echo "❌ FAILED to handle: $check_file"
+              echo "❌ FAILED to convert: $check_file"
             fi
           done
-          
-          # Final output structure
-          echo "📊 Final site structure:"
-          find _site -type f | grep -e "index.html" -e "features" | sort | head -n 15
-          echo "... (and more files)"
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
@@ -214,14 +149,3 @@ jobs:
         uses: actions/deploy-pages@v4
         with:
           timeout: 600000 # 10 minutes in milliseconds
-
-        run: |
-          echo "🔧 Verifying Jekyll baseurl configuration..."
-          if ! grep -q "baseurl: \"/forms-engine-plugin\"" site-src/_config.yml; then
-            sed -i.bak 's|baseurl: ""|baseurl: "/forms-engine-plugin"|g' site-src/_config.yml
-            sed -i.bak 's|baseurl: "/"|baseurl: "/forms-engine-plugin"|g' site-src/_config.yml
-            rm -f site-src/_config.yml.bak
-            echo "✅ Updated baseurl in _config.yml"
-          else
-            echo "✅ baseurl already correctly configured"
-          fi
