Skip to content

Audit Docusaurus site — evaluate migration to MkDocs Material #2

Description

@kristopherjturner

Summary

Audit the current azurelocal.cloud Docusaurus v3 site and evaluate whether to:

  1. Keep Docusaurus - Continue with Docusaurus as the community portal / landing page, distinct from the MkDocs Material solution repos
  2. Migrate to MkDocs Material - Unify all 5 repos on the same documentation platform for consistency

Current State

  • azurelocal.cloud runs Docusaurus v3.7.0 with Azure blue (#0078D4) theme
  • All 4 solution repos use MkDocs Material with a golden config standard
  • Docusaurus serves as the community portal with blog, landing page, and cross-site navigation (Solutions dropdown)
  • MkDocs repos are technical docs per solution

Evaluation Criteria

  • Feature comparison: blog support, landing pages, search, versioning
  • Maintenance burden: two platforms vs. one
  • Community familiarity: Docusaurus React-based vs. MkDocs Markdown-only
  • Current Docusaurus-specific features in use (blog, custom pages, MDX)
  • Migration effort estimate if switching
  • SEO / discoverability impact
  • Cross-site navigation consistency

Deliverable

A written recommendation (comment on this issue or doc) with the decision and rationale.

Activity

  1. kristopherjturner commented on May 10, 2026

    @kristopherjturner
    ContributorAuthor
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions