Add Zensical documentation site

.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

.gitignore

@@ -37,3 +37,6 @@ ENV/
 .env
 .coverage
 htmlcov/
+
+# Documentation build output
+site/

.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$

README.md

@@ -2,12 +2,15 @@
 
 ![](https://media.githubusercontent.com/media/basnijholt/nijho.lt/main/content/project/markdown-code-runner/featured.jpg)
 
+<!-- SECTION:intro:START -->
 `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.
+<!-- SECTION:intro:END -->
 
 The package is hosted on GitHub: [https://github.com/basnijholt/markdown-code-runner](https://github.com/basnijholt/markdown-code-runner)
 
+<!-- SECTION:features:START -->
 ## :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))
+<!-- SECTION:features:END -->
 
+<!-- SECTION:problem-statement:START -->
 ## :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.
+<!-- SECTION:problem-statement:END -->
 
 ## :books: Table of Contents
 
@@ -50,14 +56,17 @@ This ensures that the displayed output is always in sync with the code, and cont
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
+<!-- SECTION:installation:START -->
 ## :computer: Installation
 
 Install `markdown-code-runner` via pip:
 
 ```bash
 pip install markdown-code-runner
 ```
+<!-- SECTION:installation:END -->
 
+<!-- SECTION:quick-start:START -->
 ## :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.
+<!-- SECTION:quick-start:END -->
 
+<!-- SECTION:python-api:START -->
 ## :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")
 ```
+<!-- SECTION:python-api:END -->
 
+<!-- SECTION:examples:START -->
 ## :book: Examples
 
 Here are a few examples demonstrating the usage of `markdown-code-runner`:
@@ -222,11 +235,14 @@ Hello again!
 
 <!-- OUTPUT:END -->
 ```
+<!-- SECTION:examples:END -->
 
+<!-- SECTION:usage-ideas:START -->
 ## :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:
 
+<!-- SECTION:github-actions:START -->
 ### :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).
+<!-- SECTION:github-actions:END -->
 
 ### :computer: Idea 2: Show command-line output
 
@@ -528,11 +545,15 @@ Hello, world!
 <!-- OUTPUT:END -->
 
 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!
+<!-- SECTION:usage-ideas:END -->
 
+<!-- SECTION:license:START -->
 ## :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.
+<!-- SECTION:license:END -->
 
+<!-- SECTION:contributing:START -->
 ## :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`!
+<!-- SECTION:contributing:END -->

docs/CNAME

@@ -0,0 +1 @@
+markdown-code-runner.nijho.lt

docs/contributing.md

@@ -0,0 +1,73 @@
+---
+icon: lucide/git-pull-request
+---
+
+# Contributing
+
+<!-- CODE:START -->
+<!-- from docs_gen import readme_section -->
+<!-- print(readme_section("contributing")) -->
+<!-- CODE:END -->
+<!-- OUTPUT:START -->
+<!-- PLACEHOLDER --> Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py
+<!-- OUTPUT:END -->
+
+## 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