Skip to main content

FlorisBoard Documentation - Deployment Guide

🚀 Quick Start​

Your FlorisBoard documentation is ready to deploy! Follow these steps to publish it to GitHub Pages.

Prerequisites​

✅ All prerequisites are already met:

  • Documentation structure created
  • Docusaurus configured
  • GitHub Actions workflow set up
  • Build tested successfully

Step 1: Commit and Push Changes​

# Navigate to your repository
cd /Users/bramburn/dev/florisboard

# Check status
git status

# Add all documentation files
git add docs/ .github/workflows/docs.yml DOCUMENTATION_SUMMARY.md DOCUMENTATION_DEPLOYMENT_GUIDE.md

# Commit changes
git commit -m "Add comprehensive FlorisBoard documentation with Docusaurus

- Created 27 documentation pages covering architecture, technical details, and integration
- Set up Docusaurus with GitHub Pages deployment
- Added GitHub Actions workflow for automatic deployment
- Completed 6 comprehensive pages with detailed content
- Created 21 placeholder pages with structured content
- Configured sidebars and navigation
- Tested build successfully"

# Push to GitHub
git push origin main

Step 2: Enable GitHub Pages​

Option A: Via GitHub Web Interface​

  1. Go to your repository: https://github.com/bramburn/florisboard

  2. Click on Settings tab

  3. Scroll down to Pages section in the left sidebar

  4. Under Build and deployment:

    • Source: Select "GitHub Actions"
    • This will use the workflow we created in .github/workflows/docs.yml

  5. Click Save

  6. Wait for the deployment (usually 2-5 minutes)

  7. Your documentation will be available at:

    https://bramburn.github.io/florisboard/

Option B: Via GitHub CLI (if installed)​

# Enable GitHub Pages with GitHub Actions source
gh repo edit --enable-pages --pages-branch gh-pages

# Check workflow status
gh workflow view "Deploy Documentation"

# Watch the workflow run
gh run watch

Step 3: Verify Deployment​

Check Workflow Status​

  1. Go to Actions tab in your repository
  2. Look for "Deploy Documentation" workflow
  3. Click on the latest run
  4. Verify all steps completed successfully:
    • ✅ Checkout
    • ✅ Setup Node.js
    • ✅ Install dependencies
    • ✅ Build documentation
    • ✅ Upload artifact
    • ✅ Deploy to GitHub Pages

Access Your Documentation​

Once deployed, visit:

https://bramburn.github.io/florisboard/

You should see:

  • Welcome page with FlorisBoard introduction
  • Navigation sidebar with all sections
  • Architecture, Technical, Integration sections
  • Search functionality (built-in)
  • Dark/light mode toggle

Step 4: Test the Documentation​

Local Testing (Before Deployment)​

# Navigate to docs directory
cd docs

# Install dependencies (if not already done)
npm install

# Start development server
npm run start

# This will open http://localhost:3000/florisboard/

Production Build Testing​

# Build for production
npm run build

# Serve the build locally
npm run serve

# This will open http://localhost:3000/florisboard/

Troubleshooting​

Issue: Workflow Fails​

Solution: Check the Actions tab for error messages

Common issues:

  • Node.js version mismatch (we use Node 20)
  • Missing dependencies (run npm install locally first)
  • Broken links (Docusaurus will fail on broken internal links)

Issue: 404 Page Not Found​

Solution: Verify GitHub Pages settings

  1. Check that Pages is enabled
  2. Verify source is set to "GitHub Actions"
  3. Wait a few minutes for DNS propagation
  4. Clear browser cache

Issue: Styles Not Loading​

Solution: Check base URL configuration

Verify in docs/docusaurus.config.js:

url: 'https://bramburn.github.io',
baseUrl: '/florisboard/',

Issue: Build Fails Locally​

Solution: Clear cache and rebuild

cd docs
npm run clear
rm -rf node_modules package-lock.json
npm install
npm run build

Updating Documentation​

Making Changes​

  1. Edit markdown files in docs/docs/
  2. Test locally: npm run start
  3. Commit and push changes
  4. GitHub Actions will automatically rebuild and deploy

Adding New Pages​

  1. Create new markdown file:

    touch docs/docs/section/new-page.md

  2. Add content with frontmatter:

    ---
    sidebar_position: 5
    ---

    # New Page Title

    Content here...

  3. Update docs/sidebars.js if needed

  4. Test build: npm run build

  5. Commit and push

Completing Placeholder Pages​

Priority Order​

Complete pages in this order for maximum impact:

  1. State Management - Critical for understanding reactive architecture
  2. Layout System - Core to keyboard functionality
  3. Touch & Gestures - Essential for input handling
  4. IME APIs - Foundation for Android integration
  5. Prediction Engine - Key feature documentation
  6. Build From Scratch - High-value tutorial

Content Development Process​

For each placeholder page:

  1. Research:

    # Use codebase retrieval to find relevant code
    # Example: Search for "state management" in the codebase

  2. Outline:

    • Introduction
    • Key concepts
    • Implementation details
    • Code examples
    • Best practices
    • Related topics

  3. Write:

    • Use existing completed pages as templates
    • Include real code from FlorisBoard
    • Add diagrams for complex concepts
    • Cross-reference related pages

  4. Review:

    • Test code examples
    • Verify technical accuracy
    • Check links
    • Build locally

  5. Deploy:

    • Commit changes
    • Push to GitHub
    • Verify deployment

Advanced Configuration​

Adding Search (Algolia)​

  1. Apply for Algolia DocSearch: https://docsearch.algolia.com/apply/

  2. Once approved, update docs/docusaurus.config.js:

    themeConfig: {
      algolia: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_API_KEY',
        indexName: 'florisboard',
      },
    }

Adding Analytics​

Update docs/docusaurus.config.js:

themeConfig: {
  gtag: {
    trackingID: 'G-XXXXXXXXXX',
  },
}

Custom Domain​

  1. Add CNAME file to docs/static/:

    echo "docs.florisboard.dev" > docs/static/CNAME

  2. Configure DNS:

    • Add CNAME record pointing to bramburn.github.io

  3. Update docs/docusaurus.config.js:

    url: 'https://docs.florisboard.dev',
    baseUrl: '/',

Maintenance​

Regular Updates​

  • Update dependencies: npm update
  • Check for Docusaurus updates: npm outdated
  • Review and update content quarterly
  • Fix broken links and outdated information

Monitoring​

  • Check GitHub Actions for failed builds
  • Monitor GitHub Pages status
  • Review user feedback and issues
  • Track documentation usage (with analytics)

Resources​

Documentation​

Support​

Next Steps​

  1. ✅ Deploy: Follow Step 1-3 above to deploy your documentation
  2. 📝 Complete: Fill in placeholder pages with detailed content
  3. 🎨 Enhance: Add screenshots, diagrams, and visual assets
  4. 🔍 Optimize: Set up search and analytics
  5. 📢 Promote: Share your documentation with the community

Success Checklist​

  • Changes committed and pushed to GitHub
  • GitHub Pages enabled in repository settings
  • GitHub Actions workflow completed successfully
  • Documentation accessible at https://bramburn.github.io/florisboard/
  • All navigation links working
  • Search functionality working
  • Dark/light mode toggle working
  • Mobile responsive design verified
  • No broken links or 404 errors

Congratulations! 🎉​

Your FlorisBoard documentation is now ready to serve as:

  • A comprehensive learning resource for IME development
  • Technical reference for contributors
  • Reverse engineering guide for developers
  • Case study of modern Android architecture

The foundation is solid, and you can now focus on completing the remaining content pages to make this the definitive guide to building Android keyboards!

Need Help? Open an issue on GitHub or reach out on Matrix chat.