Skip to content

CLAUDE.md

Latest commit

 

History

History
133 lines (89 loc) · 5.89 KB

CLAUDE.md

File metadata and controls

133 lines (89 loc) · 5.89 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

OpenMetadata documentation site built with Mintlify. Multi-version docs for OpenMetadata (v1.12.x, v1.13.x, v2.0.x-SNAPSHOT). The default/current version is v1.12.x — unversioned URLs redirect there via docs.json redirects (~line 6425).

The sibling directory ../OpenMetadata contains the main OpenMetadata repo (JSON schemas in openmetadata-spec/ and ingestion source in ingestion/). The /connector-doc-review skill uses it to validate connector docs against ground truth.

Development Commands

npm i -g mint          # Install Mintlify CLI (requires Node.js >= 19)
mint dev               # Local preview at http://localhost:3000 (or: npm run dev)
mint dev --port 3333   # Custom port
mint broken-links      # Validate links across all pages (or: npm run broken-links)
mint update            # Update CLI to latest version

Deployment is automatic: push to main → deployed via Mintlify GitHub app.

Commit messages: prefix with Docs: and include PR number — Docs: Add release notes for 1.11.9 (#34)

Contributing Content

This section covers writing and editing documentation pages.

Page Frontmatter

Every page starts with YAML frontmatter:

---
title: "Page Title"
description: "SEO description"
sidebarTitle: "Short Nav Label"   # optional, for shorter sidebar text
mode: "wide"                      # optional, for full-width pages
---

File Naming

  • Kebab-case for files and directories (auto-classification.mdx)
  • .mdx for pages with JSX/component imports, .md for pure markdown
  • Images go in /public/images/ organized by category

Mintlify Components

Pages use MDX with built-in components: <Steps>, <Step>, <CardGroup>, <Card>, <Tip>, <Info>, <Warning>, <Accordion>, <AccordionGroup>, <Tabs>, <Tab>.

Snippets (Shared Content)

Reusable content lives in snippets/ and is imported via absolute paths:

import TestConnection from '/snippets/connectors/test-connection.mdx'
import DataProfiler from '/snippets/v1.11.x/connectors/yaml/data-profiler.mdx'

There are shared snippets (/snippets/connectors/) and version-specific snippets (/snippets/v1.11.x/, /snippets/v1.12.x/, /snippets/v1.13.x/). Version-specific snippets typically contain connectors-list.mdx (connector catalog per service type), related.mdx, data-profiler.mdx, and deployment snippets that differ between versions. Always import the snippet matching the page's version.

Connector Docs Pattern

Connector pages follow a consistent template:

  1. Import shared snippets and ConnectorDetailsHeader
  2. Render <ConnectorDetailsHeader> with features matrix
  3. Requirements section
  4. Metadata ingestion configuration
  5. Optional: Query Usage, Lineage, Data Profiler, Data Quality, dbt
  6. Troubleshooting

Registering New Pages

New pages must be added to docs.json in the appropriate navigation section, or they won't appear in the sidebar.

AI content review

When reviewing OpenMetadata documentation, release notes, UI copy, or other written content, use the AI-neutral workflow in .ai/doc-review/instructions.md and its checklist in .ai/doc-review/references/checklist.md. These instructions are shared across AI assistants and are not tied to Claude Code.

Pre-commit content review (Claude Code)

Before running git commit on any change touching .mdx files (or docs.json), read .ai/doc-review/instructions.md and .ai/doc-review/references/checklist.md, and review the staged diff against every applicable item — unless the changes were already reviewed against this checklist earlier in the same conversation. Show Critical and Major findings before committing; if Minor findings also exist, mention the count and offer to show them rather than listing them inline by default. Proceed with the commit only after the user has seen this and confirmed.

Changing the Site

This section covers the infrastructure: navigation, styling, components, and versioning.

Navigation Configuration

All navigation is defined in docs.json (very large file, ~6.5k lines). It defines:

  • Version tabs and page hierarchy per version (bulk of the file)
  • Redirects from unversioned paths to v1.12.x (starts at ~line 6425)
  • Footer, navbar, SEO, and theme settings

When editing docs.json, use targeted line-range reads rather than loading the whole file. Navigation groups are nested under navigation.versions[].tabs[].groups[].

Versioned Content Structure

Each version is a self-contained directory with identical structure:

v1.11.x/
  index.mdx              # Homepage
  quick-start/            # Getting started
  deployment/             # Docker, Kubernetes, Bare Metal
  connectors/             # database/, dashboard/, pipeline/, storage/, etc.
  how-to-guides/          # Feature walkthroughs
  sdk/                    # Python/Java SDK
  developers/             # Contributing
  api-reference/          # REST API docs

Custom React Components

JSX components in snippets/components/:

  • ConnectorDetailsHeader/ConnectorDetailsHeader.jsx — Feature support matrix for connectors (stage, available/unavailable features). Must appear in both the main connector page and its yaml.mdx with identical feature arrays.
  • MetadataIngestionUi.jsx — UI workflow screenshot sequences
  • CodePreview.jsx — Side-by-side code/content panels (used in yaml.mdx pages)
  • BreakingChanges/BreakingChanges.jsx — Breaking change callouts for release notes
  • VersionMatrix/VersionMatrix.jsx — Version compatibility matrix display

Styling

  • globals.css — CSS variables (colors, layout dimensions, fonts), Tailwind imports
  • style.css — Custom component styling and overrides
  • loader.js — Page loader animation
  • Theme is "aspen", primary color #6938EF