Chef Docs: Migrate To Docusaurus With TypeScript

by Admin 49 views
Migrate Chef Documentation to Docusaurus with TypeScript

The Grand Migration: Bringing Intra365 Chef Docs to Docusaurus!

Hey folks! So, we're embarking on a pretty epic journey to supercharge the documentation for Intra365 Chef, our awesome GitOps deployment orchestration system. Think of Chef as the central nervous system for all our Intra365 services humming away on Kubernetes clusters (AKS). It's the glue that holds everything together, making sure deployments, configurations, and lifecycles run smoother than a greased otter. To really do it justice, we need documentation that’s not just accurate, but also super easy to navigate, searchable, and keeps up with our fast-paced development. That's where Docusaurus and TypeScript come into play!

Why Docusaurus and TypeScript, You Ask?

We're talking about creating a full-blown documentation website, and Docusaurus is like the Swiss Army knife for this. It’s built on React, which means we can create dynamic, interactive content. Plus, with TypeScript, we're adding a layer of safety and clarity to our configuration files, making sure everything is as robust as possible. It’s all about making our docs as sophisticated as the system they describe. We want to make sure our documentation reflects the current production state, previous versions for historical reference, and even gives us a peek into future architectures. And because we live and breathe GitOps, our docs will be living right alongside our code, managed with version control. Super important stuff!

What We’re Aiming For (The Goals)

Before we dive headfirst into the technical nitty-gritty, let's lay out what we want to achieve with this migration. It’s not just about moving files; it’s about transforming how we manage and access our knowledge. Our primary goal is to implement Docusaurus 3 with a solid TypeScript configuration. This means everything from our main config file (docusaurus.config.ts) to our sidebars (sidebars.ts) will be written in TS, giving us better type safety and developer experience. We'll be setting up versioned documentation, which is crucial for tracking changes over time. Imagine easily switching between the docs for our current stable release, a previous version, and even a preview of what's coming next. How cool is that?

But we're not stopping there! We're also implementing a structured, numeric-prefixed directory structure. This isn't just for looks; it's about logical organization. Think of it like a Dewey Decimal System for our tech docs, making it super intuitive to find what you need. Need to find something fast? We’ve got you covered with local search integration using @easyops-cn/docusaurus-search-local. This means no more hopping between different search tools or relying on external services – everything will be lightning-fast and right there in the browser. And for those complex architectural diagrams or workflow visualizations? We're baking in Mermaid diagram support. This allows us to draw awesome diagrams directly in Markdown, keeping them version-controlled and always up-to-date with our code. Pretty neat, right?

Finally, a huge focus is on GitOps workflows. This means our documentation process will be automated, triggered by code changes, and seamlessly integrated into our CI/CD pipelines. We're also ensuring accessibility compliance, aiming for a neurodiversity-friendly experience so everyone can access and understand the information. This whole initiative is about embracing documentation-as-code – treating our docs with the same rigor and best practices as our application code. It’s a big undertaking, but the payoff in terms of clarity, discoverability, and maintainability will be massive. Let’s get this done, team!

The Blueprint: A Glimpse into the New Structure

Alright guys, let's get our hands dirty and visualize what this new documentation kingdom will look like. We're talking about a highly organized, scalable, and super accessible structure that’s going to make finding information a breeze. The core idea is to have everything logically grouped, easily navigable, and version-controlled, all powered by Docusaurus. This new setup isn't just a file reorganization; it's a strategic enhancement to how we manage and consume our technical knowledge.

Root Structure: The Foundation

At the very top level, within our chef/ repository, you’ll find a few key directories that form the backbone of our documentation site. The star of the show is the docs/ directory. This is where all our juicy content will live, meticulously organized. We’re using a numeric prefix system for subdirectories here (e.g., 010-introduction/, 020-architecture/, etc.). This isn't just for show; it ensures a consistent, logical order in the sidebar navigation, making it super easy for anyone to follow the flow of information, whether they're onboarding a new team member or diving deep into a specific module. Imagine going from a high-level introduction straight into detailed architecture, then diving into infrastructure specifics, deployment workflows, service configurations, and so on. It’s a guided journey!

Then we have versioned_docs/. This is where Docusaurus magic happens for versioning. Every time we snapshot a new version, Docusaurus will automatically create a copy of our docs/ content here, preserving it for future reference. This is absolutely critical for maintaining historical accuracy and allowing users to check out documentation for older releases. Next up is the src/ directory. This is our playground for custom React components and pages written in TypeScript. If we need anything beyond standard Markdown, like interactive dashboards or custom UI elements within our docs, this is where we’ll build it. And static/ is for all our assets – think images, logos, JSON schemas, OpenAPI specs – anything that needs to be served directly.

Our configuration files are also front and center: docusaurus.config.ts and sidebars.ts, both in TypeScript, are the brains of the operation, defining how the site looks, behaves, and navigates. tsconfig.json ensures our TypeScript setup is on point, and package.json manages our dependencies. Finally, versions.json is the master list of all the versions we’re tracking. It’s a clean, well-defined structure that sets us up for success.

Diving Deeper: Section by Section Breakdown

Let's peel back the layers and look at what each of these numerically prefixed directories in docs/ will contain. This structured approach is designed for clarity and comprehensiveness, ensuring no stone is left unturned.

  • 010-introduction/: This is our welcome mat. It covers the absolute basics: an overview of Chef's purpose and value, defining key concepts like GitOps and orchestration, a quick-start guide to get new users up and running in minutes, a high-level architecture overview diagram, and a glossary to define all our unique terms. It’s the perfect starting point for anyone new to the Intra365 ecosystem.
  • 020-architecture/: Here, we go deep. We’ll document the overall system architecture, detail the GitOps workflow itself, provide component diagrams showing how everything interacts, map out our integration points (like NATS and STS), explain the deployment pipeline, and map out our multi-environment strategy (Dev, Staging, Prod). This section is crucial for understanding the 'how' and 'why' behind Chef's design.
  • 030-infrastructure/: This is where we get hands-on with the nuts and bolts of our infrastructure. We'll cover Azure AKS setup, delve into networking architecture, explain storage configurations, detail secrets management (especially our Azure Key Vault CSI integration), outline our observability stack (monitoring, logging, tracing), document disaster recovery procedures, explain our scaling strategy, and importantly, detail our prompt-based platform configuration approach. This section is vital for anyone responsible for maintaining or extending our infrastructure.
  • 040-deployment-workflows/: This section is all about how we get code from commit to production. We'll cover the deployment overview, detail conventional deployment patterns, explain Helm charts and Kustomize overlays, showcase our GitHub Actions workflows, detail rollback procedures, and explain advanced strategies like canary deployments and zero-downtime updates. If you need to deploy something, this is your go-to guide.
  • 050-service-configurations/: This is the meat and potatoes for individual services. We’ll document the standard service repository pattern and then provide specific configuration details for each of our core Intra365 services: STS, Consent Manager, Mate Registry, Gateway, LLM Proxy, as well as infrastructure components like NATS and PostgreSQL. This section ensures consistency and makes managing individual services a much simpler task.
  • 060-security-compliance/: Security is paramount. Here, we’ll detail our Zero Trust Architecture, explain our RAISE 2.0 DevSecOps compliance measures, document our security gates in CI/CD (SAST, DAST, SBOM), cover container security best practices, explain network policies, detail secrets rotation, and discuss audit logging, vulnerability management, and residual risk tracking. This is our defense in depth strategy, documented.
  • 070-operations-runbooks/: For the day-to-day heroes, this section contains essential runbooks. We'll cover daily operations, incident response procedures, maintenance windows, backup and restore processes, certificate renewal, scaling operations, log analysis techniques, and health check procedures. If something needs doing, there should be a runbook here.
  • 080-troubleshooting/: When things go wrong (and they sometimes do!), this is where you'll find help. We'll list common issues, provide debugging steps for deployment failures, tackle networking problems, diagnose storage issues, guide performance debugging, explain how to handle security alerts, and list essential diagnostic tools and commands. This section is designed to get things back on track, fast.
  • 090-reference/: This is our definitive reference library. It includes API documentation, a comprehensive CLI command reference, details on all configuration options, an environment variable reference, Helm values, Kubernetes resources (CRDs), OpenAPI specifications, and crucially, our platform prompt library. Think of this as the ultimate cheat sheet.
  • 100-contributing/: For anyone wanting to get involved, this section lays out the roadmap. It includes contribution guidelines, code and documentation standards, the pull request process, our release process, and information on how to connect with our community. We want to make contributing as smooth as possible.
  • 110-roadmap/: This is our crystal ball! Living within the docs/ directory for unified navigation, this section details our future. It covers the roadmap overview, dives into planned features (like multi-cloud support and AI orchestration), explores architecture evolution (serverless, WASM), outlines migration paths (v1 to v2, legacy to cloud-native), and documents experimental features and Proofs of Concepts (POCs). This keeps everyone aligned on where we're headed.

This detailed structure, combined with the power of Docusaurus, is going to make our Chef documentation a true asset to the team. It’s organized, comprehensive, and built for the future!

The Tech Stack: Making it Happen!

Alright team, let's talk about the nuts and bolts – the actual technologies and configurations we'll be using to bring this documentation vision to life. We're leveraging the latest and greatest from Docusaurus, combined with TypeScript and some nifty plugins, to create a documentation experience that's not just informative but also incredibly powerful and user-friendly.

1. Docusaurus Configuration with TypeScript (docusaurus.config.ts)

This is the heart of our Docusaurus setup. We’re using TypeScript for this configuration file, which gives us type safety and better autocompletion as we build out our site. Here’s a peek at what it looks like:

import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'Intra365 Chef',
  tagline: 'GitOps Deployment Orchestration for Intra365',
  favicon: 'img/favicon.ico',

  url: 'https://chef.intra365.dev',
  baseUrl: '/',

  organizationName: 'intra365',
  projectName: 'chef',

  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
          editUrl: 'https://github.com/intra365/chef/tree/main/',
          showLastUpdateAuthor: true,
          showLastUpdateTime: true,
          versions: {
            current: {
              label: 'Current (main)',
              path: 'current',
            },
          },
          remarkPlugins: [
            [require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}],
          ],
        },
        blog: false, // We're focusing on docs for now
        theme: {
          customCss: './src/css/custom.css',
        },
      } satisfies Preset.Options,
    ],
  ],

  themes: ['@docusaurus/theme-mermaid'], // Enable Mermaid diagrams!
  
  markdown: {
    mermaid: true, // Ensure Mermaid rendering is enabled
  },

  plugins: [
    // Roadmap is integrated into docs/, no separate plugin needed
  ],

  themeConfig: {
    image: 'img/chef-social-card.jpg',
    navbar: {
      title: 'Chef',
      logo: {
        alt: 'Intra365 Chef Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'docs',
          position: 'left',
          label: 'Documentation',
        },
        {
          type: 'docSidebar',
          sidebarId: 'roadmap',
          position: 'left',
          label: 'Roadmap',
        },
        {
          type: 'docsVersionDropdown',
          position: 'right',
          dropdownActiveClassDisabled: true,
        },
        {
          type: 'search',
          position: 'right',
        },
        {
          href: 'https://github.com/intra365/chef',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      // ... (detailed footer links for docs, resources, community)
      copyright: `Copyright © ${new Date().getFullYear()} Happy Mates. Built with Docusaurus.`, 
    },
    prism: {
      // ... (syntax highlighting themes and languages)
    },
    mermaid: {
      // ... (Mermaid theme options)
    },
  } satisfies Preset.ThemeConfig,
};

export default config;

Key takeaways here are the explicit enabling of Mermaid for diagrams, the definition of our navigation bar with links to both main documentation and the roadmap, and the setup for versioning. We’re also configuring the prism theme for syntax highlighting, which is a must-have for code examples.

2. Version Management: Keeping Track of Time

Docusaurus makes versioning a breeze. We'll use a versions.json file to keep track of our releases:

// versions.json (example)
[
  "2.0.0",
  "1.1.0",
  "1.0.0"
]

To create a new version snapshot, we simply run:

# Create a new version snapshot
pnpm docusaurus docs:version 2.0.0

This command automatically handles snapshots of our docs/ content, creates versioned sidebars, and updates versions.json. It’s a clean, automated way to manage our documentation's history.

3. Search Made Simple: @easyops-cn/docusaurus-search-local

For lightning-fast, client-side search that works even offline, we're integrating @easyops-cn/docusaurus-search-local. This plugin is a game-changer because it doesn't rely on external APIs, making it perfect for our GitOps environment. We configure it right within docusaurus.config.ts:

// ... inside docusaurus.config.ts

themes: [
  '@docusaurus/theme-mermaid',
  [
    require.resolve('@easyops-cn/docusaurus-search-local'),
    {
      hashed: true,
      language: ['en'],
      highlightSearchTermsOnTargetPage: true,
      explicitSearchResultPath: true,
      docsRouteBasePath: '/docs', // Important for correct linking
      indexBlog: false, // We don't have a blog for now
      indexPages: false, // Focus on docs and potentially custom pages
      searchResultLimits: 8,
      searchResultContextMaxLength: 50,
      ignoreFiles: [ \/versions\.json$/, \/_category_\.json$/ ], // Exclude specific files
      searchBarShortcut: true, // Cmd/Ctrl+K shortcut
      searchBarShortcutHint: true,
      searchBarPosition: 'right',
    },
  ],
],
// ... rest of config

This plugin provides a robust search experience with features like keyboard shortcuts (Cmd/Ctrl+K), context highlighting, and multi-language support, all without external dependencies.

4. TypeScript Configuration (tsconfig.json)

We'll maintain a standard TypeScript configuration file to ensure our TS code, including Docusaurus configs and custom components, compiles correctly:

// tsconfig.json
{
  "extends": "@docusaurus/tsconfig",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@site/*": ["./src/*"]
    }
  },
  "include": ["src/**/*", "docusaurus.config.ts", "sidebars.ts"]
}

This setup allows us to use aliases like @site/* for easier imports from our src/ directory.

5. Sidebar Configuration (sidebars.ts)

Our sidebar structure is critical for navigation. We're using TypeScript to define it, incorporating emojis for visual appeal and clarity, and leveraging Docusaurus's generated-index type for automatic category landing pages. We’ll have two main sidebars: docs for our core content and roadmap for future plans.

// sidebars.ts
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  // Main documentation sidebar
  docs: [
    // ... (Sections 010-100 as defined in the proposal, e.g., Introduction, Architecture, etc.)
    {
      type: 'category',
      label: '📘 Introduction',
      link: { type: 'generated-index', title: 'Introduction to Chef', slug: '/introduction' },
      items: ['010-introduction/01-overview', /* ... other intro items */],
    },
    // ... more categories for Architecture, Infrastructure, etc.
    {
      type: 'category',
      label: '🤝 Contributing',
      link: { type: 'generated-index', title: 'Contributing to Chef', slug: '/contributing' },
      items: ['100-contributing/01-contribution-guidelines', /* ... */],
    },
  ],

  // Roadmap sidebar (future state documentation)
  roadmap: [
    {
      type: 'doc',
      id: '110-roadmap/01-roadmap-overview',
      label: '🗺️ Roadmap Overview',
    },
    {
      type: 'category',
      label: '✨ Planned Features',
      link: { type: 'generated-index', title: 'Planned Features', slug: '/roadmap/planned-features' },
      items: ['110-roadmap/010-planned-features/01-multi-cloud-support', /* ... */],
    },
    // ... more categories for Architecture Evolution, Migration Paths, Experimental
  ],
};

export default sidebars;

This structure ensures a clear, visually appealing, and logically organized navigation experience. The use of generated-index automatically creates overview pages for each category, which is a huge time saver.

6. GitHub Actions for GitOps Deployment

Our documentation process is inherently GitOps. We'll use GitHub Actions to build and deploy the documentation site automatically whenever changes are pushed to the main branch. We’ll also have a separate workflow for deploying the actual Intra365 platform to AKS.

.github/workflows/deploy-docs.yml (for documentation deployment):

name: Deploy Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 } # Need full history for versioning
      
      - uses: pnpm/action-setup@v4
        with: { version: 10.14.0 }
      
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'pnpm' }
      
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      
      - name: Build documentation
        run: pnpm build
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with: { path: build }

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

And a sample for platform deployments:

.github/workflows/deploy-platform.yml (for AKS):

name: Deploy to AKS

on:
  push:
    branches: [main]
    paths: [manifests/**, helm/**]
  workflow_dispatch: # Manual trigger

permissions: { id-token: write, contents: read }

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      
      - name: Azure Login
        uses: azure/login@v2
        with: { /* ... Azure credentials ... */ }
      
      - name: Get AKS credentials
        run: | 
          az aks get-credentials --resource-group ${{ vars.AKS_RESOURCE_GROUP }} --name ${{ vars.AKS_CLUSTER_NAME }}
      
      - name: Deploy with Helm
        run: | 
          helm upgrade --install chef-services ./helm/chef --namespace intra365 --create-namespace --wait --timeout 10m
      
      - name: Apply Kustomize overlays
        run: | 
          kubectl apply -k manifests/overlays/production
      
      - name: Verify deployment
        run: | 
          kubectl rollout status deployment/chef-gateway -n intra365

These workflows ensure that our documentation is always up-to-date and deployed automatically, while also managing our platform deployments securely using OIDC and standard Kubernetes tools.

The Roadmap: A Phased Approach to Documentation Excellence

To ensure a smooth and efficient migration, we're breaking down the process into manageable phases. This phased approach allows us to tackle specific aspects of the documentation overhaul systematically, ensuring quality and completeness at each step. It’s like building a house – you lay the foundation first, then frame the walls, and so on.

Phase 1: Setup & Configuration (Week 1)

This initial phase is all about getting the technical scaffolding in place. We'll start by initializing a new Docusaurus 3 project and configuring it to use TypeScript. This includes setting up our docusaurus.config.ts, sidebars.ts, and tsconfig.json files. We’ll establish the pnpm workspace for efficient dependency management and create the fundamental directory structure (010-introduction through 100-contributing, plus the roadmap section). Crucially, we'll integrate and configure essential plugins: versioning support to manage different releases, @easyops-cn/docusaurus-search-local for fast, client-side search, and @docusaurus/theme-mermaid for rendering our diagrams. Finally, we'll set up the GitHub Actions workflow for automated documentation builds and perform initial tests to ensure Mermaid diagrams render correctly in both light and dark themes. This phase lays the groundwork for everything that follows.

Phase 2: Content Migration (Week 2-3)

With the technical foundation set, we move to the core task: migrating existing content. We'll start by taking content from our current README files and restructuring it into the 010-introduction/ directory. Then, we'll systematically move and enhance documentation for our current architecture into 020-architecture/, detail our infrastructure setup in 030-infrastructure/, and document the various deployment workflows in 040-deployment-workflows/. We’ll also create templates and initial content for service configurations in 050-service-configurations/. This phase focuses on getting the existing knowledge into the new Docusaurus structure.

Phase 3: Security & Compliance (Week 3-4)

Security and compliance are non-negotiable. This phase dedicates time to documenting our Zero Trust Architecture within 060-security-compliance/, clearly outlining our adherence to RAISE 2.0 DevSecOps standards. We’ll detail the security gates integrated into our CI/CD pipelines (like SAST, DAST, and SBOM generation), cover best practices for container security, explain our Kubernetes network policies, and document processes for secrets rotation, audit logging, vulnerability management, and residual risk tracking. This ensures our security posture is well-documented and understood.

Phase 4: Operations & Troubleshooting (Week 4-5)

This phase focuses on the practical day-to-day aspects of managing the platform. We'll create a comprehensive set of operational runbooks in 070-operations-runbooks/, covering everything from daily tasks and incident response to maintenance, backups, and certificate management. Concurrently, we'll build out the troubleshooting guide in 080-troubleshooting/, detailing common issues, debugging steps for deployments, network problems, storage challenges, performance bottlenecks, and security alerts. We’ll also include a section on essential diagnostic tools. The goal here is to empower the operations team with the knowledge they need to keep the platform running smoothly.

Phase 5: Reference & Contributing (Week 5-6)

In this phase, we’ll solidify our reference materials and contribute guidelines. The 090-reference/ directory will be populated with API documentation, CLI commands, detailed configuration options, environment variable lists, Helm values, Kubernetes resource definitions, OpenAPI specs, and importantly, our platform prompt library. We'll also establish the contribution guidelines in 100-contributing/, covering code standards, documentation practices, and the PR process. Finally, we'll flesh out the roadmap section (110-roadmap/), documenting planned features, future architectural directions, migration strategies, and experimental initiatives. This phase ensures we have a complete knowledge base and clear pathways for future development and contribution.

Phase 6: Polish & Launch (Week 6)

The final phase is all about refinement and delivery. We’ll conduct a thorough review of all migrated and newly created content, ensuring consistency, accuracy, and clarity. We'll double-check accessibility compliance and test the search functionality across the entire site, including the roadmap. Verifying the sidebar navigation for both the main docs and the roadmap sections is crucial. We'll then create the 1.0.0 version snapshot and prepare for the final deployment to GitHub Pages (or Azure Static Web Apps). This phase ensures a polished, high-quality documentation site ready for prime time.

By following these phases, we’ll systematically transform our documentation into a powerful, modern resource that truly reflects the complexity and importance of the Intra365 Chef system.

Making Docs Accessible for Everyone!

Hey everyone, let’s chat about something super important: accessibility, especially for our neurodiverse colleagues. We want our documentation to be usable and understandable by everyone, regardless of how their brain is wired. This means going beyond just meeting basic standards; it’s about building documentation with empathy and a clear focus on cognitive load and ease of comprehension.

How are we doing this? Well, first off, the clear structure with those numeric prefixes we talked about? That’s a huge win for predictability. People know what to expect and where to find things without having to hunt. Every guide will explicitly state its expected outcomes – what you should achieve by the end of it. No more guessing games!

We're also going big on visual diagrams using Mermaid. Complex workflows and architectures can be really hard to grasp through text alone. Mermaid lets us create clear, version-controlled visuals that break down complexity. And for the actual steps? We're focusing on step-by-step instructions. Forget those vague statements; we want precise, actionable steps that leave no room for ambiguity. We’re committed to consistent formatting throughout the entire site. If we use a certain style for code blocks or callouts, we stick to it everywhere. This consistency reduces cognitive load and makes the docs feel familiar, no matter which section you're in.

Naturally, the robust search functionality we’re adding is key. Not everyone navigates linearly; some people prefer to jump straight to what they need via search. And finally, every page will have a clear table of contents, giving users multiple ways to navigate and understand the structure of the content they're viewing. By prioritizing these elements, we’re not just building documentation; we’re building an inclusive knowledge resource.

How We'll Know We've Succeeded (Success Criteria)

Okay, so how do we measure if this whole Docusaurus migration project is a win? We've got some clear benchmarks, guys. Hitting these targets means we've successfully transformed our documentation into a top-tier resource.

First and foremost, all documentation migrated to the Docusaurus structure under docs/ is a must. This includes the roadmap integrated as section 110, accessible via its own dedicated sidebar. That unified structure is key.

We need to ensure local search (@easyops-cn/docusaurus-search-local) is fully functional. Test it! Can you find information quickly? Does the keyboard shortcut (Cmd/Ctrl+K) reliably open the search modal? That’s a core usability feature.

Mermaid diagram support needs to be working flawlessly in both light and dark themes. Visually appealing and functional documentation is the goal.

Versioning has to be configured and tested. We need to be able to track at least three versions (current, v1.0.0, and ideally the roadmap across versions). Can you switch between them seamlessly?

Our GitHub Actions must successfully deploy the documentation on every push to main. We also need to have the workflows for platform deployments documented within the site itself. That’s the GitOps dream right there.

The top navigation bar should clearly display 'Documentation', 'Roadmap', the 'Version Dropdown', and the 'Search' icon. Similarly, the sidebar navigation must work perfectly for both the main documentation sections and the roadmap.

We expect RAISE 2.0 compliance documentation to be complete, ideally featuring Mermaid diagrams where appropriate. Likewise, architecture diagrams using Mermaid in the 020-architecture section are essential. Make sure those diagrams clearly show GitHub Actions for GitOps deployment, not other tools like ArgoCD or Flux.

A huge checkmark is 100% of existing content migrated with improvements – not just a lift-and-shift. We're making it better!

Crucially, the documentation must build with zero warnings or errors. This applies to TypeScript compilation too – no type errors allowed! That’s the stability we’re aiming for.

We need to verify that all 11 sections (010-110) are properly structured with their numeric prefixes. And the footer links should be logically organized across 'Documentation', 'Resources', and 'Community'.

Finally, the search should index all content, including code blocks and headings, making every piece of information discoverable. If we hit all these points, team, we've absolutely nailed it!

What We Need to Make This Happen (Dependencies)

To get this documentation project off the ground, we'll be relying on a specific set of tools and libraries. These are the building blocks that will power our Docusaurus site. You can find these listed in our package.json file, ensuring we have a clean and reproducible environment.

Here’s a breakdown of the key packages we’ll be using:

  • @docusaurus/core and @docusaurus/preset-classic: These are the foundational Docusaurus packages that provide the core framework and a standard set of features for building documentation sites.
  • @docusaurus/theme-mermaid: This gem brings native Mermaid diagram support directly into our Markdown files, making it super easy to create and embed visualizations.
  • @docusaurus/remark-plugin-npm2yarn: This handy plugin automatically converts code blocks to show commands for npm, yarn, and pnpm, making our examples more accessible to developers using different package managers.
  • @easyops-cn/docusaurus-search-local: As discussed, this is our go-to for powerful, client-side search functionality without any external API dependencies.
  • @mdx-js/react: Docusaurus uses MDX, which allows us to embed React components directly within our Markdown files. This package is essential for that capability.
  • clsx: A utility for constructing class names conditionally, which is super helpful for managing CSS classes in React components.
  • prism-react-renderer: Powers the syntax highlighting for code blocks across our documentation.
  • react and react-dom: The core React libraries that Docusaurus is built upon.

For development and build tooling, we'll be using:

  • @docusaurus/module-type-aliases and @docusaurus/tsconfig: These help with TypeScript integration within the Docusaurus ecosystem.
  • @docusaurus/types: Provides TypeScript types for Docusaurus configurations.
  • typescript: The TypeScript compiler itself, ensuring our TypeScript code is checked and compiled correctly.

And crucially, we're standardizing on pnpm as our package manager:

{
  "name": "intra365-chef-docs",
  "version": "2.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids",
    "typecheck": "tsc"
  },
  "dependencies": {
    "@docusaurus/core": "^3.7.0",
    "@docusaurus/preset-classic": "^3.7.0",
    "@docusaurus/theme-mermaid": "^3.7.0",
    "@docusaurus/remark-plugin-npm2yarn": "^3.7.0",
    "@easyops-cn/docusaurus-search-local": "^0.46.0",
    "@mdx-js/react": "^3.1.0",
    "clsx": "^2.1.1",
    "prism-react-renderer": "^2.4.1",
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
    "@docusaurus/module-type-aliases": "^3.7.0",
    "@docusaurus/tsconfig": "^3.7.0",
    "@docusaurus/types": "^3.7.0",
    "typescript": "~5.7.2"
  },
  "packageManager": "pnpm@10.14.0",
  "engines": {
    "node": ">=20.0.0"
  }
}

We're specifying pnpm@10.14.0 and node: >=20.0.0 to ensure a consistent build environment. This setup provides us with a robust, modern, and maintainable platform for our documentation.

The Future of Configuration: Prompt-Based Magic!

You know how sometimes Infrastructure-as-Code (IaC) can feel a bit… rigid? Like you’re locked into specific tools and syntax that might get outdated or require massive refactoring when something new comes along? Well, we're taking a different, more flexible approach for configuring our Intra365 platform using Chef: prompt-based configuration. Think of it as giving instructions in plain English (or a structured version of it) rather than writing complex code. This makes our platform way more adaptable and future-proof.

Why Ditch Traditional IaC (for Docs)?

Traditional IaC tools, while powerful, have their downsides:

  • Tool Lock-in: You're tied to the specific DSL (like Terraform HCL or CloudFormation YAML) and its version. Upgrading can be a nightmare.
  • Brittleness: A minor syntax change or deprecation can break your entire setup.
  • Learning Curve: Each tool has its own syntax and paradigms to master.
  • Slow Adoption: Implementing new cloud features or best practices can be slow if the IaC tool doesn't support them yet.
  • Experimentation Hurdles: Trying out new approaches can be cumbersome.

Our prompt-based approach aims to sidestep these issues. It’s about describing what we want, not exactly how to build it using a specific tool’s syntax. This allows the platform (Chef) to figure out the best way to implement it using current best practices and available tooling.

How It Works: Prompts as Instructions

Instead of writing lines of HCL like this (which we won't be doing for our documentation examples):

# Traditional Terraform approach (NOT USED HERE)
resource "azurerm_kubernetes_cluster" "aks" {
  name                = "intra365-aks"
  location            = "eastus"
  resource_group_name = "intra365-rg"
  # ... plus like 50 more lines of configuration!
}

We’ll use natural language prompts, often structured with clear requirements and context. Imagine a prompt like this:

# Prompt-Based Approach (Chef)

## AKS Cluster Setup Prompt

Create an Azure Kubernetes Service cluster for the Intra365 platform with:

**Requirements:**
- Zero-trust security model with Azure AD integration
- RAISE 2.0 compliance for DoD workloads
- Auto-scaling node pools (min: 3, max: 10)
- Availability zones for high availability
- Azure CNI networking with network policies
- Integration with Azure Key Vault via CSI driver
- Azure Monitor and Log Analytics enabled
- Private cluster endpoint for enhanced security
- System node pool separate from user workloads
- Managed identity authentication

**Compliance:**
- NIST 800-53 controls
- CIS Kubernetes Benchmark
- Azure Security Baseline

**Best Practices:**
- Use latest stable Kubernetes version
- Enable pod security policies
- Configure resource quotas per namespace
- Implement network policies for zero-trust

Generate the appropriate Azure CLI commands, Bicep templates, or portal configuration steps to implement this configuration following current Azure best practices as of the deployment date.

See? It’s declarative and intent-driven. The prompt clearly outlines the desired state, security requirements, and best practices. Chef (or the underlying tooling it orchestrates) would then interpret this prompt and generate the necessary configuration (e.g., Azure CLI commands, Bicep code, or directly interact with cloud APIs) to make it happen. This keeps our documentation focused on the intent rather than the implementation details of a specific tool.

Documentation Structure Supporting Prompts

This philosophy is woven into our documentation structure:

  • 030-infrastructure/08-platform-configuration.md: This section will host prompt templates for setting up various parts of our infrastructure. It’ll cover best practices for writing these prompts and provide examples, explaining how they evolve over time.
  • 090-reference/08-platform-prompts.md: This will be our comprehensive library of reusable prompts, categorized for easy access. Think of it as a catalog of well-defined infrastructure and configuration intentions.

The Awesome Benefits!

This prompt-based approach offers some serious advantages:

  • Timeless Documentation: Prompts describe intent. As tools or best practices change, the interpretation of the prompt can adapt, keeping the documentation relevant without constant syntax updates.
  • Adaptability: It works seamlessly whether we're using Azure CLI, Bicep, ARM, or even future tools. The core intent remains the same.
  • Understandability: Prompts are generally easier to read and understand than dense IaC code, making knowledge sharing smoother.
  • Auditable Intent: The prompts, stored in Git, provide a clear, version-controlled record of why certain configurations were chosen.
  • AI-Assisted: This format is perfect for AI coding assistants like GitHub Copilot, which can help generate the actual implementation based on the prompt.
  • Best Practice Alignment: By having Chef interpret prompts based on current best practices, we automatically stay aligned with the latest recommendations from cloud providers.

We'll include prompts for everything from provisioning clusters and configuring security to setting up observability and defining service deployments. It's a more agile and intelligent way to manage our infrastructure configuration.

Visualizing Complexity: The Power of Mermaid Diagrams

Alright team, let's talk about making our documentation not just informative, but also visually engaging and easy to understand. For complex systems like Intra365 Chef, simply writing out descriptions can get dense and confusing quickly. That’s where Mermaid diagrams come in, and we’re integrating them deeply into our Docusaurus setup. Mermaid allows us to draw flowcharts, sequence diagrams, state diagrams, and more, directly within our Markdown files using a simple text-based syntax. This is a massive win for clarity and maintainability!

Why Mermaid is a Game-Changer for Docs

Think about it: instead of static, potentially outdated image files, we have diagrams that are:

  1. Version Controlled: Diagrams live in Git alongside the Markdown text. When you review a code change, you see the diagram change too. No more stale screenshots!
  2. Always Accurate: Because they're text-based, they update automatically with the content. What you see is what you get.
  3. Theme Aware: Mermaid integrates beautifully with Docusaurus's light and dark modes, automatically adjusting its appearance so your diagrams always look great.
  4. Accessible: The underlying text syntax can be parsed by screen readers, providing a layer of accessibility that image files often lack.
  5. Easy to Edit: Modifying a diagram is as simple as editing text. No need for dedicated diagramming tools.
  6. GitOps Native: This fits perfectly with our GitOps philosophy. Everything is code, including our visualizations.

Examples of What We'll Document with Mermaid

We'll be using Mermaid across various sections to illustrate key concepts:

  • GitOps Deployment Flow: Showing the journey from a Git commit to a successful deployment on AKS. This helps everyone understand the triggers, steps, and outcomes.

    ```mermaid
graph LR
    A[Git Commit] --> B[GitHub Actions]
    B --> C{Tests Pass?}
    C -->|Yes| D[Build Image]
    C -->|No| E[Notify Team]
    D --> F[Push to Registry]
    F --> G[Update Manifest]
    G --> H[GitHub Actions Deploy]
    H --> I[Apply to AKS]
    I --> J[Health Check]
    J -->|Pass| K[Complete]
    J -->|Fail| L[Auto Rollback]
```

  • Zero-Trust Authentication Flow: Visualizing how user requests are authenticated and authorized in our secure environment.

    ```mermaid
sequenceDiagram
    participant U as User
    participant G as Gateway
    participant S as STS
    participant A as Anomaly Detector
    
    U->>G: Request with JWT
    G->>S: Validate Token
    S->>A: Check Risk Score
    A-->>S: Risk: 45 (Medium)
    S-->>G: Require MFA
    G-->>U: MFA Challenge
    U->>G: TOTP Code
    G->>S: Verify MFA
    S-->>G: Access Granted
    G-->>U: 200 OK + New Token
```

  • Service Architecture: Mapping out the relationships and dependencies between our core Intra365 services.

    ```mermaid
graph TB
    subgraph "Intra365 Ecosystem"
        GW[Gateway]
        STS[Security & Token Service]
        CM[Consent Manager]
        MR[Mate Registry]
        LP[LLM Proxy]
    end
    
    subgraph "Infrastructure"
        NATS[NATS JetStream]
        PG[(PostgreSQL)]
        KV[Key Vault]
    end
    
    GW --> STS
    GW --> CM
    GW --> MR
    GW --> LP
    
    STS --> NATS
    CM --> NATS
    CM --> PG
    
    STS --> KV
    MR --> NATS
    LP --> NATS
```

  • Deployment State Machine: Illustrating the different states a deployment can go through.

    ```mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> Running: Start Deployment
    Running --> Testing: Deploy Complete
    Testing --> Healthy: Health Check Pass
    Testing --> Failed: Health Check Fail
    Healthy --> Monitoring: Promote to Production
    Failed --> Rollback: Initiate Rollback
    Rollback --> Pending: Rollback Complete
    Monitoring --> [*]: Stable
```

By embedding these diagrams directly into our Markdown, we ensure that our documentation is not only comprehensive but also visually intuitive, making complex technical concepts much easier to grasp for everyone on the team.

Looking Ahead: References and Next Steps

As we dive into this migration, it's always good to have quick access to the resources that underpin our work. Here are some key references that will be invaluable:

  • Intra365 Architecture: You'll find the core architecture details likely in /Users/nielsgregersjohansen/Code/happy-mates/happy-mates-intra365/ARCHITECTURE.md. We'll be migrating and enhancing this content.
  • Functional Requirements: For the 'what' behind our systems, check out /Users/nielsgregersjohansen/Code/happy-mates/happy-mates-intra365/FUNCTIONAL_REQUIREMENTS.md.
  • Zero Trust Security: Our foundational security principles are documented at /Users/nielsgregersjohansen/Code/happy-mates/happy-mates-intra365/ZERO_TRUST_SECURITY.md.
  • RAISE 2.0 Guide: For compliance specifics, the /Users/nielsgregersjohansen/Code/happy-mates/happy-mates-intra365/references/RAISE2.0_Implementation_Guide.md will be a critical reference.

Of course, the tools themselves have fantastic documentation:

Labels for tracking this initiative will include: documentation, enhancement, docusaurus, typescript, gitops, and priority: high.

Estimated Effort: We're looking at approximately 6 weeks for this entire migration, breaking down to about 30-40 hours of focused work. This includes setup, content migration, security documentation, operations guides, and final polish/testing. It's a significant but achievable undertaking!