---
title: "From Material for MkDocs"
description: "Migrate MkDocs Markdown, mkdocs.yml navigation, extensions, theme overrides, and plugins"
canonical_url: "https://docs.farming-labs.dev/docs/migrations/mkdocs"
markdown_url: "https://docs.farming-labs.dev/docs/migrations/mkdocs.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 1750
  task: "Migrate a Material for MkDocs site into Farming Labs Docs."
  outcome: "MkDocs pages, nav order, assets, code, and converted Python Markdown extensions render in a buildable Farming Labs Docs project."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "Preserve mkdocs.yml, docs, theme overrides, plugins, hooks, macros, includes, and dependency lock files."
    - "Record site_url, site_dir, use_directory_urls, nav, extra, and all Markdown extensions."
    - "Initialize the target runtime separately."
  files:
    - "mkdocs.yml"
    - "requirements.txt"
    - "pyproject.toml"
    - "docs.config.ts"
    - "docs.config.tsx"
  commands:
    - run: "npx @farming-labs/docs init"
      description: "Scaffold the selected Farming Labs target runtime."
  sideEffects:
    - "Python Markdown extensions, Jinja macros, hooks, and theme overrides may be rewritten as MDX or application components."
  verification:
    - description: "Build the target and compare mkdocs nav, routes, extensions, assets, macros, redirects, and search."
      expect: "Required routes resolve and no unconverted Python Markdown or Jinja syntax breaks MDX."
  rollback:
    - "Keep the MkDocs build and deployment available until route and extension verification passes."
  failureModes:
    - symptom: "Indented extension syntax renders as plain text."
      resolution: "Convert that Python Markdown extension family into supported Markdown or MDX across the corpus."
    - symptom: "A macro or plugin-generated page is missing."
      resolution: "Materialize its generated content or rebuild the behavior as an explicit target integration."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Migrate a Material for MkDocs site into Farming Labs Docs.
Outcome: MkDocs pages, nav order, assets, code, and converted Python Markdown extensions render in a buildable Farming Labs Docs project.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- Preserve mkdocs.yml, docs, theme overrides, plugins, hooks, macros, includes, and dependency lock files.
- Record site_url, site_dir, use_directory_urls, nav, extra, and all Markdown extensions.
- Initialize the target runtime separately.

### Files

- `mkdocs.yml`
- `requirements.txt`
- `pyproject.toml`
- `docs.config.ts`
- `docs.config.tsx`

### Commands

- `npx @farming-labs/docs init` — Scaffold the selected Farming Labs target runtime.

### Side Effects

- Python Markdown extensions, Jinja macros, hooks, and theme overrides may be rewritten as MDX or application components.

### Verification

- Build the target and compare mkdocs nav, routes, extensions, assets, macros, redirects, and search.
  - Expected: Required routes resolve and no unconverted Python Markdown or Jinja syntax breaks MDX.

### Rollback

- Keep the MkDocs build and deployment available until route and extension verification passes.

### Failure Modes

- Indented extension syntax renders as plain text. — Recovery: Convert that Python Markdown extension family into supported Markdown or MDX across the corpus.
- A macro or plugin-generated page is missing. — Recovery: Materialize its generated content or rebuild the behavior as an explicit target integration.
<!-- farming-labs:agent-contract:end -->

# From Material for MkDocs

## From Material for MkDocs task

Task: Migrate a Material for MkDocs site into Farming Labs Docs.

Expected result: MkDocs pages, nav order, assets, code, and converted Python Markdown extensions render in a buildable Farming Labs Docs project.

## From Material for MkDocs prerequisites

- Preserve mkdocs.yml, docs, theme overrides, plugins, hooks, macros, includes, and dependency lock files.
- Record site_url, site_dir, use_directory_urls, nav, extra, and all Markdown extensions.
- Initialize the target runtime separately.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From Material for MkDocs verification

- Build the target and compare mkdocs nav, routes, extensions, assets, macros, redirects, and search. Expected: Required routes resolve and no unconverted Python Markdown or Jinja syntax breaks MDX.
- Failure: Indented extension syntax renders as plain text.
- Recovery: Convert that Python Markdown extension family into supported Markdown or MDX across the corpus.
- Rollback: Keep the MkDocs build and deployment available until route and extension verification passes.

## From Material for MkDocs agent guidance

Treat mkdocs.yml and its inherited config as the migration source of truth. Inventory docs_dir,
site_url, use_directory_urls, nav, markdown_extensions, plugins, hooks, theme.custom_dir, extra_css,
and extra_javascript. Search content for every enabled syntax before converting files.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).