Quick Start

Loading…

Quick Start

Relevant source files

• README.md

This page provides step-by-step instructions for basic usage of the DeepWiki-to-mdBook converter. It covers Docker image building, container execution with environment variables, output inspection, and local serving. For comprehensive configuration options, see Configuration Reference. For understanding the internal pipeline, see System Architecture.

Prerequisites

Before starting, ensure you have the following installed:

• Docker (version 20.10 or later)
• Git (for repository cloning)
• Python 3 (for local serving)

The system requires no additional dependencies on the host machine; all build tools and Python packages are contained within the Docker image.

Sources: README.md:1-95

Basic Workflow

The typical workflow involves three steps: building the Docker image, running the container to generate documentation, and serving the output locally for preview.

flowchart TD
    Start["User initiates workflow"]
Clone["Clone repository\ngit clone"]
Build["Build Docker image\ndocker build -t deepwiki-to-mdbook ."]
Run["Run container with config\ndocker run --rm -e REPO=... -v ..."]
subgraph Container["Docker Container Execution"]
BuildScript["build-docs.sh"]
Scraper["deepwiki-scraper.py"]
Process["process-template.py"]
MdBook["mdbook build"]
end
    
    Output["Output directory\n/output mounted volume"]
Serve["Serve locally\npython3 -m http.server"]
View["View in browser\nhttp://localhost:8000"]
Start --> Clone
 
   Clone --> Build
 
   Build --> Run
 
   Run --> Container
 
   Container --> BuildScript
 
   BuildScript --> Scraper
 
   BuildScript --> Process
 
   BuildScript --> MdBook
 
   MdBook --> Output
 
   Output --> Serve
 
   Serve --> View

Workflow Diagram

Sources: README.md:12-29

Step 1: Build the Docker Image

Navigate to the repository root and build the Docker image:

This command:

• Reads the multi-stage Dockerfile at the repository root
• Compiles mdbook and mdbook-mermaid from source in the Rust builder stage
• Installs Python 3.12 dependencies in the final stage
• Tags the resulting image as deepwiki-to-mdbook

The build process typically takes 5-10 minutes on the first run due to Rust compilation. Subsequent builds use Docker layer caching.

Sources: README.md:14-16

Step 2: Run the Container

Execute the container with required environment variables and a volume mount for output:

Environment Variable Configuration

The container accepts configuration exclusively through environment variables:

*The REPO variable is auto-detected if the container is run in a Git repository context. For manual execution, it should be explicitly provided.

Volume Mount

The -v "$(pwd)/output:/output" mount maps the host’s ./output directory to the container’s /output directory. All generated artifacts are written here.

Sources: README.md:18-27 README.md:31-51

Step 3: Serve and View Output

After the container completes execution, serve the generated HTML documentation locally:

This command:

• Changes to the output directory
• Starts Python’s built-in HTTP server
• Serves files from the book subdirectory
• Listens on port 8000

Open http://localhost:8000 in a web browser to view the searchable documentation.

Output Directory Structure

The container generates four output artifacts:

Directory Descriptions:

• book/ : The final HTML output generated by mdbook build. This is the directory to serve for viewing documentation.
• markdown/ : Enhanced markdown files after diagram injection and template processing. Contains the source files used by mdBook.
• raw_markdown/ : Markdown files immediately after HTML-to-markdown conversion, before diagram enhancement. Useful for debugging the extraction phase.
• book.toml : The mdBook configuration file generated from environment variables.

Sources: README.md:26-27 README.md:53-58

flowchart LR
    CMD["Container CMD\nbuild-docs.sh"]
subgraph Phase1["Phase 1: Extraction"]
Fetch["fetch_and_convert_to_markdown()\ndeepwiki-scraper.py"]
RawOut["raw_markdown/\ndirectory"]
end
    
    subgraph Phase2["Phase 2: Enhancement"]
Extract["extract_mermaid_from_nextjs_data()\ndeepwiki-scraper.py"]
Normalize["normalize_mermaid_diagram()\ndeepwiki-scraper.py"]
Inject["inject_mermaid_diagrams()\ndeepwiki-scraper.py"]
Templates["process-template.py\n--input templates/header.html"]
MdOut["markdown/\ndirectory"]
end
    
    subgraph Phase3["Phase 3: Build"]
Summary["generate_summary()\nbuild-docs.sh"]
BookInit["mdbook init\nbinary"]
BookBuild["mdbook build\nbinary"]
BookOut["book/\ndirectory"]
end
    
 
   CMD --> Fetch
 
   Fetch --> RawOut
 
   RawOut --> Extract
 
   Extract --> Normalize
 
   Normalize --> Inject
 
   Inject --> Templates
 
   Templates --> MdOut
 
   MdOut --> Summary
 
   Summary --> BookInit
 
   BookInit --> BookBuild
 
   BookBuild --> BookOut

Container Execution Flow

The following diagram maps the container’s internal execution to specific code entities:

This diagram shows the execution path through the three phases of the pipeline, with references to actual functions and binaries. The build-docs.sh script orchestrates all three phases sequentially. For detailed information on each phase, see Three-Phase Pipeline.

Sources: README.md:72-77

Common Usage Patterns

Pattern 1: Custom Book Title and Authors

Pattern 2: Markdown-Only Mode

Skip the HTML build to inspect or further process the markdown files:

The markdown/ directory will contain all enhanced markdown files, but the book/ directory will not be created. See Markdown-Only Mode for more details.

Pattern 3: Custom Templates

Provide custom header and footer templates by mounting a templates directory:

Your my-templates/ directory should contain header.html and/or footer.html. See Template System for template variable syntax and Custom Templates for a comprehensive guide.

Sources: README.md:39-51

Minimal Example

For a minimal working example with auto-detected repository:

The REPO variable is auto-detected from git remote get-url origin, and BOOK_AUTHORS defaults to the repository owner.

Sources: README.md:12-29 README.md34

Verification Steps

After running the container, verify successful execution:

1. Check container logs : The container should print progress messages for each phase.
2. Inspect output directory : Ensure all four artifacts exist (book/, markdown/, raw_markdown/, book.toml).
3. Verify HTML structure : book/index.html should exist and contain the search interface.
4. Test local serving : The HTTP server should start without errors.
5. Browse documentation : Navigate to http://localhost:8000 and verify page rendering and search functionality.

Next Steps

After completing the Quick Start:

• Customize configuration : See Configuration Reference for all environment variables and options.
• Understand the pipeline : See System Architecture for how the system transforms DeepWiki content.
• Use in CI/CD : See GitHub Action to integrate into automated workflows.
• Customize templates : See Template System Details to brand your documentation.

Sources: README.md:1-95

Dismiss

Refresh this wiki

Enter email to refresh