Megadoc Submodule Documentation Patterns

Overview

This instruction applies to repositories that are submodules of the ohemr-epic-megadoc monorepo. Your repository's documentation will be automatically included in the unified megadoc site using the monorepo plugin's !include directive.

Critical Concept: Stub vs. Full Configuration

Your repository provides a STUB mkdocs.yml configuration:

• The megadoc parent repo owns ALL plugins, themes, and global settings
• Your stub provides ONLY: site metadata and navigation structure
• Your docs are included in the parent site's navigation tree via !include

Analogy: You're providing a chapter for a book, not writing your own book.

Required Stub mkdocs.yml

Minimal Required Fields

site_name: your-repository-name
repo_url: https://github.com/optum-tech-compute/your-repository-name
repo_name: optum-tech-compute/your-repository-name
edit_uri: edit/main/docs

Field Descriptions:

• site_name: Display name in megadoc navigation (use repo name for consistency)
• repo_url: Full GitHub URL to your repository
• repo_name: Organization/repository format (shows in UI)
• edit_uri: Path template for "Edit on GitHub" links (usually edit/main/docs)

Optional Navigation

site_name: your-repository-name
repo_url: https://github.com/optum-tech-compute/your-repository-name
repo_name: optum-tech-compute/your-repository-name
edit_uri: edit/main/docs

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Architecture: architecture.md
  - API Reference: api/
  - Changelog: ../CHANGELOG.md
  - Contributing: ../CONTRIBUTING.md

Navigation Best Practices:

• Define nav explicitly for better control (vs. automatic generation)
• Reference root-level files like ../CHANGELOG.md to include repo metadata
• Use folders with trailing / for auto-discovery: api/
• Keep navigation flat and intuitive (2-3 levels maximum)

Forbidden Fields (Parent Repo Owns These)

DO NOT include in your stub mkdocs.yml:

• theme: - Megadoc parent defines the Material theme
• plugins: - Monorepo, search, and other plugins configured centrally
• markdown_extensions: - Extensions configured globally
• extra: - Global site extras defined in parent
• extra_css: - Custom CSS managed centrally
• extra_javascript: - Custom JS managed centrally

Why?: These settings are applied globally by the parent megadoc repo. Including them in your stub will have no effect or may cause conflicts.

The Monorepo Plugin and !include

How Your Docs Get Included

The parent ohemr-epic-megadoc repo uses the monorepo plugin to include your documentation:

# In parent megadoc mkdocs.yml
nav:
  - Infrastructure:
      - Terraform Modules:
          - Your Module: '!include submodules/your-repo-name/mkdocs.yml'

What happens:

1. Megadoc loads your mkdocs.yml stub
2. Monorepo plugin merges your navigation into the parent site
3. Your docs/ folder becomes part of the unified site
4. "Edit on GitHub" links point back to your repository

Wildcard Inclusions

Powerful pattern - one line includes dozens of repos:

# Includes ALL repos matching pattern
- Ansible Roles: '*include submodules/ohemr-ansible-role-*/mkdocs.yml'

This creates a menu tree from:

• ohemr-ansible-role-base-os-config/mkdocs.yml
• ohemr-ansible-role-application-and-agents/mkdocs.yml
• ohemr-ansible-role-security-compliance/mkdocs.yml
• ... (all matching repos)

Result: 100 repos = 1 configuration line. This is the power of the monorepo pattern.

Required Documentation Structure

Minimal Structure

your-repo/
├── mkdocs.yml              # Stub configuration (required)
├── docs/
│   └── index.md            # Landing page (required)
├── README.md               # GitHub landing page
├── CHANGELOG.md            # Version history
└── CONTRIBUTING.md         # Contribution guide

Recommended Structure

your-repo/
├── mkdocs.yml
├── docs/
│   ├── index.md                    # Overview and quick start
│   ├── getting-started.md          # Installation and setup
│   ├── architecture.md             # Design and structure
│   ├── how-to/                     # Task-oriented guides
│   │   ├── deploy.md
│   │   ├── configure.md
│   │   └── troubleshoot.md
│   ├── reference/                  # API docs, schema, config
│   │   ├── api.md
│   │   ├── configuration.md
│   │   └── schema.md
│   └── runbooks/                   # Operational procedures
│       ├── incident-response.md
│       └── maintenance.md
├── README.md
├── CHANGELOG.md
└── CONTRIBUTING.md

Front Matter Requirements

Every markdown file must start with YAML front matter:

---
title: Page Title Here
description: Brief description of this page's content
owner: team-name or github-username
doc_type: how-to # or: reference, runbook, concept
lifecycle_status: active # or: experimental, deprecated
last_reviewed: 2025-12-18
tags:
  - tag1
  - tag2
  - tag3
---
# Page Title Here

Content starts here...

Field Descriptions:

• title: Page title (used in navigation and search)
• description: One-sentence summary (used in search results)
• owner: Team or person responsible for maintaining this page
• doc_type: Diátaxis category (how-to, reference, runbook, concept)
• lifecycle_status: Current state (active, experimental, deprecated)
• last_reviewed: Last time content was verified accurate (YYYY-MM-DD)
• tags: Keywords for search and categorization

Diátaxis Framework

Organize documentation using the Diátaxis framework:

How-To Guides (Task-Oriented)

Purpose: Achieve a specific goal Location: docs/how-to/ Example: "How to deploy your application", "How to configure authentication"

---
title: How to deploy application X
doc_type: how-to
---

## Prerequisites

- Requirement 1
- Requirement 2

## Steps

### 1. Prepare environment

...

### 2. Deploy application

...

## Verification

...

Reference (Information-Oriented)

Purpose: Lookup technical details Location: docs/reference/ Example: "API documentation", "Configuration schema", "CLI commands"

---
title: Configuration reference
doc_type: reference
---

## Configuration Options

### `option_name`

- **Type**: string
- **Required**: yes
- **Default**: none
- **Description**: ...

Runbooks (Procedural)

Purpose: Execute operational procedures Location: docs/runbooks/ Example: "Incident response", "Backup and restore", "Scaling procedures"

---
title: Incident response runbook
doc_type: runbook
---

## When to Use

- Symptom 1
- Symptom 2

## Diagnosis Steps

1. Check X
2. Verify Y

## Resolution

...

Concepts (Understanding-Oriented)

Purpose: Explain architecture and design Location: docs/ or docs/concepts/ Example: "Architecture overview", "Design principles"

---
title: System architecture
doc_type: concept
---

## Overview

High-level explanation of system design

## Components

...

## Data Flow

...

Style Guide

Headings

• Use sentence case: "Getting started" not "Getting Started"
• Keep focused: One concept per section
• Be specific: "Configure OAuth authentication" not "Setup"
• Maximum 3 levels: #, ##, ### (avoid #### and deeper)

Code Blocks

Always annotate with language:

```bash
# Good - syntax highlighted
terraform init
```

```
# Bad - no highlighting
terraform init
```

Supported languages: bash, yaml, python, terraform, javascript, json, sql, markdown

Links

Prefer relative links:

[Configuration guide](./reference/configuration.md) ✅
[Configuration guide](/docs/reference/configuration.md) ❌ (breaks in submodule)

External links open in new tab (if your markdown processor supports it):

[External Tool](https://example.com){:target="\_blank"}

Lists

Use parallel structure:

✅ Good:

- Configure authentication
- Deploy application
- Verify deployment

❌ Bad:

- Configure authentication
- Application deployment
- Verify that the deployment worked

Admonitions (Callouts)

Use Material theme admonitions:

!!! note
Informational callout

!!! warning
Important caution

!!! danger
Critical warning - risk of data loss

!!! tip
Helpful suggestion

!!! example
Code example or demonstration

Validation Before Submission

Local Testing

# Install mkdocs
pip install mkdocs mkdocs-material

# Serve locally (in your repo root)
mkdocs serve

# Visit http://localhost:8000

What to check:

• All pages render correctly
• Navigation structure makes sense
• Links work (no 404s)
• Code blocks have syntax highlighting
• Front matter is valid YAML

Megadoc Integration Testing

Test in megadoc context (after your PR is merged):

1. Clone megadoc repo
2. Update submodule: git submodule update --remote submodules/your-repo
3. Build site: mkdocs build
4. Check navigation tree includes your docs
5. Verify "Edit on GitHub" links point to your repo

Common Issues

Docs don't appear in megadoc:

• Check mkdocs.yml has required fields (site_name, repo_url, etc.)
• Verify docs/index.md exists
• Ensure no YAML syntax errors in mkdocs.yml
• Check megadoc parent includes your submodule

Edit links broken:

• Verify edit_uri points to correct branch/path
• Standard format: edit/main/docs or edit/develop/docs

Navigation messy:

• Define explicit nav: in your stub mkdocs.yml
• Keep navigation flat (2-3 levels max)
• Use descriptive navigation labels

Fallback Mechanism

If your repository lacks proper documentation, megadoc auto-generates a fallback:

• Location: .megadoc/fallbacks/your-repo-name/
• Contents: Minimal stub mkdocs.yml and placeholder docs
• Purpose: Prevent build failures, show placeholder in navigation

Fallbacks indicate missing documentation:

• A GitHub issue will be created in your repo
• The issue provides setup instructions
• Once you add proper docs, fallback is automatically ignored

Goal: Avoid fallbacks by adding proper documentation from the start.

Consistency is Key

Why consistency matters:

• Users navigate between repositories seamlessly
• Search results are predictable
• Maintenance burden reduced (everyone follows same patterns)
• New contributors onboard faster

Consistency checklist:

• ✅ Front matter on every page
• ✅ Diátaxis categorization followed
• ✅ Style guide adhered to
• ✅ Links validated
• ✅ Code blocks annotated
• ✅ Navigation structure intuitive

Getting Help

Resources:

• Megadoc repo: ohemr-epic-megadoc
• Megadoc maintainers: @epic-platform-sre
• MkDocs documentation: https://www.mkdocs.org
• Material theme: https://squidfunk.github.io/mkdocs-material
• Diátaxis framework: https://diataxis.fr

Common questions:

• Q: Can I use custom plugins in my stub?
  • A: No - plugins are configured in parent megadoc repo
• Q: How do I add custom CSS?
  • A: Request it in megadoc repo (applied globally)
• Q: Why isn't my nav structure showing up?
  • A: Ensure your stub mkdocs.yml defines nav: section
• Q: Can I test locally with megadoc theme?
  • A: Yes - clone megadoc, update submodule, build full site

Summary

Your submodule repository provides:

1. Stub mkdocs.yml with site metadata + optional navigation
2. docs/ folder with markdown content
3. Front matter on every page
4. Diátaxis-organized structure
5. Consistent style and formatting

Megadoc parent repository provides:

1. Unified theme and styling
2. All plugins (monorepo, search, etc.)
3. Global navigation structure
4. Build and deployment pipeline
5. !include integration of your docs

Result: One unified documentation site with consistent experience across 100+ repositories.