# Dash Documentation Boilerplate

> A modern, markdown-driven documentation system for Dash applications built on Dash Mantine Components, with first-class AI/LLM and SEO integration via dash-improve-my-llms 2.0.

![logo](assets/intro_img.jpg)

> **A modern, responsive documentation system for Dash applications built with Dash Mantine Components**

Create beautiful, interactive documentation for your Dash components, data science workflows, and applications with markdown-driven content, live code examples, and automatic theme persistence.

---

## What is This?

The Dash Documentation Boilerplate is a **production-ready framework** for creating professional documentation sites for your Dash projects. Whether you're documenting a component library, showcasing data visualizations, or building a comprehensive application guide, this boilerplate provides everything you need.

### Built With Modern Technologies

- **Dash 4.1+** - Pluggable backends (Flask / FastAPI / Quart), MCP-aware
- **Dash Mantine Components 2.7+** - Beautiful, accessible UI components
- **Mantine 8.3+** - Modern React component library
- **React 18** - Latest React features
- **Python 3.11+** - Modern Python with type hints

---

## Key Features

### 📝 Markdown-Driven Documentation
Write your documentation in **markdown files** with full Python integration. The framework automatically discovers markdown files in the `docs/` directory and generates pages with:

- **Frontmatter metadata** for page configuration
- **Custom directives** for interactive examples
- **Automatic routing** based on your file structure
- **Table of contents** generation

### 🎨 Beautiful UI/UX
Built with Dash Mantine Components for a modern, professional look:

- **Responsive design** - Works beautifully on mobile, tablet, and desktop
- **Dark & Light themes** - Automatic theme persistence via localStorage
- **Smooth transitions** - Professional animations and interactions
- **Customizable** - Easy to theme with your brand colors
- **Accessible** - WCAG compliant components

### 🔧 Custom Directives
Powerful directives to enhance your documentation:

- `.. toc::` - Generate table of contents from headings
- `.. exec::module.path` - Embed interactive Python components
- `.. source::path/to/file.py` - Display source code with syntax highlighting
- `.. kwargs::ComponentName` - Auto-generate component props documentation

### 🤖 AI/LLM Integration
Powered by [dash-improve-my-llms](https://pypi.org/project/dash-improve-my-llms/) **2.0**:

- **`LLMS_DOC` pattern** — write a module-level prose string per page; the package serves it verbatim at `/<page>/llms.txt`
- **Multi-backend** — same surface under Flask, FastAPI, and Quart (auto-detected)
- **MCP bridge** — each page's prose registers as a `dash.mcp` resource on Dash 4.3+
- **SEO** — `/sitemap.xml` with priority inference, `/robots.txt` with bot-class policies
- **Bot management** — training crawlers blocked, search citations allowed, browsers untouched
- **Share with AI** — paste your URL into ChatGPT/Claude; they read the prose docs directly

### 🐋 Production Ready

- **Docker support** - Dockerfile and docker-compose included
- **Gunicorn server** - Production-ready WSGI server
- **Environment config** - Easy deployment configuration
- **Optimized builds** - Fast loading and rendering

---

## Quick Start

### 1. Installation

```bash
# Clone the repository
git clone https://github.com/pip-install-python/Dash-Documentation-Boilerplate.git
cd Dash-Documentation-Boilerplate

# Install Python dependencies
pip install -r requirements.txt

# Install Node dependencies (for Mantine components)
npm install
```

### 2. Run the Development Server

```bash
./scripts/dev.sh          # or: python run.py
```

Visit `http://localhost:8559` in your browser.

### 3. Create Your First Documentation Page

Create a new folder in `docs/` with a markdown file:

```markdown
---
name: My Component
description: Description of my awesome component
endpoint: /components/my-component
icon: mdi:code-tags
---

## My Component

Your documentation content here...

.. toc::

## Features

- Feature 1
- Feature 2
```

That's it! Your page will automatically appear in the navigation.

---

## Example Documentation

This site includes several example pages to demonstrate the capabilities:

- **Getting Started** - Learn how to create documentation pages
- **Custom Directives** - See all available directives in action
- **Interactive Components** - Examples of callbacks and state management
- **Data Visualization** - Plotly integration examples
- **AI Integration** - Showcase AI/LLM features

---

## Project Structure

```
dash-documentation-boilerplate/
├── assets/                      # Static assets and CSS
│   ├── m2d.css                 # Markdown-to-Dash styling
│   └── main.css                # Custom styles
│
├── components/                  # Reusable UI components
│   ├── appshell.py             # Main app layout
│   ├── header.py               # Header with search and theme toggle
│   └── navbar.py               # Navigation sidebar
│
├── docs/                        # Your documentation content
│   └── your-component/
│       ├── component.md        # Markdown documentation
│       └── examples.py         # Python interactive examples
│
├── lib/                         # Utility libraries
│   ├── constants.py            # App-wide constants
│   └── directives/             # Custom markdown directives
│       ├── kwargs.py           # Component props tables
│       ├── source.py           # Source code display
│       └── toc.py              # Table of contents
│
├── pages/                       # Dash multi-page app
│   ├── home.md                 # This home page
│   ├── home.py                 # Home page layout
│   └── markdown.py             # Dynamic markdown loader
│
├── scripts/                     # Post-deploy checks against a live site
├── tests/                       # pytest suite (all three backends)
├── .github/workflows/           # CI and CD
│
├── templates/
│   └── index.html              # Custom HTML template
│
├── CHANGELOG.md                # Version history
├── README.md                   # Full documentation
├── render.yaml                 # Render deployment blueprint
├── requirements.txt            # Python dependencies
├── package.json                # Node dependencies
├── Dockerfile                  # Docker container
└── run.py                      # Application entry point
```

---

## Customization

### Change Primary Color

Edit `lib/constants.py`:

```python
PRIMARY_COLOR = "teal"  # Change to any Mantine color
```

### Modify Styles

- `assets/main.css` - General application styling
- `assets/m2d.css` - Markdown-specific styling

### Configure AI/LLM Integration

Update `run.py` to configure bot management and SEO:

```python
from dash_improve_my_llms import RobotsConfig

app._base_url = "https://your-production-url.com"
app._robots_config = RobotsConfig(
    block_ai_training=True,
    allow_ai_search=True,
    crawl_delay=10
)
```

---

## Deployment

### Docker

```bash
# Build the image
docker build -t dash-docs-boilerplate .

# Run the container
docker run -p 8550:8550 dash-docs-boilerplate
```

### Docker Compose

```bash
docker-compose up
```

Visit `http://localhost:8550`

---

## Resources

- **GitHub Repository**: [Dash-Documentation-Boilerplate](https://github.com/pip-install-python/Dash-Documentation-Boilerplate)
- **Full Documentation**: See [README.md](https://github.com/pip-install-python/Dash-Documentation-Boilerplate/blob/main/README.md)
- **Changelog**: [CHANGELOG.md](https://github.com/pip-install-python/Dash-Documentation-Boilerplate/blob/main/CHANGELOG.md)
- **AI Integration Guide**: [AI/LLM Integration](/examples/ai-integration)
- **Multi-Site Networks**: [Wiring a family of documentation sites together](/networks)

### Community

- **GitHub**: [@pip-install-python](https://github.com/pip-install-python) ![GitHub](https://img.shields.io/github/followers/pip-install-python?style=social)
- **YouTube**: [2plot.ai](https://www.youtube.com/@2plotai?sub_confirmation=1) — build-alongs and component walkthroughs

---

## License

MIT License - see [LICENSE](https://github.com/pip-install-python/Dash-Documentation-Boilerplate/blob/main/LICENSE) for details.

---

**Ready to start?** Check out the example documentation pages to see what you can build!

## Pages

Every page in this application. Each has a Markdown version at the `llms.txt` URL beside it.

- [Dash Documentation Boilerplate](https://boilerplate.2plot.dev/): A modern, markdown-driven documentation system for Dash applications built on Dash Mantine Components, with first-class AI/LLM and SEO integration via dash-improve-my-llms 2.0.
  - Machine-readable: https://boilerplate.2plot.dev/llms.txt
- [Authentication](https://boilerplate.2plot.dev/authentication): Gate documentation pages with Clerk — as a standalone site, or as one satellite in a network of documentation sites
  - Machine-readable: https://boilerplate.2plot.dev/authentication/llms.txt
- [Backend Deep Dive](https://boilerplate.2plot.dev/backend-comparison): An in-depth comparison of Flask, FastAPI and Quart as Dash 4.x backends — architecture, strengths, weaknesses, deployment, and concrete best practices for each.
  - Machine-readable: https://boilerplate.2plot.dev/backend-comparison/llms.txt
- [Pluggable Backends](https://boilerplate.2plot.dev/backends): Run this documentation site on Flask, FastAPI or Quart with one environment variable, and learn what each backend unlocks.
  - Machine-readable: https://boilerplate.2plot.dev/backends/llms.txt
- [AI/LLM Integration](https://boilerplate.2plot.dev/examples/ai-integration): Make your Dash app discoverable to MCP clients, web crawlers, and paste-into-chat users with dash-improve-my-llms 2.0
  - Machine-readable: https://boilerplate.2plot.dev/examples/ai-integration/llms.txt
- [Custom Directives](https://boilerplate.2plot.dev/examples/directives): Comprehensive guide to all custom markdown directives available
  - Machine-readable: https://boilerplate.2plot.dev/examples/directives/llms.txt
- [Interactive .md](https://boilerplate.2plot.dev/examples/interactive): Advanced callback patterns and state management examples
  - Machine-readable: https://boilerplate.2plot.dev/examples/interactive/llms.txt
- [Data Visualization](https://boilerplate.2plot.dev/examples/visualization): Interactive charts and graphs with Plotly integration
  - Machine-readable: https://boilerplate.2plot.dev/examples/visualization/llms.txt
- [FastAPI Showcase](https://boilerplate.2plot.dev/fastapi-showcase): What the FastAPI backend unlocks in this boilerplate — OpenAPI docs, a native JSON API, ASGI middleware, and a path to MCP.
  - Machine-readable: https://boilerplate.2plot.dev/fastapi-showcase/llms.txt
- [Getting Started](https://boilerplate.2plot.dev/getting-started): Learn how to create documentation pages with markdown and Python
  - Machine-readable: https://boilerplate.2plot.dev/getting-started/llms.txt
- [Multi-Site Networks](https://boilerplate.2plot.dev/networks): Wire a family of separately-hosted documentation sites together so search engines and AI agents can see them as one ecosystem
  - Machine-readable: https://boilerplate.2plot.dev/networks/llms.txt

## About The 2plot network

Open-source Dash component libraries by Pip Install Python. Each component has its own documentation site and its own llms.txt; 2plot.dev indexes all of them, and 2plot.ai is the hub.

Network index: [https://2plot.dev](https://2plot.dev/llms.txt)

## Network

Other applications in this network. Same operator; each one serves its own `/llms.txt` in this format.

- [2plot.ai](https://2plot.ai): Network hub and account origin.
  - Machine-readable: https://2plot.ai/llms.txt
- [2plot.dev](https://2plot.dev): Package index for every open-source component in the network.
  - Machine-readable: https://2plot.dev/llms.txt
- [dash-leaflet2](https://leaflet.2plot.dev): Leaflet 2 maps as Dash components.
  - Machine-readable: https://leaflet.2plot.dev/llms.txt
- [dash-mui-scheduler](https://muischeduler.2plot.dev): MUI X Scheduler — calendars and event scheduling for Dash.
  - Machine-readable: https://muischeduler.2plot.dev/llms.txt
- [dash-flows](https://flows.2plot.dev): Node-graph editors built on React Flow.
  - Machine-readable: https://flows.2plot.dev/llms.txt
- [dash-pannellum](https://pannellum.2plot.dev): 360° panorama and virtual-tour viewer.
  - Machine-readable: https://pannellum.2plot.dev/llms.txt
- [dash-emoji-mart](https://emojimart.2plot.dev): Emoji picker component.
  - Machine-readable: https://emojimart.2plot.dev/llms.txt
- [dash-email](https://email.2plot.dev): Email composition and delivery components.
  - Machine-readable: https://email.2plot.dev/llms.txt

## Related projects

Projects by the same author on their own domains. Built on the same stack, but not part of the primary network.

- [Pip Install Python](https://pip-install-python.com): The original component documentation site.
  - Machine-readable: https://pip-install-python.com/llms.txt
- [Pirate's Bargain](https://piratesbargain.com): Deal aggregator built on the same Dash stack.
  - Machine-readable: https://piratesbargain.com/llms.txt
- [ai-agent.buzz](https://ai-agent.buzz): Agent tooling directory.
  - Machine-readable: https://ai-agent.buzz/llms.txt

## External references

Third-party documentation this project depends on or references. Not affiliated — listed so an agent can follow a dependency directly instead of searching for it.

- [Dash Mantine Components](https://www.dash-mantine-components.com): The UI component layer these docs are built with.
  - Machine-readable: https://www.dash-mantine-components.com/llms.txt
- [Plotly Dash documentation](https://dash.plotly.com): Upstream framework documentation.
  - Machine-readable: https://dash.plotly.com/llms.txt