postsvg 0.1.0 → 0.3.0

data/docs/DEPLOYMENT.md

@@ -0,0 +1,456 @@
+# Deploying Postsvg Documentation
+
+This guide explains how to deploy the Postsvg documentation site to various platforms.
+
+## Quick Deploy to GitHub Pages
+
+The easiest deployment method is GitHub Pages (already configured).
+
+### Prerequisites
+
+- Repository pushed to GitHub
+- Documentation in `docs/` directory
+- `_config.yml` properly configured
+
+### Steps
+
+1. **Enable GitHub Pages:**
+   ```
+   Repository Settings → Pages
+   Source: Deploy from a branch
+   Branch: main
+   Folder: /docs
+   ```
+
+2. **Wait for deployment:**
+   - GitHub Actions will automatically build the site
+   - Check the Actions tab for build status
+   - Site will be available at: `https://metanorma.github.io/postsvg`
+
+3. **Verify deployment:**
+   ```sh
+   # Check the site is live
+   curl -I https://metanorma.github.io/postsvg
+   ```
+
+### Troubleshooting GitHub Pages
+
+**Problem:** Site not building
+
+**Solution:**
+```sh
+# Check _config.yml syntax
+bundle exec jekyll build
+
+# View build logs in GitHub Actions tab
+```
+
+**Problem:** 404 errors on pages
+
+**Solution:**
+- Ensure baseurl in `_config.yml` matches repository name
+- Check file extensions are `.adoc` not `.md`
+- Verify `jekyll-asciidoc` plugin is in `_config.yml`
+
+## Local Testing
+
+Always test locally before deploying:
+
+```sh
+cd docs
+
+# Install dependencies
+bundle install
+
+# Serve locally
+bundle exec jekyll serve
+
+# View at http://localhost:4000/postsvg
+
+# Build static site
+bundle exec jekyll build
+
+# Output in _site/
+```
+
+### Local Testing Checklist
+
+- [ ] All pages load without errors
+- [ ] Navigation works correctly
+- [ ] Search functions properly
+- [ ] Links are not broken
+- [ ] Code examples display correctly
+- [ ] Images/diagrams load
+- [ ] Mobile layout works
+
+## Deploy to Netlify
+
+For continuous deployment with Netlify:
+
+### Setup
+
+1. **Create `netlify.toml` in repository root:**
+
+```toml
+[build]
+  base = "docs"
+  publish = "_site"
+  command = "bundle exec jekyll build"
+
+[build.environment]
+  RUBY_VERSION = "3.2"
+
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200
+```
+
+2. **Connect repository:**
+   - Go to Netlify dashboard
+   - "New site from Git"
+   - Select GitHub repository
+   - Configure build settings (auto-detected from netlify.toml)
+
+3. **Deploy:**
+   - Push to main branch
+   - Netlify automatically builds and deploys
+   - Site available at: `https://your-site.netlify.app`
+
+### Custom Domain on Netlify
+
+1. **Add domain:**
+   ```
+   Site Settings → Domain Management → Add custom domain
+   ```
+
+2. **Configure DNS:**
+   ```
+   Add CNAME record:
+   docs.postsvg.org → your-site.netlify.app
+   ```
+
+3. **Enable HTTPS:**
+   - Automatically enabled by Netlify
+   - Free Let's Encrypt certificate
+
+## Deploy to Vercel
+
+For deployment with Vercel:
+
+### Setup
+
+1. **Install Vercel CLI:**
+   ```sh
+   npm install -g vercel
+   ```
+
+2. **Create `vercel.json` in docs directory:**
+
+```json
+{
+  "buildCommand": "bundle exec jekyll build",
+  "outputDirectory": "_site",
+  "framework": "jekyll"
+}
+```
+
+3. **Deploy:**
+   ```sh
+   cd docs
+   vercel
+   ```
+
+4. **Production deployment:**
+   ```sh
+   vercel --prod
+   ```
+
+## Deploy to Custom Server
+
+For deployment to your own server:
+
+### Build Static Site
+
+```sh
+cd docs
+bundle install
+bundle exec jekyll build
+
+# Output is in _site/
+```
+
+### Upload to Server
+
+```sh
+# Using rsync
+rsync -avz _site/ user@server:/var/www/docs/
+
+# Using scp
+scp -r _site/* user@server:/var/www/docs/
+```
+
+### Nginx Configuration
+
+```nginx
+server {
+    listen 80;
+    server_name docs.postsvg.org;
+
+    root /var/www/docs;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ =404;
+    }
+
+    # Enable gzip
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+}
+```
+
+### Apache Configuration
+
+```apache
+<VirtualHost *:80>
+    ServerName docs.postsvg.org
+    DocumentRoot /var/www/docs
+
+    <Directory /var/www/docs>
+        Options Indexes FollowSymLinks
+        AllowOverride All
+        Require all granted
+    </Directory>
+
+    # Enable compression
+    <IfModule mod_deflate.c>
+        AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript
+    </IfModule>
+</VirtualHost>
+```
+
+## Automated Deployment with GitHub Actions
+
+Create `.github/workflows/deploy-docs.yml`:
+
+```yaml
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+          working-directory: docs
+
+      - name: Build site
+        run: |
+          cd docs
+          bundle exec jekyll build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_site
+```
+
+## Custom Domain Setup
+
+### GitHub Pages Custom Domain
+
+1. **Add CNAME file:**
+   ```sh
+   echo "docs.postsvg.org" > docs/CNAME
+   ```
+
+2. **Configure DNS:**
+   ```
+   CNAME record:
+   docs.postsvg.org → metanorma.github.io
+
+   Or A records:
+   docs.postsvg.org → 185.199.108.153
+   docs.postsvg.org → 185.199.109.153
+   docs.postsvg.org → 185.199.110.153
+   docs.postsvg.org → 185.199.111.153
+   ```
+
+3. **Enable HTTPS:**
+   ```
+   Repository Settings → Pages → Enforce HTTPS
+   ```
+
+## Monitoring Deployment
+
+### Check Build Status
+
+**GitHub Pages:**
+```sh
+# Check Actions tab in repository
+# Or use GitHub API:
+curl https://api.github.com/repos/metanorma/postsvg/pages/builds/latest
+```
+
+**Netlify:**
+```sh
+# Check Netlify dashboard
+# Or use Netlify CLI:
+netlify status
+```
+
+### Monitor Site Health
+
+```sh
+# Check site is accessible
+curl -I https://docs.postsvg.org
+
+# Check specific pages
+curl -s https://docs.postsvg.org/getting-started/ | grep "<title>"
+
+# Check for broken links (using linkchecker)
+linkchecker https://docs.postsvg.org
+```
+
+## Rollback Deployment
+
+### GitHub Pages
+
+```sh
+# Revert last commit
+git revert HEAD
+git push origin main
+
+# Or deploy specific commit
+git checkout <commit-hash> docs/
+git commit -m "Rollback docs to <commit-hash>"
+git push origin main
+```
+
+### Netlify
+
+```
+Deploys → Select previous deployment → Publish deploy
+```
+
+## Performance Optimization
+
+### Enable Caching
+
+Add to `_config.yml`:
+
+```yaml
+# Minify HTML
+compress_html:
+  clippings: all
+  comments: all
+  endings: all
+  ignore:
+    envs: [development]
+```
+
+### Optimize Images
+
+```sh
+# Install image optimizer
+gem install image_optim image_optim_pack
+
+# Optimize images
+image_optim -r docs/images/
+```
+
+### Enable CDN
+
+**Using Cloudflare:**
+1. Add site to Cloudflare
+2. Point DNS to Cloudflare nameservers
+3. Enable caching and minification
+4. Configure SSL/TLS to Full
+
+## Post-Deployment Checklist
+
+- [ ] Site loads at production URL
+- [ ] All pages are accessible
+- [ ] Navigation works correctly
+- [ ] Search is functional
+- [ ] HTTPS is enabled
+- [ ] Custom domain resolves correctly
+- [ ] Mobile layout renders properly
+- [ ] No broken links
+- [ ] Analytics tracking (if configured)
+- [ ] Sitemap generated
+- [ ] robots.txt is correct
+
+## Troubleshooting
+
+### Build Failures
+
+**Missing dependencies:**
+```sh
+cd docs
+bundle install
+bundle exec jekyll build
+```
+
+**Plugin errors:**
+```sh
+# Check plugin versions in Gemfile
+# Update plugins:
+bundle update
+```
+
+### Deployment Issues
+
+**Site not updating:**
+```sh
+# Clear GitHub Pages cache
+# Push new commit:
+git commit --allow-empty -m "Trigger rebuild"
+git push origin main
+```
+
+**404 errors:**
+```sh
+# Check baseurl in _config.yml
+# Verify file paths are correct
+# Ensure jekyll-asciidoc is installed
+```
+
+## Support
+
+For deployment issues:
+- Check [GitHub Pages documentation](https://docs.github.com/en/pages)
+- Review [Jekyll documentation](https://jekyllrb.com/docs/)
+- See [just-the-docs theme docs](https://just-the-docs.com/)
+- Create issue at https://github.com/metanorma/postsvg/issues
+
+## Quick Reference
+
+```sh
+# Local development
+cd docs && bundle exec jekyll serve
+
+# Build static site
+cd docs && bundle exec jekyll build
+
+# Deploy to GitHub Pages
+git push origin main
+
+# Check build status
+# Visit: https://github.com/metanorma/postsvg/actions
+
+# Access deployed site
+# Visit: https://metanorma.github.io/postsvg

data/docs/DEPLOYMENT_INSTRUCTIONS.md

@@ -0,0 +1,229 @@
+# GitHub Pages Deployment Instructions
+
+This guide provides step-by-step instructions for deploying the PostSVG documentation to GitHub Pages.
+
+## Prerequisites
+
+- Repository must be public or have GitHub Pages enabled for private repositories
+- Documentation is committed and pushed to the `main` branch
+- All link validation checks have passed
+
+## Enabling GitHub Pages
+
+### Step 1: Navigate to Repository Settings
+
+1. Go to the PostSVG repository: https://github.com/metanorma/postsvg
+2. Click on the **Settings** tab (located in the top navigation bar)
+3. In the left sidebar, scroll down to the **Code and automation** section
+4. Click on **Pages**
+
+### Step 2: Configure GitHub Pages Source
+
+1. Under **Build and deployment**, find the **Source** section
+2. Click the dropdown menu under **Source** and select **Deploy from a branch**
+3. Under **Branch**, select:
+   - Branch: `main`
+   - Folder: `/docs`
+4. Click **Save**
+
+### Step 3: Wait for Deployment
+
+GitHub Pages will automatically build and deploy your site. This typically takes 1-3 minutes.
+
+## Expected Deployment URL
+
+Once deployed, your documentation will be available at:
+
+```
+https://metanorma.github.io/postsvg/
+```
+
+The main documentation page will be:
+
+```
+https://metanorma.github.io/postsvg/index.html
+```
+
+## Verifying Deployment
+
+### Method 1: Check GitHub Actions
+
+1. Go to the **Actions** tab in your repository
+2. Look for a workflow named **pages build and deployment**
+3. Wait for the workflow to complete (green checkmark ✓)
+4. The workflow details will show the deployment URL
+
+### Method 2: Check Settings Page
+
+1. Return to **Settings** > **Pages**
+2. At the top of the page, you'll see a banner that says:
+   ```
+   Your site is live at https://metanorma.github.io/postsvg/
+   ```
+3. Click **Visit site** to view your documentation
+
+### Method 3: Manual Verification
+
+1. Open a browser and navigate to: https://metanorma.github.io/postsvg/
+2. Verify that the documentation loads correctly
+3. Check navigation between pages works
+4. Verify all internal links are functional
+
+## Monitoring GitHub Actions Workflows
+
+### Link Check Workflow
+
+The repository includes a `link-check.yml` workflow that runs on:
+- Every push to `main`
+- Every pull request
+- Weekly schedule (Mondays at 00:00 UTC)
+
+To monitor this workflow:
+
+1. Go to **Actions** tab
+2. Click on **Check Documentation Links** workflow
+3. View recent runs and their status
+
+### Troubleshooting Link Check Failures
+
+If the link check workflow fails:
+
+1. Click on the failed workflow run
+2. Click on the **check-links** job
+3. Review the output to identify broken links
+4. Fix the broken links in the documentation
+5. Commit and push the changes
+6. The workflow will run automatically
+
+## Common Issues and Solutions
+
+### Issue 1: Site Not Updating
+
+**Symptom**: Changes to documentation don't appear on the live site
+
+**Solutions**:
+- Clear your browser cache (Ctrl+Shift+R or Cmd+Shift+R)
+- Wait 5-10 minutes for GitHub's CDN to update
+- Check that changes were actually pushed to the `main` branch
+- Verify the workflow completed successfully in Actions tab
+
+### Issue 2: 404 Page Not Found
+
+**Symptom**: GitHub Pages shows 404 error
+
+**Solutions**:
+- Ensure the `/docs` folder exists in the `main` branch
+- Verify `index.html` exists in the `/docs` folder
+- Check that GitHub Pages is configured to use `/docs` folder
+- Ensure the repository is public (or Pages is enabled for private repos)
+
+### Issue 3: Broken Links
+
+**Symptom**: Internal links don't work or show 404 errors
+
+**Solutions**:
+- Run `rake check:links` locally to identify broken links
+- Ensure all file references use relative paths
+- Verify file extensions match exactly (case-sensitive)
+- Check that cross-references use correct paths
+
+### Issue 4: Workflow Failures
+
+**Symptom**: GitHub Actions workflows fail
+
+**Solutions**:
+- Check the workflow logs in the Actions tab
+- Ensure all required files are committed
+- Verify that Ruby and dependencies are properly installed
+- For link-check failures, review the specific broken links reported
+
+### Issue 5: Custom Domain Not Working
+
+**Symptom**: Custom domain doesn't resolve to GitHub Pages
+
+**Solutions**:
+- Verify DNS records are correctly configured
+- Allow 24-48 hours for DNS propagation
+- Check that the CNAME file exists in `/docs`
+- Ensure HTTPS is enabled in GitHub Pages settings
+
+## Maintenance
+
+### Regular Tasks
+
+1. **Weekly Link Checks**: Monitor the automated weekly link check workflow
+2. **Update Documentation**: Keep documentation in sync with code changes
+3. **Review Pull Requests**: Ensure documentation changes pass link validation
+4. **Monitor Issues**: Address documentation-related issues promptly
+
+### Best Practices
+
+1. Always run `rake check:links` before pushing documentation changes
+2. Use relative paths for all internal documentation links
+3. Test documentation locally before deploying
+4. Keep the documentation structure organized and MECE
+5. Update the documentation when adding new features or commands
+
+## Rollback Procedure
+
+If you need to rollback to a previous version:
+
+1. Identify the commit hash of the working version
+2. Create a new branch from that commit:
+   ```bash
+   git checkout -b rollback-docs <commit-hash>
+   ```
+3. Force push to main (use with caution):
+   ```bash
+   git push origin rollback-docs:main --force
+   ```
+4. Wait for GitHub Pages to redeploy
+
+## Support
+
+For issues specific to GitHub Pages deployment:
+- GitHub Pages Documentation: https://docs.github.com/en/pages
+- GitHub Actions Documentation: https://docs.github.com/en/actions
+
+For PostSVG documentation issues:
+- Open an issue at: https://github.com/metanorma/postsvg/issues
+- Include the page URL and description of the problem
+- Attach screenshots if relevant
+
+## Quick Reference Commands
+
+```bash
+# Check links locally
+rake check:links
+
+# Push documentation to GitHub
+git push origin main
+
+# View git log
+git log --oneline
+
+# Check current branch
+git branch
+
+# View workflow status (requires GitHub CLI)
+gh workflow list
+gh run list --workflow=link-check.yml
+```
+
+## Deployment Checklist
+
+Before deploying documentation updates:
+
+- [ ] All new files created and committed
+- [ ] Link validation passes (`rake check:links`)
+- [ ] Changes pushed to `main` branch
+- [ ] GitHub Actions workflows triggered
+- [ ] Link check workflow passes
+- [ ] Documentation accessible at GitHub Pages URL
+- [ ] All navigation links work correctly
+- [ ] Cross-references resolve properly
+- [ ] No 404 errors on any pages
+
+---
+
+Last Updated: 2025-10-25