diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..48ba696
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,63 @@
+name: Documentation
+
+on:
+ push:
+ branches: [main, docs-site] # TODO: Remove docs-site before merging
+ pull_request:
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+concurrency:
+ group: "pages"
+ cancel-in-progress: false
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v6
+
+ - name: Set up Python
+ uses: actions/setup-python@v6
+ with:
+ python-version: '3.12'
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v7
+
+ - name: Install dependencies
+ run: |
+ uv sync
+ uv pip install -e ".[docs]"
+
+ - name: Verify docs templates have placeholders
+ run: uv run python docs/docs_gen.py --verify
+
+ - name: Generate docs content
+ run: uv run python docs/docs_gen.py --docs-only
+
+ - name: Build documentation
+ run: uv run zensical build
+
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v4
+ with:
+ path: ./site
+
+ deploy:
+ # TODO: Remove docs-site condition before merging
+ if: (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/docs-site') && github.event_name != 'pull_request'
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index a7578e5..15850c9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,3 +37,6 @@ ENV/
.env
.coverage
htmlcov/
+
+# Documentation build output
+site/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 430975c..205e25b 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -21,3 +21,11 @@ repos:
hooks:
- id: mypy
additional_dependencies: ["types-PyYAML", "types-requests", "types-setuptools"]
+ - repo: local
+ hooks:
+ - id: docs-placeholders
+ name: Verify docs templates have placeholders
+ entry: python docs/docs_gen.py --verify
+ language: python
+ pass_filenames: false
+ files: ^docs/.*\.md$
diff --git a/README.md b/README.md
index 6179382..4a04a7a 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,15 @@
+
`markdown-code-runner` is a Python package that automatically executes code blocks within a Markdown file, including hidden code blocks, and updates the output in-place.
This package is particularly useful for maintaining Markdown files with embedded code snippets, ensuring that the output displayed is up-to-date and accurate.
It also enables the generation of content such as tables, plots, and other visualizations directly from the code.
+
The package is hosted on GitHub: [https://github.com/basnijholt/markdown-code-runner](https://github.com/basnijholt/markdown-code-runner)
+
## :star: Features
- :rocket: Automatically execute code blocks, including hidden code blocks, within a Markdown file
- :eyes: Allows hidden code blocks (i.e., code blocks that are not displayed in the Markdown file) to generate content like tables, plots, etc.
@@ -16,7 +19,9 @@ The package is hosted on GitHub: [https://github.com/basnijholt/markdown-code-ru
- :octocat: Easily integrates with GitHub Actions
- :tada: No external dependencies and works with Python 3.7+
- :globe_with_meridians: Execute *all* languages by using the file code blocks and executing it with bash (see [Rust :crab: example](#crab-idea-6-run-a-rust-program))
+
+
## :question: Problem Statement
When creating Markdown files with code examples, it's essential to keep the output of these code snippets accurate and up-to-date.
@@ -25,6 +30,7 @@ In addition, there might be cases where hidden code blocks are needed to generat
`markdown-code-runner` solves this problem by automatically executing the code blocks, including hidden ones, within a Markdown file and updating the output in-place.
This ensures that the displayed output is always in sync with the code, and content generated by hidden code blocks is seamlessly integrated.
+
## :books: Table of Contents
@@ -50,6 +56,7 @@ This ensures that the displayed output is always in sync with the code, and cont
+
## :computer: Installation
Install `markdown-code-runner` via pip:
@@ -57,7 +64,9 @@ Install `markdown-code-runner` via pip:
```bash
pip install markdown-code-runner
```
+
+
## :rocket: Quick Start
To get started with `markdown-code-runner`, follow these steps:
@@ -126,7 +135,9 @@ To get started with `markdown-code-runner`, follow these steps:
```
3. The output of the code block will be automatically executed and inserted between the output markers.
+
+
## :snake: Python API
To use `markdown-code-runner`, simply import the `update_markdown_file` function from the package and call it with the path to your Markdown file:
@@ -136,7 +147,9 @@ from markdown_code_runner import update_markdown_file
update_markdown_file("path/to/your/markdown_file.md")
```
+
+
## :book: Examples
Here are a few examples demonstrating the usage of `markdown-code-runner`:
@@ -222,11 +235,14 @@ Hello again!
```
+
+
## :bulb: Usage Ideas
Markdown Code Runner can be used for various purposes, such as creating Markdown tables, generating visualizations, and showcasing code examples with live outputs. Here are some usage ideas to get you started:
+
### :gear: Idea 1: Continuous Integration with GitHub Actions
You can use `markdown-code-runner` to automatically update your Markdown files in a CI environment.
@@ -315,6 +331,7 @@ jobs:
3. Commit and push the workflow file to your repository. The workflow will now automatically run whenever you push changes to the `main` branch, updating your `README.md` with the latest outputs from your code blocks.
For more information on configuring GitHub Actions, check out the [official documentation](https://docs.github.com/en/actions/learn-github-actions/introduction-to-github-actions).
+
### :computer: Idea 2: Show command-line output
@@ -528,11 +545,15 @@ Hello, world!
These are just a few examples of how you can use Markdown Code Runner to enhance your Markdown documents with dynamic content. The possibilities are endless!
+
+
## :page_with_curl: License
`markdown-code-runner` is released under the [MIT License](https://opensource.org/licenses/MIT). Please include the LICENSE file when using this package in your project, and cite the original source.
+
+
## :handshake: Contributing
Contributions are welcome! To contribute, please follow these steps:
@@ -545,3 +566,4 @@ Contributions are welcome! To contribute, please follow these steps:
Please report any issues or bugs on the GitHub issue tracker: [https://github.com/basnijholt/markdown-code-runner/issues](https://github.com/basnijholt/markdown-code-runner/issues)
Thank you for your interest in `markdown-code-runner`!
+
diff --git a/docs/CNAME b/docs/CNAME
new file mode 100644
index 0000000..ec6a2cc
--- /dev/null
+++ b/docs/CNAME
@@ -0,0 +1 @@
+markdown-code-runner.nijho.lt
diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg
new file mode 100644
index 0000000..5ecc699
--- /dev/null
+++ b/docs/assets/logo.svg
@@ -0,0 +1,11 @@
+
+
+
+
+
+ MD
+ >_
+
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000..8d19379
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,73 @@
+---
+icon: lucide/git-pull-request
+---
+
+# Contributing
+
+
+
+
+
+
+ Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+
+
+## Development Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/basnijholt/markdown-code-runner.git
+cd markdown-code-runner
+```
+
+2. Create a virtual environment and install dependencies:
+
+```bash
+# Using uv (recommended)
+uv sync
+
+# Or using pip
+python -m venv venv
+source venv/bin/activate # On Windows: venv\Scripts\activate
+pip install -e ".[test]"
+```
+
+3. Run the tests:
+
+```bash
+pytest
+```
+
+4. Run pre-commit hooks:
+
+```bash
+pre-commit run --all-files
+```
+
+## Code Style
+
+This project uses:
+
+- **Ruff** for linting and formatting
+- **MyPy** for type checking
+- **pytest** for testing with 100% code coverage requirement
+
+## Pull Request Process
+
+1. Create a new branch for your changes
+2. Make your changes and add tests
+3. Ensure all tests pass: `pytest`
+4. Ensure pre-commit passes: `pre-commit run --all-files`
+5. Submit a pull request with a clear description
+
+## Reporting Issues
+
+Please report issues on the [GitHub issue tracker](https://github.com/basnijholt/markdown-code-runner/issues).
+
+Include:
+
+- A clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Your Python version and OS
diff --git a/docs/docs_gen.py b/docs/docs_gen.py
new file mode 100755
index 0000000..07288a7
--- /dev/null
+++ b/docs/docs_gen.py
@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+# ruff: noqa: T201, S603, S607
+"""Documentation generation utilities for Markdown Code Runner.
+
+Provides functions to extract sections from README.md and transform
+content for the documentation site. Docs templates are stored with
+placeholder OUTPUT sections and processed during CI build.
+
+Usage:
+ uv run python docs/docs_gen.py # Generate docs (process in-place)
+ uv run python docs/docs_gen.py --reset # Reset docs to templates (placeholders)
+ uv run python docs/docs_gen.py --verify # Verify docs have placeholders
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+# Path to README relative to this module (docs_gen.py is in docs/)
+_MODULE_DIR = Path(__file__).parent
+README_PATH = _MODULE_DIR.parent / "README.md"
+
+# Placeholder for OUTPUT sections in docs templates
+# The marker is checked by verify_placeholders() to ensure we don't commit generated content
+OUTPUT_PLACEHOLDER_MARKER = ""
+OUTPUT_PLACEHOLDER = (
+ f"{OUTPUT_PLACEHOLDER_MARKER} "
+ "Output is generated during CI build. We don't commit generated content "
+ "to keep docs copyable and avoid recursion. See docs/docs_gen.py"
+)
+
+
+def readme_section(section_name: str, *, strip_heading: bool = True) -> str:
+ """Extract a marked section from README.md.
+
+ Sections are marked with HTML comments:
+
+ content
+
+
+ Args:
+ section_name: The name of the section to extract
+ strip_heading: If True, remove the first heading from the section
+
+ Returns:
+ The content between the section markers
+
+ Raises:
+ ValueError: If the section is not found in README.md
+
+ """
+ content = README_PATH.read_text()
+
+ start_marker = f""
+ end_marker = f""
+
+ start_idx = content.find(start_marker)
+ if start_idx == -1:
+ msg = f"Section '{section_name}' not found in README.md"
+ raise ValueError(msg)
+
+ end_idx = content.find(end_marker, start_idx)
+ if end_idx == -1:
+ msg = f"End marker for section '{section_name}' not found"
+ raise ValueError(msg)
+
+ section = content[start_idx + len(start_marker) : end_idx].strip()
+
+ if strip_heading:
+ # Remove first heading (# or ## or ###)
+ section = re.sub(r"^#{1,3}\s+[^\n]+\n+", "", section, count=1)
+
+ return _transform_readme_links(section)
+
+
+def _transform_readme_links(content: str) -> str:
+ """Transform README internal links to docs site links."""
+ # Map README anchors to doc pages
+ link_map = {
+ "#computer-installation": "getting-started.md#installation",
+ "#rocket-quick-start": "getting-started.md#quick-start",
+ "#snake-python-api": "usage/python-api.md",
+ "#book-examples": "examples.md",
+ "#bulb-usage-ideas": "examples.md#usage-ideas",
+ "#gear-idea-1-continuous-integration-with-github-actions": "usage/github-actions.md",
+ "#page_with_curl-license": "index.md#license",
+ "#handshake-contributing": "contributing.md",
+ "#star-features": "index.md#features",
+ "#question-problem-statement": "index.md#why-use-markdown-code-runner",
+ }
+
+ for old_link, new_link in link_map.items():
+ content = content.replace(f"]({old_link})", f"]({new_link})")
+
+ # Remove ToC link pattern [[ToC](#...)]
+ return re.sub(r"\[\[ToC\]\([^)]+\)\]", "", content)
+
+
+def _find_markdown_files_with_code_blocks(docs_dir: Path) -> list[Path]:
+ """Find all markdown files containing markdown-code-runner markers."""
+ files_with_code = []
+ for md_file in docs_dir.rglob("*.md"):
+ content = md_file.read_text()
+ if "" in content:
+ files_with_code.append(md_file)
+ return sorted(files_with_code)
+
+
+def _run_markdown_code_runner(files: list[Path], repo_root: Path) -> bool:
+ """Run markdown-code-runner on all files. Returns True if all succeeded."""
+ if not files:
+ print("No files with CODE:START markers found.")
+ return True
+
+ print(f"Found {len(files)} file(s) with auto-generated content:")
+ for f in files:
+ print(f" - {f.relative_to(repo_root)}")
+ print()
+
+ # Set PYTHONPATH to include docs/ so this module is importable
+ env = os.environ.copy()
+ python_path = env.get("PYTHONPATH", "")
+ docs_dir = str(repo_root / "docs")
+ env["PYTHONPATH"] = f"{docs_dir}:{python_path}" if python_path else docs_dir
+
+ all_success = True
+ for file in files:
+ rel_path = file.relative_to(repo_root)
+ print(f"Updating {rel_path}...", end=" ", flush=True)
+ result = subprocess.run(
+ ["markdown-code-runner", str(file)],
+ check=False,
+ capture_output=True,
+ text=True,
+ env=env,
+ )
+ if result.returncode == 0:
+ print("OK")
+ else:
+ print("FAILED")
+ print(f" Error: {result.stderr}")
+ all_success = False
+
+ return all_success
+
+
+def reset_output_sections(file_path: Path) -> bool:
+ """Reset all OUTPUT sections in a file to contain only the placeholder.
+
+ Returns True if the file was modified.
+ """
+ content = file_path.read_text()
+ original = content
+
+ # Pattern to match OUTPUT sections and replace their content with placeholder
+ # Matches: \n...content...\n
+ pattern = re.compile(
+ r"()\n.*?\n()",
+ re.DOTALL,
+ )
+
+ replacement = rf"\1\n{OUTPUT_PLACEHOLDER}\n\2"
+ content = pattern.sub(replacement, content)
+
+ if content != original:
+ file_path.write_text(content)
+ return True
+ return False
+
+
+def verify_placeholders(file_path: Path) -> list[int]:
+ """Verify that all OUTPUT sections contain the placeholder.
+
+ Ignores OUTPUT markers inside fenced code blocks (examples).
+ Returns list of line numbers where violations occur.
+ """
+ content = file_path.read_text()
+ lines = content.split("\n")
+ violations = []
+
+ in_fence = False
+ in_output = False
+ output_start_line = 0
+
+ for i, line in enumerate(lines, 1):
+ # Track fence boundaries (``` or ~~~)
+ stripped = line.lstrip()
+ if stripped.startswith(("```", "~~~")):
+ in_fence = not in_fence
+ continue
+
+ # Skip content inside fences (code examples)
+ if in_fence:
+ continue
+
+ if "" in line:
+ in_output = True
+ output_start_line = i
+ elif "" in line:
+ in_output = False
+ elif in_output:
+ # Check if this is the placeholder line
+ if OUTPUT_PLACEHOLDER_MARKER in line:
+ continue
+ # Allow empty lines
+ if not line.strip():
+ continue
+ # Any other content is a violation
+ violations.append(output_start_line)
+ # Skip to end of this output section
+ in_output = False
+
+ return violations
+
+
+def cmd_generate(repo_root: Path, *, include_readme: bool = True) -> int:
+ """Generate docs by running markdown-code-runner on all files."""
+ files = _find_markdown_files_with_code_blocks(repo_root / "docs")
+
+ if include_readme:
+ readme = repo_root / "README.md"
+ if readme.exists() and "" in readme.read_text():
+ files.append(readme)
+
+ success = _run_markdown_code_runner(files, repo_root)
+ return 0 if success else 1
+
+
+def cmd_reset(repo_root: Path) -> int:
+ """Reset docs OUTPUT sections to placeholders."""
+ docs_dir = repo_root / "docs"
+ files = _find_markdown_files_with_code_blocks(docs_dir)
+
+ if not files:
+ print("No docs files with CODE:START markers found.")
+ return 0
+
+ print(f"Resetting {len(files)} file(s) to templates:")
+ modified_count = 0
+ for f in files:
+ rel_path = f.relative_to(repo_root)
+ if reset_output_sections(f):
+ print(f" ✓ {rel_path}")
+ modified_count += 1
+ else:
+ print(f" - {rel_path} (no changes)")
+
+ print(f"\nReset {modified_count} file(s) to templates.")
+ return 0
+
+
+def cmd_verify(repo_root: Path) -> int:
+ """Verify docs have placeholders (no processed content committed)."""
+ docs_dir = repo_root / "docs"
+ files = _find_markdown_files_with_code_blocks(docs_dir)
+
+ if not files:
+ print("No docs files with CODE:START markers found.")
+ return 0
+
+ print(f"Verifying {len(files)} docs file(s) have placeholders...")
+ all_valid = True
+
+ for f in files:
+ rel_path = f.relative_to(repo_root)
+ violations = verify_placeholders(f)
+ if violations:
+ print(f" ✗ {rel_path}: OUTPUT sections at lines {violations} have content")
+ all_valid = False
+ else:
+ print(f" ✓ {rel_path}")
+
+ if all_valid:
+ print("\nAll docs files have placeholder OUTPUT sections.")
+ return 0
+ print("\nError: Some docs files have processed content.")
+ print("Run 'uv run python docs/docs_gen.py --reset' to fix.")
+ return 1
+
+
+def main() -> int:
+ """Main entry point with subcommands."""
+ parser = argparse.ArgumentParser(
+ description="Documentation generation utilities for Markdown Code Runner.",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""
+Examples:
+ uv run python docs/docs_gen.py # Generate docs (process in-place)
+ uv run python docs/docs_gen.py --reset # Reset docs to templates
+ uv run python docs/docs_gen.py --verify # Verify docs have placeholders
+""",
+ )
+ parser.add_argument(
+ "--reset",
+ action="store_true",
+ help="Reset docs OUTPUT sections to placeholders",
+ )
+ parser.add_argument(
+ "--verify",
+ action="store_true",
+ help="Verify docs have placeholder OUTPUT sections",
+ )
+ parser.add_argument(
+ "--docs-only",
+ action="store_true",
+ help="Only process docs, not README.md",
+ )
+
+ args = parser.parse_args()
+ repo_root = _MODULE_DIR.parent
+
+ if args.reset:
+ return cmd_reset(repo_root)
+ if args.verify:
+ return cmd_verify(repo_root)
+ return cmd_generate(repo_root, include_readme=not args.docs_only)
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/docs/examples.md b/docs/examples.md
new file mode 100644
index 0000000..c6c44ab
--- /dev/null
+++ b/docs/examples.md
@@ -0,0 +1,209 @@
+---
+icon: lucide/book-open
+---
+
+# Examples
+
+Real-world examples demonstrating the power and flexibility of `markdown-code-runner`.
+
+
+
+
+
+
+ Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+
+```
+
+After running `markdown-code-runner`:
+```markdown
+This is an example of a simple code block:
+
+
+
+
+
+ Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+
+```
+
+### :star: Example 2: Multiple code blocks
+
+```markdown
+Here are two code blocks:
+
+First code block:
+
+
+
+
+
+ Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+
+```
+
+
+```markdown
+Second code block:
+
+
+
+
+
+ Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+
+```
+
+After running `markdown-code-runner`:
+
+```markdown
+Here are two code blocks:
+
+First code block:
+
+
+
+
+
+ Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+
+
+Second code block:
+
+
+
+
+
+ Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+
+```
+
+
+
+## Usage Ideas
+
+
+
+
+
+
+
+.*?", "", content, flags=re.DOTALL) -->
+
+
+
+ Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+
+```
+Which is rendered as:
+
+
+
+
+
+
+
+
+
+
+- delectus aut autem (User ID: 1, Completed: False)
+- quis ut nam facilis et officia qui (User ID: 1, Completed: False)
+- fugiat veniam minus (User ID: 1, Completed: False)
+- et porro tempora (User ID: 1, Completed: True)
+- laboriosam mollitia et enim quasi adipisci quia provident illum (User ID: 1, Completed: False)
+
+
+
+
+### :crab: Idea 6: Run a Rust program
+
+We can use `markdown-code-runner` to write Rust code to a file and then a hidden bash code block to run the code and display the output.
+
+The code below *is actually executed*, check out the [`README.md` in plain text](https://github.com/basnijholt/markdown-code-runner/blob/main/README.md?plain=1) to see how this works.
+
+```rust markdown-code-runner filename=main.rs
+fn main() {
+ println!("Hello, world!");
+}
+```
+
+Which when executed produces:
+
+
+
+
+
+
+
+
+
+```
+```
+
+
+
+These are just a few examples of how you can use Markdown Code Runner to enhance your Markdown documents with dynamic content. The possibilities are endless!
+
+
+
+## More Ideas
+
+Here are additional creative uses for `markdown-code-runner`:
+
+### Auto-Generate Package Statistics
+
+```python markdown-code-runner
+# Fetch package download statistics
+import requests
+
+url = "https://api.pepy.tech/api/v2/projects/markdown-code-runner"
+# Note: This would require an API key in practice
+print("Download statistics would appear here!")
+```
+
+### Document Your API
+
+```python markdown-code-runner
+# Auto-generate API documentation from docstrings
+import inspect
+from markdown_code_runner import update_markdown_file
+
+# Get function signature
+sig = inspect.signature(update_markdown_file)
+print(f"**Signature:** `update_markdown_file{sig}`")
+print()
+
+# Get docstring
+doc = update_markdown_file.__doc__
+if doc:
+ print(doc)
+```
+
+### Include Test Results
+
+```python markdown-code-runner
+# Show test coverage or test results
+import subprocess
+result = subprocess.run(
+ ["python", "-c", "print('All tests passed!')"],
+ capture_output=True,
+ text=True
+)
+print(result.stdout)
+```
+
+### Dynamic Configuration Examples
+
+```python markdown-code-runner
+# Generate configuration examples from actual defaults
+print("Default markers used by markdown-code-runner:")
+print()
+print("| Marker | Purpose |")
+print("|--------|---------|")
+print("| `` | Start of hidden Python code |")
+print("| `` | End of hidden code block |")
+print("| `` | Start of hidden Bash code |")
+print("| `` | Start of output section |")
+print("| `` | End of output section |")
+print("| `` | Skip the next code block |")
+```
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..9be41ca
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,46 @@
+---
+icon: lucide/rocket
+---
+
+# Getting Started
+
+This guide will help you install and start using `markdown-code-runner` in minutes.
+
+## Installation
+
+
+
+
+
+
+ Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+
+
+You can also install with `uv`:
+
+```bash
+uv pip install markdown-code-runner
+```
+
+Or as a tool:
+
+```bash
+uv tool install markdown-code-runner
+```
+
+## Quick Start
+
+
+
+
+
+
+ Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+
+
+## Next Steps
+
+- [Python API](usage/python-api.md) - Use markdown-code-runner programmatically
+- [CLI Reference](usage/cli.md) - Command-line interface options
+- [GitHub Actions](usage/github-actions.md) - Automate with CI/CD
+- [Examples](examples.md) - Real-world usage examples
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..f097a14
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,97 @@
+---
+icon: lucide/play
+---
+
+# Markdown Code Runner
+
+**Automatically execute code blocks within Markdown files and update the output in-place**
+
+
+
+
)
+[project.markdown_extensions.md_in_html]
+
+# Enable attribute lists for adding CSS classes (e.g., {.md-button})
+[project.markdown_extensions.attr_list]
+
+# Enable syntax highlighting for fenced code blocks
+[project.markdown_extensions.pymdownx.highlight]
+anchor_linenums = true
+
+[project.markdown_extensions.pymdownx.superfences]
+
+# Enable tabs (=== "Tab Name" syntax)
+[project.markdown_extensions.pymdownx.tabbed]
+alternate_style = true
+
+# Enable emoji/icon support
+[project.markdown_extensions.pymdownx.emoji]
+emoji_index = "zensical.extensions.emoji.twemoji"
+emoji_generator = "zensical.extensions.emoji.to_svg"
+