fix: extract API sidebar titles from H1 headings in docs workflow #10
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Documentation | |
| on: | |
| push: | |
| branches: | |
| - rel/prod | |
| release: | |
| types: [published] | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Setup .NET | |
| uses: actions/setup-dotnet@v4 | |
| with: | |
| dotnet-version: | | |
| 8.0.x | |
| 9.0.x | |
| 10.0.x | |
| - name: Setup Node.js | |
| uses: actions/setup-node@v4 | |
| with: | |
| node-version: '20' | |
| cache: 'npm' | |
| cache-dependency-path: docs/package-lock.json | |
| - name: Restore dotnet tools | |
| run: dotnet tool restore | |
| - name: Build .NET project | |
| run: dotnet build -c Release | |
| - name: Find XML documentation | |
| id: find-xml | |
| run: | | |
| XML_FILE=$(find src -name "Bogoware.Monads.xml" -path "*/bin/Release/*" | head -1) | |
| DLL_FILE=$(find src -name "Bogoware.Monads.dll" -path "*/bin/Release/*" | grep -v "/ref/" | head -1) | |
| echo "xml_file=$XML_FILE" >> "$GITHUB_OUTPUT" | |
| echo "dll_file=$DLL_FILE" >> "$GITHUB_OUTPUT" | |
| - name: Generate API documentation | |
| env: | |
| DLL_FILE: ${{ steps.find-xml.outputs.dll_file }} | |
| run: | | |
| mkdir -p docs/docs/api | |
| dotnet xmldoc2md "$DLL_FILE" -o docs/docs/api --index-page-name index --github-pages | |
| # Add frontmatter to generated files | |
| for file in docs/docs/api/*.md; do | |
| if [ -f "$file" ]; then | |
| filename=$(basename "$file" .md) | |
| if [ "$filename" = "index" ]; then | |
| title="API Reference" | |
| position=1 | |
| else | |
| position=99 | |
| # Extract title from H1 heading in the generated markdown | |
| h1_line=$(grep -m1 "^# " "$file" || true) | |
| if [ -n "$h1_line" ]; then | |
| title="${h1_line#\# }" | |
| title="${title//</<}" | |
| title="${title//>/>}" | |
| else | |
| title="${filename#bogoware.monads.}" | |
| fi | |
| fi | |
| temp_file=$(mktemp) | |
| echo "---" > "$temp_file" | |
| echo "title: \"$title\"" >> "$temp_file" | |
| echo "sidebar_position: $position" >> "$temp_file" | |
| echo "---" >> "$temp_file" | |
| echo "" >> "$temp_file" | |
| cat "$file" >> "$temp_file" | |
| mv "$temp_file" "$file" | |
| fi | |
| done | |
| - name: Sync changelog | |
| run: node scripts/sync-readme.js | |
| - name: Install npm dependencies | |
| run: npm ci | |
| working-directory: docs | |
| - name: Build Docusaurus | |
| run: npm run build | |
| working-directory: docs | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: docs/build | |
| deploy: | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| needs: build | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |