MkDocs Integration

Sourcey imports existing MkDocs projects directly. Point a tab at mkdocs.yml and Sourcey reads the MkDocs configuration, resolves the same markdown files, and renders them as a normal markdown tab. There is no need to copy the sidebar structure into sourcey.config.ts by hand.

Note

Requires Sourcey 3.6.0 or later.

Configuration

Pass the path to your MkDocs config, relative to sourcey.config.ts:

import { defineConfig, mkdocs } from "sourcey";

export default defineConfig({
  navigation: {
    tabs: [
      {
        tab: "Documentation",
        slug: "",
        source: mkdocs("./mkdocs.yml"),
      },
    ],
  },
});

mkdocs({ config: "./mkdocs.yml" }) is the equivalent object form.

What gets ingested

MkDocs concept	How Sourcey handles it
`docs_dir`	Pages resolve relative to it (default `docs`)
`nav` (or legacy `pages`)	Top-level sections become sidebar groups; nested sections flatten into the group with `Parent / Child` labels
Explicit page labels	Preserved as sidebar labels
Snippet includes (`--8<-- "file.md"`)	Expanded inline at build time
Admonitions (`!!! note`, `??? tip`)	Converted to blockquotes with a bold title, including nested admonitions
Content tabs (`=== "Tab"`)	Flattened into sections with bold tab titles
Inline code language markers (`#!python ...`)	Stripped
Static assets under `docs_dir`	Images, CSS, JS, PDFs, and similar files are copied into the build output

Loose pages at the top level of nav collect into a "Pages" group. Entries that point at external URLs or anchors are skipped. If the config has no nav at all, Sourcey discovers every .md and .mdx file under docs_dir.

What gets ignored

Only docs_dir and nav (or pages) are read from mkdocs.yml. Theme settings, plugin configuration, and markdown extension options are ignored: Sourcey applies its own theme, search, and markdown pipeline. Python-specific YAML tags (!!python/name:, !ENV) are stripped before parsing so they do not break the import.

Dev server

sourcey dev watches both mkdocs.yml and the docs directory. Edits to either trigger a re-render.

Next steps

Navigation reference for how MkDocs groups map onto Sourcey navigation
Writing pages for the markdown features available once you author for Sourcey directly