GitHub Action

Loading…

GitHub Action

Relevant source files

• README.md
• action.yml

This page documents the reusable GitHub Action that enables external repositories to generate mdBook documentation from DeepWiki content. The action packages the entire Docker-based build system into a single workflow step that can be invoked with YAML configuration. For information about the automated build-and-deploy workflow used in this repository itself, see Build and Deploy Workflow. For information about the test workflow, see Test Workflow.

Overview

The GitHub Action is defined in action.yml:1-53 and implements a composite action pattern. It builds the Docker image on-demand within the calling workflow’s runner environment, executes the documentation generation process, and outputs artifacts to a configurable directory. Unlike pre-built action images, this approach bundles the Dockerfile directly, ensuring that the action always uses the exact code version referenced in the workflow.

graph TB
    subgraph "Calling Repository Workflow"
        WorkflowYAML["workflow.yml\nuses: jzombie/deepwiki-to-mdbook@main"]
InputParams["Input Parameters\nrepo, book_title, output_dir, etc."]
end
    
    subgraph "action.yml Composite Steps"
        Step1["Step 1: Build Docker image\nworking-directory: github.action_path"]
Step2["Step 2: Run documentation builder\ndocker run with mounted volume"]
end
    
    subgraph "Execution Environment"
        Dockerfile["Dockerfile\nbundled with action"]
ImageTag["IMAGE_TAG=deepwiki-to-mdbook:GITHUB_RUN_ID"]
Container["Docker Container\nbuild-docs.sh entrypoint"]
end
    
    subgraph "Output Artifacts"
        OutputDir["inputs.output_dir\nmounted to /output"]
Book["book/\nHTML documentation"]
Markdown["markdown/\nenhanced markdown"]
Config["book.toml\nmdBook config"]
end
    
 
   WorkflowYAML --> InputParams
 
   InputParams --> Step1
 
   Step1 --> Dockerfile
 
   Dockerfile --> ImageTag
 
   ImageTag --> Step2
 
   Step2 --> Container
 
   Container --> OutputDir
 
   OutputDir --> Book
 
   OutputDir --> Markdown
 
   OutputDir --> Config

The action provides the same functionality as local Docker execution but wraps it in a GitHub Actions-native interface with declarative input parameters instead of raw environment variables and shell commands.

Diagram: Action Invocation and Execution Flow

The action uses the github.action_path context variable to locate the bundled Dockerfile within the checked-out action repository. The image tag includes GITHUB_RUN_ID to ensure uniqueness across concurrent workflow executions.

Sources: action.yml:1-53 README.md:60-70

Input Parameters

The action exposes six input parameters that map directly to the Docker container’s environment variables. All parameters except repo have sensible defaults.

The output_dir parameter is workflow-relative and resolved to an absolute path before mounting action.yml44 This allows callers to specify paths like ./docs-output or ${{ github.workspace }}/generated-docs.

Sources: action.yml:3-26

Action Implementation

The action uses the composite run type action.yml28 meaning it executes shell commands directly in the workflow runner rather than using a pre-built container image. This design choice enables the action to always use the current repository code without requiring separate image publication.

Diagram: Action Step Implementation Details

graph TB
    subgraph "Step 1: Build Docker image"
        ActionPath["github.action_path\nPoints to checked-out action repo"]
SetWorkDir["working-directory: github.action_path"]
BuildCmd["docker build -t IMAGE_TAG ."]
SetEnv["Export IMAGE_TAG to GITHUB_ENV"]
end
    
    subgraph "Step 2: Run documentation builder"
        MkdirOutput["mkdir -p inputs.output_dir"]
ResolveDir["OUT_DIR=$(cd inputs.output_dir && pwd)"]
DockerRun["docker run --rm"]
EnvVars["Environment Variables\nREPO, BOOK_TITLE, BOOK_AUTHORS\nGIT_REPO_URL, MARKDOWN_ONLY"]
VolumeMount["Volume: OUT_DIR:/output"]
end
    
    subgraph "Container Execution"
        Entrypoint["CMD: build-docs.sh"]
OutputGeneration["Generate book/, markdown/, etc."]
end
    
 
   ActionPath --> SetWorkDir
 
   SetWorkDir --> BuildCmd
 
   BuildCmd --> SetEnv
 
   SetEnv --> MkdirOutput
 
   MkdirOutput --> ResolveDir
 
   ResolveDir --> DockerRun
 
   DockerRun --> EnvVars
 
   DockerRun --> VolumeMount
 
   EnvVars --> Entrypoint
 
   VolumeMount --> Entrypoint
 
   Entrypoint --> OutputGeneration

The first step action.yml:30-37 uses working-directory: ${{ github.action_path }} to ensure docker build executes in the action’s repository root where the Dockerfile is located. The image tag incorporates GITHUB_RUN_ID action.yml35 to prevent conflicts when multiple workflows run concurrently. The tag is exported to $GITHUB_ENV action.yml36 to make it available in subsequent steps.

The second step action.yml:39-52 resolves the output_dir input to an absolute path action.yml44 using cd and pwd, which is necessary because Docker volume mounts require absolute paths. The docker run command action.yml:45-52 uses the same environment variable names as local Docker execution, mapping each input parameter to its corresponding environment variable.

Sources: action.yml:28-53

Usage Examples

Basic Usage

The most common usage pattern provides only the required repo parameter and accepts default values for all other inputs:

This generates documentation for the myorg/myproject DeepWiki repository with the default title “Documentation” and outputs to ./output.

Sources: README.md:62-70

Full Configuration

A fully configured invocation specifies all optional parameters:

This provides custom metadata and changes the output location to ./generated-docs.

Sources: action.yml:3-26

Markdown-Only Mode

To extract markdown without building HTML, useful for custom post-processing:

This skips the mdBook build phase and outputs only markdown/ and raw_markdown/ directories. For more information about markdown-only mode, see Markdown-Only Mode.

Sources: action.yml:19-22

GitHub Pages Deployment

The action integrates with GitHub Pages deployment workflows:

This workflow generates documentation weekly and deploys it to GitHub Pages. The ${{ github.repository }} context variable automatically uses the current repository as the target.

Sources: README.md:60-70

Comparison with Local Docker Usage

The GitHub Action provides the same functionality as direct Docker invocation but with different interfaces:

Both methods use the identical Docker image and build-docs.sh entrypoint, ensuring consistent output regardless of invocation method. The action adds automation conveniences like automatic image building and path resolution, while local Docker provides more direct control and faster iteration during development.

Sources: action.yml:28-53 README.md:14-27

Implementation Details

Composite Action Structure

The action uses the composite type action.yml28 rather than docker or javascript types. This design choice has several implications:

1. No Pre-built Images : The action does not publish Docker images to registries. Instead, it builds the image on-demand in each workflow run.
2. Version Consistency : Using @main or a specific commit SHA ensures the action always uses the corresponding Dockerfile version.
3. Build Caching : GitHub Actions runners cache Docker layers between runs, reducing build time after the initial execution.
4. Shell Portability : The action requires only bash and docker, making it compatible with all standard GitHub-hosted runners.

Sources: action.yml28

Environment Variable Mapping

The action translates workflow inputs to Docker environment variables using GitHub Actions expression syntax:

Each inputs.* reference is resolved by the Actions runtime before shell execution action.yml:46-51 Empty values are passed as empty strings, which triggers auto-detection behavior in build-docs.sh. For details about auto-detection features, see Auto-Detection Features.

Sources: action.yml:45-52

Working Directory Management

The action uses working-directory: ${{ github.action_path }} action.yml31 in the build step to ensure docker build executes in the action repository root. The github.action_path context variable points to the directory where the action was checked out, which is outside the calling workflow’s workspace.

In contrast, the second step does not specify a working directory, so it executes in ${{ github.workspace }} by default. This allows the output_dir input to use workflow-relative paths action.yml44

Sources: action.yml31 action.yml44

Common Integration Patterns

Multi-Repository Documentation

Organizations can use the action to generate documentation for multiple repositories in a single workflow:

This generates documentation for three repositories in parallel, each in its own output subdirectory.

Sources: action.yml:3-26

Conditional Builds

The action can be conditionally executed based on workflow triggers:

This only runs the documentation build when manually triggered, using a repository specified in the workflow dispatch inputs.

Sources: action.yml:1-53

Artifact Upload Integration

The action output integrates seamlessly with GitHub Actions artifact upload:

This uploads multiple output directories as a single artifact for later download or deployment.

Sources: README.md:54-58

Dismiss

Refresh this wiki

Enter email to refresh