Local Development
Prerequisites
- Python 3.x and
pip - Node.js and pnpm (for working on aggregator/webhook components)
- Git
Setting Up MkDocs Locally
1. Clone the Repository
git clone git@github.com:statista/docs-builder.git
cd docs-builder
2. Install Python Dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e . # Install the custom lenient_builder plugin
3. Add Documentation Content
The aggregator requires GitHub App credentials to pull docs from all repositories automatically. For local development, you can manually clone the repositories you want to work with:
# Navigate to the docs directory
cd docs
# Clone the repository you want to preview (maintaining the org structure)
mkdir -p <org-name>
cd <org-name>
git clone <repo-url>
4. Serve the Site Locally
# From the root of docs-builder
source venv/bin/activate # if not already activated
mkdocs serve
Visit http://localhost:8000 to see your local documentation site.
Changes to markdown files will automatically reload in the browser.
Working on Components
The system consists of five main components, each with different development workflows:
- Aggregator - TypeScript tool that pulls
/docsfolders from GitHub repositories - Docs Rebuilder - Lambda function that runs the full rebuild pipeline (aggregate → build → deploy)
- Webhook Handler - Lambda function that receives and processes GitHub webhook events
- CDK Infrastructure - AWS CDK stack that deploys all infrastructure resources
- MkDocs Plugins - Custom Python plugins that extend MkDocs functionality
See the individual component pages for specific development instructions.