How the DeepWiki Export Feature Generates Markdown and JSON Wiki Files

The DeepWiki export feature converts collections of wiki pages into downloadable Markdown or JSON files via a FastAPI endpoint that assembles documents with metadata, tables of contents, and cross-references.

The DeepWiki export feature in the AsyncFuncAI/deepwiki-open repository enables users to transform generated wiki documentation into portable file formats. This functionality is implemented in the FastAPI server and supports both human-readable Markdown and machine-parseable JSON outputs. Understanding how this feature processes repository data and assembles export files helps developers integrate DeepWiki into their documentation workflows.

FastAPI Endpoint Architecture for DeepWiki Export

Request Validation with WikiExportRequest

The export process begins with the WikiExportRequest Pydantic model defined in api/api.py. This model validates the incoming POST /export/wiki request payload to ensure it contains the required fields: repo_url (string), pages (list of WikiPage objects), and format (enum of "markdown" or "json").

The export_wiki Route Handler

The export_wiki function in api/api.py handles the POST /export/wiki endpoint. This handler extracts the repository name from the URL, creates a timestamped filename using the current UTC time, and dispatches to the proper generator based on the requested format. It returns a FastAPI Response object with Content-Disposition: attachment headers to trigger browser downloads.

Markdown Export Generation Process

Document Structure and Metadata

The generate_markdown_export function in api/api.py constructs a comprehensive Markdown document starting with a header containing the repository URL and generation timestamp. It iterates through the pages list to build a structured document that preserves the wiki hierarchy and content.

Table of Contents and Cross-References

For each page in the export, the generator creates HTML anchor tags (<a id='...'>) to enable internal navigation. The function builds a table of contents using standard Markdown links to these anchors. It also resolves the relatedPages field by mapping page IDs to their corresponding titles, creating a "Related Pages" section that maintains bidirectional links between documentation entries. Each page section concludes with a horizontal rule (---) to visually separate content.

JSON Export Generation Process

Metadata and Schema Design

The generate_json_export function in api/api.py produces a structured JSON object containing two top-level keys: metadata and pages. The metadata object includes the repository URL, an ISO-8601 formatted generation timestamp, and the total page count, providing essential context for downstream consumers.

Serialization with Pydantic

The function serializes the WikiPage objects using Pydantic's model_dump() method, which converts the models to dictionaries while preserving type information. The resulting JSON is pretty-printed with json.dumps(..., indent=2) to ensure human readability while maintaining machine-parseable structure. This format is ideal for importing wiki data into content management systems or documentation platforms.

Practical Usage Examples

Exporting Markdown via cURL

You can trigger a Markdown export using a standard HTTP POST request. The following cURL command sends the repository URL and wiki pages to the endpoint and saves the response as a timestamped file:

curl -X POST https://<your-deepwiki-host>/export/wiki \
  -H "Content-Type: application/json" \
  -d '{
        "repo_url": "https://github.com/example/repo",
        "pages": [
          {
            "id": "intro",
            "title": "Introduction",
            "content": "Welcome to the repo...",
            "filePaths": ["README.md"],
            "importance": "high",
            "relatedPages": ["setup"]
          },
          {
            "id": "setup",
            "title": "Setup Guide",
            "content": "Installation steps...",
            "filePaths": ["docs/setup.md"],
            "importance": "medium",
            "relatedPages": ["intro"]
          }
        ],
        "format": "markdown"
      }' \
  --output repo_wiki_$(date +%Y%m%d_%H%M%S).md

Exporting JSON via Python Requests

For programmatic integration, use Python's requests library to retrieve structured JSON data. This approach is useful for importing wiki content into databases or documentation platforms:

import requests
import json

payload = {
    "repo_url": "https://github.com/example/repo",
    "pages": [
        {
            "id": "intro",
            "title": "Introduction",
            "content": "Welcome to the repo...",
            "filePaths": ["README.md"],
            "importance": "high",
            "relatedPages": ["setup"]
        }
    ],
    "format": "json"
}

resp = requests.post(
    "https://<your-deepwiki-host>/export/wiki",
    json=payload,
    headers={"Accept": "application/json"}
)

resp.raise_for_status()
export_data = resp.json()
print(json.dumps(export_data, indent=2))

Programmatic Integration

You can also import the generator functions directly from api/api.py for use in custom workflows without making HTTP requests:

from api.api import generate_markdown_export, generate_json_export, WikiPage

pages = [
    WikiPage(
        id="intro",
        title="Introduction",
        content="Welcome...",
        filePaths=["README.md"],
        importance="high",
        relatedPages=["setup"]
    )
]

md_output = generate_markdown_export("https://github.com/example/repo", pages)
json_output = generate_json_export("https://github.com/example/repo", pages)

Summary

• The DeepWiki export feature processes POST /export/wiki requests through the FastAPI server in api/api.py, validating input with the WikiExportRequest Pydantic model.
• Markdown export generates a single document with metadata headers, HTML anchors for navigation, a table of contents, and resolved cross-references between related pages.
• JSON export produces a structured object with repository metadata including ISO-8601 timestamps and serialized WikiPage data using Pydantic's model_dump() method.
• Both formats support direct download via HTTP Content-Disposition: attachment headers and can be invoked via cURL, Python requests, or direct function imports.

Frequently Asked Questions

What endpoint handles the DeepWiki export feature?

The POST /export/wiki endpoint in api/api.py handles all export requests. It accepts a JSON payload containing the repository URL, wiki pages, and desired format, then returns the generated file as a downloadable attachment using Content-Disposition headers.

How does the Markdown export create internal navigation links?

The generate_markdown_export function creates HTML anchor tags (<a id='...'>) for each page and builds a table of contents using standard Markdown links to these anchors. It also resolves the relatedPages field to create bidirectional links between related documentation sections.

Can I use the export generators without running the HTTP server?

Yes, you can import generate_markdown_export and generate_json_export directly from api/api.py along with the WikiPage model. This allows you to generate export files programmatically within Python scripts without making HTTP requests to the FastAPI server.

What metadata is included in the JSON export format?

The JSON export includes a metadata object containing the repository URL, an ISO-8601 formatted generation timestamp, and the total page count. The pages array contains the serialized WikiPage objects with all fields preserved for programmatic consumption.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}