Migrating from Docusaurus to MkDocs

Recently, I migrated my personal site from Docusaurus to MkDocs. This decision was driven by several factors, but a significant one was that Docusaurus is owned and maintained by Meta. While Docusaurus is a powerful and flexible documentation framework, I wanted to move to a platform that is more community-driven and open, aligning better with my values.

MkDocs, especially with the Material theme, offers a clean, fast, and highly customizable experience for static site generation. The migration process involved restructuring my documentation, updating configuration files, and moving content from MDX to standard Markdown. I also appreciated MkDocs' straightforward integration with Python tooling and its active, independent community.

If you're considering a similar move, the process is very manageable and the benefits—especially around transparency and community ownership—are well worth it.

Learning curve

The learning curve for mkdocs is pretty shallow, especially with moving from docusaurus. Both build static sites off of markdown files, so the bulk of documentation doesn't need to change. There are some intricasies with updating the mkdocs.yml file that I need to dive in some more on, but I have zero complains for creating a basic site and publishing quickly.

Deploying website

For deployment, I use GitHub Actions to automate the build and deployment process. Whenever I push changes to the main branch, a GitHub Actions workflow is triggered that builds the MkDocs site and syncs the generated static files to an Amazon S3 bucket. The site is then served through Amazon CloudFront, which provides a fast and secure CDN for global access.

This setup allows me to focus on writing content and making improvements, while the deployment and hosting are handled automatically in the background. Using S3 and CloudFront together ensures that the site is highly available, scalable, and benefits from low-latency delivery to visitors around the world.

It's important to note that while you can host a static site directly from S3, that is limited to http connections. I'd prefer to let anyone who stumbles upon this site the comfort in knowing that it's using a secure connection.

flowchart TD
    J[Writer Creates Content] --> K[Git Commit Attempt]
    K --> L[Pre-commit Hook Runs]
    L --> M[mkdocs build]
    M --> N{Build Successful?}
    N -->|Yes| A[Push to Main Branch]
    N -->|No| O[Fix Build Errors]
    O --> K

    A --> B[GitHub Actions Triggered]
    B --> C[Build MkDocs Site]
    C --> D[Generate Static Files]
    D --> E[Sync to Amazon S3 Bucket]
    E --> F[Amazon CloudFront CDN]
    F --> P[Invalidate CloudFront Cache]
    G--> S[Verify Site Accessibility]
    P --> G[Global Content Delivery]
    G --> H[HTTPS Secure Connection]
    H --> I[Users Access Site]

    style A fill:#e1f5fe,color:#000
    style B fill:#f3e5f5,color:#000
    style C fill:#f3e5f5,color:#000
    style D fill:#f3e5f5,color:#000
    style E fill:#fff3e0,color:#000
    style F fill:#fff3e0,color:#000
    style P fill:#fff3e0,color:#000
    style S fill:#e8f5e8,color:#000
    style G fill:#e8f5e8,color:#000
    style H fill:#e8f5e8,color:#000
    style I fill:#e8f5e8,color:#000
    style J fill:#e1f5fe,color:#000
    style K fill:#ffecb3,color:#000
    style L fill:#ffecb3,color:#000
    style M fill:#ffecb3,color:#000
    style N fill:#ffecb3,color:#000
    style O fill:#ffcdd2,color:#000

    classDef automation fill:#f3e5f5,stroke:#9c27b0,color:#000
    classDef aws fill:#fff3e0,stroke:#ff9800,color:#000
    classDef seo fill:#e3f2fd,stroke:#1976d2,color:#000
    classDef delivery fill:#e8f5e8,stroke:#4caf50,color:#000
    classDef user fill:#e1f5fe,stroke:#2196f3,color:#000
    classDef precommit fill:#ffecb3,stroke:#f57c00,color:#000
    classDef error fill:#ffcdd2,stroke:#d32f2f,color:#000

    class B,C,D automation
    class E,F,P aws
    class Q,R seo
    class S,G,H,I delivery
    class A,J user
    class K,L,M,N precommit
    class O error