Skip to content

Documentation Migration Guide

Summary of Changes

This document tracks the migration from inline README documentation to structured MkDocs documentation.

What Was Done

  1. Created MkDocs Structure (documentation/ directory)
  2. Getting Started (3 pages)
  3. User Guide (4 pages)
  4. Development (4 pages)
  5. Advanced (3 pages)

  6. Contributing (1 page)

  7. Migrated Existing Documentation

  8. Copied from docs/ (gitignored, local-only)
  9. Adapted for MkDocs Material theme

  10. Added cross-references and navigation

  11. Setup CI/CD

  12. GitHub Actions workflow (.github/workflows/docs.yml)
  13. Automatic deployment to GitHub Pages on main push

  14. Build validation on pull requests

  15. Added Makefile Commands

  16. make docs-install - Install MkDocs dependencies
  17. make docs-build - Build documentation site
  18. make docs-serve - Preview locally at http://127.0.0.1:8000

  19. make docs-deploy - Manual deployment (CI handles this)

  20. Updated .gitignore

  21. Added site/ (MkDocs build artifacts)
  22. Added .cache/ (MkDocs cache)
  23. Kept docs/ (local-only development documentation)

What Needs To Be Done

1. Simplify Main README.md

The main README should become a concise landing page that directs users to the comprehensive documentation:

Recommended structure:

# 🎤 Voice Transcriber

[Badges here]

Lightweight desktop voice-to-text transcription with OpenAI Whisper and system tray integration.

## ✨ Features

- 🎯 System Tray Integration
- 🌍 Multilingual Support (5 languages)
- 🏠 Self-Hosted Option (Speaches)
- 📋 Automatic Clipboard Copy

## 🚀 Quick Start

```bash
git clone https://github.com/Nouuu/voice-transcriber.git
cd voice-transcriber
make setup
nano ~/.config/voice-transcriber/config.json  # Add API key
make run

📚 Documentation

Comprehensive documentation available at: https://nouuu.github.io/voice-transcriber

🤝 Contributing

See Contributing Guide for guidelines.

📄 License

MIT License - see LICENSE file. 

**What to remove from README**:

- ❌ Detailed installation steps (move to docs)
- ❌ Complete configuration reference (move to docs)
- ❌ Extensive usage examples (move to docs)
- ❌ Full troubleshooting guide (move to docs)
- ❌ Detailed development workflow (move to docs)
- ❌ Complete roadmap (move to docs)

**What to keep in README**:

- ✅ Project overview and features
- ✅ Quick start command sequence
- ✅ Links to comprehensive documentation
- ✅ Badges and basic metadata
- ✅ License information

#### 2. Enable GitHub Pages

In your repository settings:

1. Go to **Settings** > **Pages**
2. Source: **Deploy from a branch**
3. Branch: **gh-pages** (will be created by CI)
4. Wait for first deployment from CI

#### 3. Test Documentation Locally

```bash
# Install dependencies
make docs-install

# Preview locally
make docs-serve

Open http://127.0.0.1:8000 and verify:

  • Navigation works correctly
  • All pages load without errors
  • Code examples are properly formatted
  • Internal links resolve correctly
  • Search functionality works

4. Deploy to GitHub Pages

Option 1: Automatic (Recommended)

Push to main branch:

git add .
git commit -m "docs: setup MkDocs documentation with CI/CD"
git push origin main

GitHub Actions will automatically deploy to GitHub Pages.

Option 2: Manual

make docs-deploy

After documentation is live, update:

  • README.md: Add documentation URL
  • package.json: Update homepage field
  • GitHub repository description: Add documentation link

Files Created/Modified

Created Files

documentation/
├── index.md
├── README.md
├── getting-started/
│   ├── installation.md
│   ├── configuration.md
│   └── first-run.md
├── user-guide/
│   ├── basic-usage.md
│   ├── language-support.md
│   ├── transcription-backends.md
│   └── troubleshooting.md
├── development/
│   ├── architecture.md
│   ├── development-guide.md
│   ├── testing.md
│   └── api-reference.md
├── advanced/
│   ├── speaches-integration.md
│   ├── whisper-models.md
│   └── local-inference.md
└── contributing.md

mkdocs.yml
.github/workflows/docs.yml

Modified Files

Makefile (added docs-* commands)
.gitignore (added site/ and .cache/)

Unchanged Files

docs/ (still gitignored, local-only)
README.md (to be simplified by user)
CLAUDE.md (local-only, no changes needed)

Rollback Plan

If needed, documentation migration can be rolled back:

# Remove MkDocs files
rm -rf documentation/ site/ mkdocs.yml

# Restore Makefile (remove docs commands)
git checkout main -- Makefile

# Restore .gitignore
git checkout main -- .gitignore

# Remove GitHub Actions workflow
rm .github/workflows/docs.yml

Benefits of Migration

Before (Inline README)

  • ❌ Single 650-line README file
  • ❌ No search functionality
  • ❌ No version history for docs
  • ❌ Difficult to navigate
  • ❌ No syntax highlighting in examples

After (MkDocs)

  • ✅ Organized, paginated documentation
  • ✅ Full-text search across all pages
  • ✅ Git-tracked version history
  • ✅ Clear navigation with sections
  • ✅ Syntax highlighting and admonitions
  • ✅ Mobile-friendly responsive design
  • ✅ Automatic deployment with CI/CD

Next Steps

  1. Review all documentation pages for accuracy
  2. Simplify main README.md as described above
  3. Test local documentation preview with make docs-serve
  4. Push to main to trigger automatic deployment
  5. Verify GitHub Pages deployment at https://nouuu.github.io/voice-transcriber
  6. Update repository links to documentation site

Questions?