docs: improve documentation and fix progress bar seek issue #4
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: Docs | |
| on: | |
| push: | |
| branches: | |
| - main | |
| paths: | |
| - "docs/**" | |
| - ".github/workflows/docs.yml" | |
| - "package.json" | |
| - "yarn.lock" | |
| pull_request: | |
| paths: | |
| - "docs/**" | |
| - ".github/workflows/docs.yml" | |
| - "package.json" | |
| - "yarn.lock" | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "docs" | |
| cancel-in-progress: true | |
| env: | |
| NODE_VERSION: 20 | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 15 | |
| steps: | |
| - name: Checkout Repo | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - name: Setup Node.js | |
| uses: actions/setup-node@v4 | |
| with: | |
| node-version: ${{ env.NODE_VERSION }} | |
| cache: "yarn" | |
| # Verify package.json exists and is valid | |
| - name: Validate package.json | |
| run: | | |
| if [ ! -f package.json ]; then | |
| echo "Error: package.json not found in root" | |
| exit 1 | |
| fi | |
| node -e "JSON.parse(require('fs').readFileSync('package.json', 'utf8'))" | |
| - name: Install Root Dependencies | |
| run: yarn install --immutable --frozen-lockfile | |
| # Check if docs directory and package.json exist | |
| - name: Validate docs structure | |
| run: | | |
| if [ ! -d "./docs" ]; then | |
| echo "Error: docs directory not found" | |
| exit 1 | |
| fi | |
| if [ ! -f "./docs/package.json" ]; then | |
| echo "Error: docs/package.json not found" | |
| exit 1 | |
| fi | |
| - name: Install Docs Dependencies | |
| working-directory: ./docs | |
| run: yarn install --immutable --frozen-lockfile | |
| # Add cache for node_modules to speed up builds | |
| - name: Cache docs node_modules | |
| uses: actions/cache@v4 | |
| with: | |
| path: docs/node_modules | |
| key: ${{ runner.os }}-docs-${{ hashFiles('docs/yarn.lock') }} | |
| restore-keys: | | |
| ${{ runner.os }}-docs- | |
| # Lint/validate docs before building (optional but recommended) | |
| - name: Validate Docusaurus config | |
| working-directory: ./docs | |
| run: | | |
| if [ -f "docusaurus.config.js" ]; then | |
| node -e "require('./docusaurus.config.js')" | |
| elif [ -f "docusaurus.config.ts" ]; then | |
| echo "TypeScript config detected - ensure it compiles" | |
| fi | |
| - name: Build Docusaurus | |
| working-directory: ./docs | |
| run: yarn build | |
| env: | |
| NODE_ENV: production | |
| # Add any environment variables your docs might need | |
| # DOCUSAURUS_BASE_URL: ${{ github.event.repository.name }} | |
| # Verify build output exists | |
| - name: Verify build output | |
| run: | | |
| if [ ! -d "./docs/build" ]; then | |
| echo "Error: Build directory not found" | |
| exit 1 | |
| fi | |
| if [ ! -f "./docs/build/index.html" ]; then | |
| echo "Error: index.html not found in build output" | |
| exit 1 | |
| fi | |
| echo "Build output size:" | |
| du -sh ./docs/build | |
| - name: Upload Build Artifact | |
| if: github.event_name == 'push' | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: ./docs/build | |
| retention-days: 1 | |
| deploy: | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/main' | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| needs: build | |
| timeout-minutes: 10 | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 | |
| with: | |
| timeout: 600000 # 10 minutes | |
| # Optional: Add a job to test the deployed site | |
| test-deployment: | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/main' | |
| runs-on: ubuntu-latest | |
| needs: deploy | |
| timeout-minutes: 5 | |
| steps: | |
| - name: Test deployed site | |
| run: | | |
| # Wait for deployment to be available | |
| sleep 30 | |
| # Get the deployment URL and test it | |
| SITE_URL="${{ needs.deploy.outputs.url || format('https://{0}.github.io/{1}/', github.repository_owner, github.event.repository.name) }}" | |
| echo "Testing site at: $SITE_URL" | |
| # Basic HTTP check | |
| if curl -f -s "$SITE_URL" > /dev/null; then | |
| echo "✅ Site is accessible" | |
| else | |
| echo "❌ Site is not accessible" | |
| exit 1 | |
| fi |