Fumadocs Framework: Python

URL: /docs/ui/python Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/python.mdx

Generate docs from Python

Inline: $c = \pm\sqrt{a^2 + b^2}$

Generate Docs

Install the Python command first, we need it to collect docs from your Python package.

pip install ./node_modules/fumadocs-python

Generate the docs as a JSON:

fumapy-generate your-package-name
# for example
fumapy-generate httpx

Use the following script to convert JSON into MDX:

import { rimraf } from "rimraf"
import * as Python from "fumadocs-python"
import * as fs from "node:fs/promises"

// output JSON file path
const jsonPath = "./httpx.json"

async function generate() {
    const out = "content/docs/(api)"
    // clean previous output
    await rimraf(out)

    const content = JSON.parse((await fs.readFile(jsonPath)).toString())
    const converted = Python.convert(content, {
        baseUrl: "/docs",
    })

    await Python.write(converted, {
        outDir: out,
    })
}

void generate()

MDX Components

Add the components.

import defaultMdxComponents from "fumadocs-ui/mdx"
import type { MDXComponents } from "mdx/types"
import * as Python from "fumadocs-python/components"

export function getMDXComponents(components?: MDXComponents): MDXComponents {
    return {
        ...defaultMdxComponents,
        ...Python,
        ...components,
    }
}

Add styles:

@import "tailwindcss";
@import "fumadocs-ui/css/neutral.css";
@import "fumadocs-ui/css/preset.css";
@import "fumadocs-python/preset.css";

Fumadocs Framework: Page Slugs & Page Tree

URL: /docs/ui/page-conventions Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/page-conventions.mdx

A shared convention for organizing your documents

This guide only applies for content sources that uses loader() API, such as Fumadocs MDX.

Overview

Fumadocs generates page slugs and page tree (sidebar items) from your content directory using loader(), the routing functionality will be handled by your React framework.

You can define folders and pages similar to file-system based routing.

File

For MDX & Markdown file, you can customise page information from frontmatter.

---
title: My Page
description: Best document ever
icon: HomeIcon
---

## Learn More

Fumadocs detects from the following properties to construct page trees.

Slugs

The slugs of a page are generated from its file path.

Folder

Organize multiple pages, you can create a Meta file to customise folders.

Folder Group

By default, putting a file into folder will change its slugs. You can wrap the folder name in parentheses to avoid impacting the slugs of child files.

Root Folder

Marks the folder as a root folder, only items in the opened root folder will be visible.

{
    "title": "Name of Folder",
    "description": "The description of root folder (optional)",
    "root": true
}

For example, when you are opening root folder framework, the other folders (e.g. headless) are not shown on the sidebar and other navigation elements.

Meta

Customise folders by creating a meta.json file in the folder.

{
    "title": "Display Name",
    "icon": "MyIcon",
    "pages": ["index", "getting-started"],
    "defaultOpen": true
}

Pages

Folder items are sorted alphabetically by default, you can add or control the order of items using pages.

{
    "pages": ["index", "getting-started"]
}

When specified, items are not included unless they are listed in pages.

{
    "pages": ["components", "---My Separator---", "...folder", "...", "!file", "!otherFolder", "[Vercel](https://vercel.com)", "[Triangle][Vercel](https://vercel.com)"]
}

Icons

Since Fumadocs doesn't include an icon library, you have to convert the icon names to JSX elements in runtime, and render it as a component.

You can add an icon handler to loader().

i18n Routing

You can define different style for i18n routing.

import type { I18nConfig } from "fumadocs-core/i18n"

export const i18n: I18nConfig = {
    // default
    parser: "dot",
    // or
    parser: "dir",
}