### Example Content - Markdown

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/quick-start.md

A simple example of a content file in Markdown format for a Dodeca site. This file defines the title and content of the root page.

```markdown
+++
title = "My Site"
+++

Hello, world!
```

--------------------------------

### Install Dodeca on Windows

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/installation.md

Installs dodeca on Windows systems by downloading and executing a PowerShell script from GitHub releases. This method supports x86_64 architecture.

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/bearcove/dodeca/releases/latest/download/dodeca-installer.ps1 | iex"
```

--------------------------------

### Install Dodeca Release via Script (Shell)

Source: https://github.com/bearcove/dodeca/blob/main/DEVELOP.md

Provides shell commands to install the Dodeca release using a provided script. Shows how to install the latest release, a specific version, or install to a custom directory by setting environment variables.

```shell
# Install latest release
curl -fsSL https://raw.githubusercontent.com/bearcove/dodeca/main/install.sh | sh

# Install specific version
DODECA_VERSION=v0.3.0 curl -fsSL https://raw.githubusercontent.com/bearcove/dodeca/main/install.sh | sh

# Install to custom directory
DODECA_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/bearcove/dodeca/main/install.sh | sh
```

--------------------------------

### Serve Dodeca Site with Live Reload - Bash

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/quick-start.md

Starts a local development server for the Dodeca site with live reloading enabled. It will print the URL the site is being served from.

```bash
ddc serve
```

--------------------------------

### Dodeca - Add New Content (Markdown)

Source: https://github.com/bearcove/dodeca/blob/main/crates/dodeca/templates/minimal/content/guide/getting-started.md

Example of creating a new Markdown file for content in Dodeca. It demonstrates the required frontmatter structure with 'title' and 'weight' properties.

```markdown
+++
title = "My New Page"
weight = 10
+++

Your content here...
```

--------------------------------

### Dodeca - Run Development Server (CLI)

Source: https://github.com/bearcove/dodeca/blob/main/crates/dodeca/templates/minimal/content/guide/getting-started.md

Command to start the Dodeca development server. The `--open` flag automatically opens the site in the default browser. Changes are live-reloaded.

```bash
ddc serve --open
```

--------------------------------

### Full Dodeca Configuration Example

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/configuration.md

An example demonstrating a complete Dodeca configuration, combining basic settings, link checking with skipped domains, and stable assets.

```yaml
content: content
output: public

link_check:
  rate_limit_ms: 1000
  skip_domains:
    - example.com

stable_assets:
  - favicon.svg
```

--------------------------------

### Create Project Directory - Bash

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/quick-start.md

Creates a new directory for your Dodeca site and navigates into it. This is the initial step for setting up a new project.

```bash
mkdir my-site
cd my-site
```

--------------------------------

### Install and Manage Dodeca Sites (Bash)

Source: https://context7.com/bearcove/dodeca/llms.txt

Provides essential bash commands for installing Dodeca, initializing a new site, building the site locally or with a TUI, serving the site with live reload, checking links, and cleaning the build cache. It covers basic and advanced usage for build and serve commands.

```bash
# Install dodeca
cargo install dodeca

# Initialize a new site
ddc init my-site
cd my-site

# Build the site (output to public/ by default)
ddc build

# Build with TUI progress display
ddc build --tui

# Build to custom output directory
ddc build -o dist/

# Serve with live reload (tries ports 4000-4019)
ddc serve

# Serve on specific address and port
ddc serve -a 0.0.0.0 -p 8080

# Serve and automatically open browser
ddc serve --open

# Specify content directory
ddc serve -c docs/content/

# Check links in the site
ddc check-links

# Clean build cache and output
ddc clean
```

--------------------------------

### Verify Dodeca Installation

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/installation.md

Checks if the dodeca installation was successful by running the `ddc` command with the `--version` flag. This command should output the installed version of dodeca.

```bash
ddc --version
```

--------------------------------

### Install and Configure rrsync Server

Source: https://github.com/bearcove/dodeca/blob/main/scripts/CAS-SERVER-SETUP.md

Steps to install rrsync, create a dedicated user and directory, set up SSH keys for secure access, and configure authorized_keys with rrsync specific options for read-only, write-once access within a chroot environment. This ensures secure and controlled data transfer.

```bash
# 1. Install rrsync (comes with rsync package on most systems)
# Debian/Ubuntu: /usr/bin/rrsync or /usr/share/doc/rsync/scripts/rrsync
# If not found, download from rsync source

# 2. Create CAS user and directory
sudo useradd -r -s /usr/sbin/nologin -d /srv/cas cas
sudo mkdir -p /srv/cas/cas/{sha256,pointers}
sudo chown -R cas:cas /srv/cas

# 3. Set up SSH key (get public key from CAS_SSH_KEY secret)
sudo mkdir -p /home/cas/.ssh
sudo chmod 700 /home/cas/.ssh

# 4. Add to /home/cas/.ssh/authorized_keys:
command="rrsync -wo /srv/cas/cas",no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding ssh-ed25519 AAAA... your-key-here

# Flags explained:
# -w: write-only (no downloads) - remove to allow downloads
# -o: write-once (prevent overwrites) - remove to allow overwrites
# /srv/cas/cas: chroot to this directory

sudo chmod 600 /home/cas/.ssh/authorized_keys
sudo chown -R cas:cas /home/cas

# 5. Test connection from client
ssh cas@golem.bearcove.cloud
# Should print: Please use rsync to access this directory.

```

--------------------------------

### Install Dodeca on macOS/Linux

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/installation.md

Installs dodeca on macOS and Linux systems by downloading and executing a shell script from GitHub releases. This method is suitable for Apple Silicon (arm64) on macOS and x86_64 on Linux.

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bearcove/dodeca/releases/latest/download/dodeca-installer.sh | sh
```

--------------------------------

### Generate CI Workflow and Installer (Shell)

Source: https://github.com/bearcove/dodeca/blob/main/DEVELOP.md

Commands to regenerate the CI release workflow and installer script from Rust source code. Includes an option to check if generated files are up-to-date, primarily for CI usage.

```shell
# Regenerate .github/workflows/release.yml and install.sh
cargo xtask ci

# Check if generated files are up to date (used in CI)
cargo xtask ci --check
```

--------------------------------

### Example Dodeca Configuration for Assets

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/static-assets.md

A comprehensive example of a Dodeca configuration file, specifying content and output directories, and listing assets that should be treated as stable. This configuration ensures that essential files like favicons and robots.txt maintain fixed URLs.

```yaml
content: content
output: public

stable_assets:
  - favicon.svg
  - robots.txt
  - og-image.png
  - apple-touch-icon.png
```

--------------------------------

### Build Dodeca from Source

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/installation.md

Builds the dodeca project from its source code using Cargo XTASk. This process clones the repository, navigates into the directory, and executes the build command, which compiles WASM components, plugins, and the main binary.

```bash
git clone https://github.com/bearcove/dodeca.git
cd dodeca
cargo xtask build
```

--------------------------------

### TOML Frontmatter: Complete Example

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/frontmatter.md

A comprehensive example combining multiple frontmatter fields including title, description, weight, template, and various custom fields within the `[extra]` table.

```toml
+++
title = "Comprehensive Guide"
description = "Everything you need to know"
weight = 10
template = "guide.html"

[extra]
author = "amos"
difficulty = "intermediate"
prerequisites = ["basics", "setup"]
sidebar = true
+++
```

--------------------------------

### Markdown Frontmatter Example

Source: https://github.com/bearcove/dodeca/blob/main/crates/dodeca/templates/blog/content/posts/hello-world.md

Example of frontmatter for a Markdown blog post, including title, weight, and extra metadata like date and author. This structure is essential for organizing and sorting posts.

```markdown
+++
title = "My New Post"
weight = 10

[extra]
date = "2024-01-15"
author = "Your Name"
+++

Your content here...
```

--------------------------------

### Execute Rust Code Block - Rust

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/quick-start.md

An example of a Rust code block marked for execution within Dodeca. When using `ddc build` or `ddc serve` with the code execution helper, this code will be compiled and run.

```rust
let message = "Hello from dodeca!";
println!("{}", message);
```

--------------------------------

### Example Dodeca Site Layout

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/project-layout.md

Illustrates a typical file and directory structure for a Dodeca project. This includes configuration, content, templates, static assets, and build output.

```tree
my-site/
├── .config/
│   └── dodeca.yaml
├── content/
│   ├── _index.md
│   └── guide/
│       ├── _index.md
│       └── intro.md
├── templates/
│   ├── base.html
│   ├── index.html
│   ├── section.html
│   └── page.html
├── static/
│   └── images/
│       └── logo.png
└── public/               # build output (configured via dodeca.yaml)

```

--------------------------------

### Dodeca Site Configuration (KDL)

Source: https://context7.com/bearcove/dodeca/llms.txt

Example KDL configuration file for Dodeca. It demonstrates how to set content and output directories, configure link checking with skips and rate limits, define stable assets, enable and configure code execution with dependencies and language-specific settings (Rust), and set syntax highlighting themes.

```kdl
// .config/dodeca.kdl
content "docs/content"
output "docs/public"

link_check {
    // Optional: skip specific domains
    skip_domains "example.com" "test.org"
    // Rate limit for external checks (ms)
    rate_limit_ms 1000
}

stable_assets {
    // Assets that don't get cache-busted
    "favicon.ico"
    "robots.txt"
}

code_execution {
    enabled #true
    fail_on_error #true
    timeout_secs 30
    cache_dir ".cache/code-execution"

    dependencies {
        "serde" "1.0"
        "tokio" "1.0"
    }

    rust {
        command "cargo"
        args "run" "--quiet" "--release"
        extension "rs"
        prepare_code #true
        show_output #true
    }
}

syntax-highlight {
    light-theme "github-light"
    dark-theme "tokyo-night"
}
```

--------------------------------

### Dodeca - Build for Production (CLI)

Source: https://github.com/bearcove/dodeca/blob/main/crates/dodeca/templates/minimal/content/guide/getting-started.md

Command to build the Dodeca project for production deployment. The output is generated in the 'public/' directory.

```bash
ddc build
```

--------------------------------

### Build Dodeca Project Artifacts (Shell)

Source: https://github.com/bearcove/dodeca/blob/main/DEVELOP.md

Commands to build the Dodeca project, including WASM, plugins, and the main executable. Supports both standard and release builds, running the executable, and installing it to the Cargo bin directory.

```shell
# Build everything (WASM + plugins + dodeca)
cargo xtask build

# Build in release mode
cargo xtask build --release

# Run ddc after building
cargo xtask run -- serve

# Install to ~/.cargo/bin
cargo xtask install
```

--------------------------------

### Dodeca Project Structure Overview

Source: https://github.com/bearcove/dodeca/blob/main/crates/dodeca/templates/minimal/content/guide/getting-started.md

Visual representation of a typical Dodeca project directory layout. It highlights key directories for configuration, content, styles, static assets, and templates.

```text
{{site_name}}/.
├── .config/
│   └── dodeca.yaml     # Configuration
├── content/
│   ├── _index.md       # Home page
│   └── guide/
│       ├── _index.md   # Guide section
│       └── getting-started.md
├── sass/
│   └── main.scss       # Styles
├── static/             # Static assets
└── templates/
    ├── base.html       # Base template
    ├── index.html      # Home page template
    ├── section.html    # Section template
    └── page.html       # Page template
```

--------------------------------

### TOML Frontmatter Example

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/project-layout.md

Demonstrates the use of TOML frontmatter within Markdown files for defining metadata like title, description, and weight. This is a common pattern for content organization in Dodeca.

```toml
+++
title = "Intro"
description = "Optional"
weight = 10
+++
```

--------------------------------

### Convert Path to URL (Jinja)

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/internals/templates.md

This example illustrates how to use the `get_url` function to convert a content path into a usable web URL, typically for creating navigation links.

```jinja
<a href="{{ get_url(path='guide/getting-started') }}">Get Started</a>
```

--------------------------------

### HTML Minification Example

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/internals/minification.md

Demonstrates HTML minification by collapsing whitespace, omitting optional tags, stripping comments, and removing unnecessary quotes. This is handled by the `minify-html` library.

```html
<div class=container><p>Hello, world!
```

--------------------------------

### Basic Jinja Control Flow (Jinja)

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/internals/templates.md

This snippet provides examples of fundamental Jinja control flow structures, including `if`/`elif`/`else` for conditional logic, `for` loops for iteration, and `set` for variable assignment.

```jinja
{% if condition %}
  ...
{% elif other %}
  ...
{% else %}
  ...
{% endif %}

{% for item in list %}
  {{ item }}
{% endfor %}

{% set variable = value %}
```

--------------------------------

### Evaluate Expressions with Gingembre

Source: https://context7.com/bearcove/dodeca/llms.txt

This example demonstrates how to evaluate template expressions directly using the `eval_expression` function provided by Gingembre. It takes an expression string and a context, returning the evaluated result. This is useful for dynamic content generation or testing.

```rust
use gingembre::{Context, Value};

// Expression evaluation (REPL-style)
let result = gingembre::eval_expression("page.title | upper", &ctx).await?;
assert_eq!(result.to_string(), "MY BLOG POST");
```

--------------------------------

### Configuring Stable Assets in Dodeca YAML

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/static-assets.md

Provides an example of how to configure specific assets to have stable URLs in the `dodeca.yaml` configuration file. These assets, such as favicons and robots.txt, will not have cache-busting hashes appended to their URLs.

```yaml
stable_assets:
  - favicon.svg
  - robots.txt
  - og-image.png
```

--------------------------------

### Complete Jinja Template Example

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/internals/templates.md

A comprehensive Jinja template demonstrating inheritance, block definition, loop usage for breadcrumbs and table of contents, conditional rendering, and content rendering with filters. It shows a typical structure for an article page, including navigation and metadata.

```jinja
{% extends "base.html" %}

{% block title %}{{ page.title }} - {{ config.title }}{% endblock %}

{% block content %}
<article>
  {# Breadcrumbs #}
  <nav class="breadcrumbs">
    <a href="/">Home</a>
    {% for ancestor in page.ancestors %}
      / <a href="{{ ancestor.permalink }}">{{ ancestor.title }}</a>
    {% endfor %}
    / {{ page.title }}
  </nav>

  <h1>{{ page.title }}</h1>
  {{ page.content | safe }}

  {# Table of contents #}
  {% if page.toc and page.toc | length > 0 %}
  <aside class="toc">
    <h2>On this page</h2>
    <ul>
      {% for h in page.toc %}
        <li><a href="{{ h.permalink }}">{{ h.title }}</a></li>
      {% endfor %}
    </ul>
  </aside>
  {% endif %}
</article>
{% endblock %}
```

--------------------------------

### Sass/SCSS Directory Structure and Entry Point

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/sass.md

Organize Sass files in a 'sass/' directory at the project root. 'sass/main.scss' is the required entry point for compilation; other files starting with '_' are considered partials and not compiled directly.

```tree
my-site/
├── .config/
│   └── dodeca.yaml
├── content/
├── sass/
│   ├── main.scss        # Entry point (required)
│   ├── _variables.scss  # Partial (not compiled directly)
│   └── _components.scss # Another partial
├── static/
└── templates/
```

--------------------------------

### Trigger Dodeca Release via Git Tag (Shell)

Source: https://github.com/bearcove/dodeca/blob/main/DEVELOP.md

Demonstrates how to trigger a Dodeca release by pushing a version tag to the Git repository. This process automatically builds artifacts for all targets, creates archives, generates checksums, and creates a GitHub release.

```shell
git tag v0.3.0
git push origin v0.3.0
```

--------------------------------

### Serve Static Files API

Source: https://context7.com/bearcove/dodeca/llms.txt

Serves static assets directly from the Picante database.

```APIDOC
## GET /static/*file

### Description
Serves static files (e.g., images, JavaScript) stored within the Picante database.

### Method
GET

### Endpoint
`/static/*file`

### Parameters
#### Path Parameters
- **file** (string) - Required - The path to the static file requested.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200 OK)
- **body** (Response) - The content of the static file with the correct MIME type and caching headers.

#### Error Response (404 NOT FOUND)
- **body** - An error message if the static file is not found.

#### Response Example
```http
HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: public, max-age=31536000, immutable

[Binary image data...]
```
```

--------------------------------

### Add Copy Button to Code Blocks

Source: https://github.com/bearcove/dodeca/blob/main/crates/dodeca/tests/fixtures/sample-site/public/guide/getting-started/index.html

This JavaScript code snippet adds a 'Copy' button to all preformatted code blocks on the page. When clicked, it copies the code content to the clipboard and provides visual feedback. It uses the Clipboard API and DOM manipulation.

```javascript
document.addEventListener('DOMContentLoaded', () => {
  document.querySelectorAll('pre').forEach(pre => {
    if (pre.querySelector('.copy-btn')) return;
    const btn = document.createElement('button');
    btn.className = 'copy-btn';
    btn.textContent = 'Copy';
    btn.onclick = async () => {
      const code = pre.querySelector('code')?.textContent || pre.textContent;
      await navigator.clipboard.writeText(code);
      btn.textContent = 'Copied!';
      btn.classList.add('copied');
      setTimeout(() => {
        btn.textContent = 'Copy';
        btn.classList.remove('copied');
      }, 2000);
    };
    pre.appendChild(btn);
  });
});
```

--------------------------------

### Serve CSS API

Source: https://context7.com/bearcove/dodeca/llms.txt

Provides the main CSS file for styling the served content.

```APIDOC
## GET /styles.css

### Description
Serves the main CSS file (`styles.css`) generated from the Picante database.

### Method
GET

### Endpoint
`/styles.css`

### Parameters
(No parameters)

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200 OK)
- **body** (Response) - The CSS content with appropriate headers.

#### Error Response (500 INTERNAL SERVER ERROR)
- **body** - An error message if CSS generation fails.

#### Response Example
```http
HTTP/1.1 200 OK
Content-Type: text/css
Cache-Control: public, max-age=31536000, immutable

body {
    font-family: sans-serif;
}
```
```

--------------------------------

### Render HTML Templates with Gingembre Engine

Source: https://context7.com/bearcove/dodeca/llms.txt

This snippet demonstrates basic template rendering using the Gingembre engine. It involves setting up an InMemoryLoader, adding template files, building a context with data, and then rendering a specific template. Dependencies include the `gingembre` crate.

```rust
use gingembre::{Engine, Context, Value, InMemoryLoader};

// Basic template rendering
let mut loader = InMemoryLoader::new();
loader.add("base.html", r#"<!DOCTYPE html>
<html>
<head>
    <title>{% block title %}Default Title{% endblock %}</title>
</head>
<body>
    {% block content %}{% endblock %}
</body>
</html>"#);

loader.add("page.html", r#"{% extends "base.html" %}

{% block title %}{{ page.title }}{% endblock %}

{% block content %}
<article>
    <h1>{{ page.title }}</h1>
    <time>{{ page.date | date_format: "%Y-%m-%d" }}</time>

    {% if page.draft %}
    <div class="draft-notice">This is a draft</div>
    {% endif %}

    <div class="content">
        {{ page.body | safe }}
    </div>

    {% if page.tags %}
    <ul class="tags">
        {% for tag in page.tags %}
        <li><a href="/tags/{{ tag }}/">{{ tag }}</a></li>
        {% endfor %}
    </ul>
    {% endif %}
</article>
{% endblock %}"#);

// Build context with data
let engine = Engine::new(loader);
let mut ctx = Context::new();

ctx.set("page", Value::Object({
    let mut obj = VObject::new();
    obj.insert("title".into(), Value::from("My Blog Post"));
    obj.insert("date".into(), Value::from("2024-01-15"));
    obj.insert("draft".into(), Value::from(false));
    obj.insert("body".into(), Value::from("<p>Post content here</p>"));
    obj.insert("tags".into(), Value::Array({
        let mut arr = VArray::new();
        arr.push(Value::from("rust"));
        arr.push(Value::from("web"));
        arr
    }));
    obj
}));

// Render
let output = engine.render("page.html", &ctx).await?;
```

--------------------------------

### Serve Content API

Source: https://context7.com/bearcove/dodeca/llms.txt

Handles requests for dynamic content, serving rendered pages from the Picante database.

```APIDOC
## GET /*path

### Description
Serves rendered HTML pages based on the provided path. It queries the Picante database and injects a live reload script in development mode.

### Method
GET

### Endpoint
`/*path`

### Parameters
#### Path Parameters
- **path** (string) - Required - The requested path for the page.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200 OK)
- **body** (Html<String>) - The rendered HTML content of the page.

#### Error Response (500 INTERNAL SERVER ERROR)
- **body** - An error message if rendering fails.

#### Response Example
```html
<!DOCTYPE html>
<html>
<head>
    <title>Example Page</title>
</head>
<body>
    <h1>Hello, World!</h1>
    <script type="module">
        import { initLiveReload } from '/livereload.js';
        initLiveReload();
    </script>
</body>
</html>
```
```

--------------------------------

### CAS Server Debugging Commands

Source: https://github.com/bearcove/dodeca/blob/main/scripts/CAS-SERVER-SETUP.md

A collection of bash commands for debugging the CAS server setup. These include checking user permissions, verifying disk usage of the content store, finding recently uploaded files, and cleaning up old pointer files to manage storage.

```bash
# On server, check what cas user can do:
sudo -u cas ls -la /srv/cas/cas/

# Check disk usage:
sudo du -sh /srv/cas/cas/sha256/

# Find recent uploads:
sudo find /srv/cas/cas/sha256 -type f -mmin -60 | head

# Clean up old pointers (optional):
sudo find /srv/cas/cas/pointers -type f -mtime +30 -delete

```

--------------------------------

### Code Execution Failure Example

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/code-execution.md

This example illustrates the error message format when a Rust code execution fails during a `ddc build`. It shows the file, line number, language, and the specific stderr output from the compilation or runtime error, helping developers identify and fix issues.

```text
✗ Code execution failed in content/tutorial.md:42 (rust): Process exited with code: Some(1)
  stderr: error[E0425]: cannot find value `typo_variable`
```

--------------------------------

### TOML Frontmatter: Description Field

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/frontmatter.md

Example of setting the optional `description` field in frontmatter. This string is available as `section.description` for sections in templates.

```toml
+++
title = "API Reference"
description = "Complete API documentation for all endpoints"
+++
```

--------------------------------

### ddc build

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/cli.md

Build the site to the output directory. This command compiles your project's content and templates into static files.

```APIDOC
## ddc build

### Description
Build the site to the output directory.

### Method
CLI

### Endpoint
`ddc build [path] [OPTIONS]`

### Parameters
#### Path Parameters
- **[path]** (string) - Optional - Project directory. If omitted, searches from the current directory upward for `.config/dodeca.yaml`.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Build the site in the current directory
ddc build

# Build a specific project
ddc build ~/my-site

# Build with custom output directory
ddc build -o dist

# Build with progress UI
ddc build --tui
```

### Response
#### Success Response (0)
Build completed successfully.

#### Response Example
None

### Options
- `-c, --content <dir>`: Override the content directory.
- `-o, --output <dir>`: Override the output directory.
- `--tui`: Show TUI progress display.
```

--------------------------------

### Rust: Build Site Tree Structure with Dependency Tracking

Source: https://context7.com/bearcove/dodeca/llms.txt

Constructs the complete site tree structure by parsing markdown files and organizing them into sections and pages. This `picante::tracked` function iterates through source files, distinguishing between index pages (sections) and regular pages, and returns a `PicanteResult<SiteTree>`.

```rust
use picante::PicanteResult;
use crate::db::{Db, SourceFile};

// Build the complete site tree structure
#[picante::tracked]
pub async fn build_tree<DB: Db>(db: &DB) -> PicanteResult<SiteTree> {
    // Parse all markdown files
    let sources = SourceRegistry::sources(db)?.unwrap_or_default();

    // Build tree of sections and pages
    let mut sections = Vec::new();
    let mut pages = Vec::new();

    for source in sources.iter() {
        let path = source.path(db)?;
        let content = source.content(db)?;

        if is_index_page(&path) {
            sections.push(parse_section(db, source).await?);
        } else {
            pages.push(parse_page(db, source).await?);
        }
    }

    Ok(SiteTree { sections, pages })
}
```

--------------------------------

### TOML Frontmatter: Title Field

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/frontmatter.md

Example of using the `title` frontmatter field. This string value sets the page or section title and is available as `page.title` or `section.title` in templates.

```toml
+++
title = "Getting Started"
+++
```

--------------------------------

### Loading and Displaying Navigation from YAML Data

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/internals/templates.md

Provides an example of loading navigation data from a `navigation.yaml` file and rendering it as a navigation menu. It showcases accessing data through `data.navigation` and iterating over lists.

```jinja
<nav>
{% for item in data.navigation.main %}
  <a href="{{ item.url }}"{% if item.external %} target="_blank"{% endif %}>
    {{ item.label }}
  </a>
{% endfor %}
</nav>
```

--------------------------------

### Define and Use Template Macros with Gingembre

Source: https://context7.com/bearcove/dodeca/llms.txt

This snippet illustrates how to define and use macros within the Gingembre template engine. It shows importing macros from one template file into another and then invoking them with arguments. This promotes code reusability in templates.

```rust
use gingembre::{Engine, Context, Value, InMemoryLoader};

// Template macros
loader.add("macros.html", r#"{% macro card(title, description) %}
<div class="card">
    <h3>{{ title }}</h3>
    <p>{{ description }}</p>
</div>
{% endmacro %}"#);

loader.add("cards.html", r#"{% from "macros.html" import card %}

<div class="cards">
    {{ card("First Card", "Description 1") }}
    {{ card("Second Card", "Description 2") }}
</div>
"#);
```

--------------------------------

### Root Section Template - HTML

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/quick-start.md

The default HTML template for the root section of a Dodeca site. It demonstrates how to use Dodeca's templating language to display section titles and content.

```html
<!DOCTYPE html>
<html>
<head>
    <title>{{ section.title }}</title>
</head>
<body>
    {{ section.content | safe }}
</body>
</html>
```

--------------------------------

### TOML Frontmatter: Template Field

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/frontmatter.md

Example of specifying a custom template file using the `template` field. If omitted, Dodeca uses default templates like `index.html`, `section.html`, or `page.html`.

```toml
+++
title = "Landing Page"
template = "landing.html"
+++
```

--------------------------------

### Load Cell Binary and Establish RPC Session (Rust)

Source: https://context7.com/bearcove/dodeca/llms.txt

Loads a cell binary from the executable directory and establishes an RPC session using the provided shared memory hub. It configures environment variables for the cell process, passes a socket for signaling via file descriptor passing, and waits for the cell to signal readiness.

```rust
use rapace::transport::shm::{HubHost, HubConfig, AddPeerOptions, ShmTransport};
use rapace::{RpcSession, Session};
use std::process::{Command, Stdio};
use std::path::PathBuf;
use std::sync::Arc;

// Assuming these types are defined elsewhere:
// use crate::{CellLifecycleClient, ReadyAck, ReadyMsg};
// use dodeca_app::ImageProcessorClient, WebPProcessorClient, SassCompilerClient, MinifierClient;

/// Load a cell binary and establish RPC session
pub async fn load_cell(
    hub: &Arc<HubHost>,
    cell_name: &str,
) -> Result<RpcSession> {
    // Find cell binary (in same directory as main binary)
    let exe_dir = std::env::current_exe()?.parent().unwrap().to_path_buf();
    let cell_path = exe_dir.join(format!("ddc-cell-{}", cell_name));

    // Add peer to hub
    let peer_id = hub.next_peer_id();
    let (tx_ring, rx_ring) = hub.add_peer(AddPeerOptions {
        peer_id,
        tx_slots: 64,
        rx_slots: 64,
    })?;

    // Create socketpair for doorbell signaling
    let (our_sock, their_sock) = socketpair()?;

    // Spawn cell process with environment variables
    let mut cmd = Command::new(cell_path);
    cmd.env("RAPACE_HUB_PATH", hub.path());
    cmd.env("RAPACE_PEER_ID", peer_id.to_string());
    cmd.env("RAPACE_TX_RING_OFFSET", tx_ring.offset().to_string());
    cmd.env("RAPACE_RX_RING_OFFSET", rx_ring.offset().to_string());

    // Pass doorbell socket via fd passing
    cmd.stdin(Stdio::from(their_sock));

    let child = cmd.spawn()?;

    // Create RPC session over SHM transport
    let transport = ShmTransport::new(tx_ring, rx_ring, our_sock);
    let session = RpcSession::new(transport);

    // Wait for cell to signal readiness
    // let lifecycle: CellLifecycleClient = session.client();
    // let ReadyAck = lifecycle.wait_ready(ReadyMsg {}).await?;

    Ok(session)
}

// Placeholder for socketpair function if not globally available
fn socketpair() -> Result<(std::os::unix::io::RawFd, std::os::unix::io::RawFd)> {
    // Implementation depends on the OS, e.g., using nix::unistd::socketpair
    unimplemented!("socketpair not implemented")
}
```

--------------------------------

### ddc serve

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/cli.md

Build and serve the site with live reload. Changes to content, templates, or styles are automatically reflected in the browser.

```APIDOC
## ddc serve

### Description
Build and serve the site with live reload. Changes to content, templates, or styles are automatically reflected in the browser.

### Method
CLI

### Endpoint
`ddc serve [path] [OPTIONS]`

### Parameters
#### Path Parameters
- **[path]** (string) - Optional - Project directory. If omitted, searches from the current directory upward for `.config/dodeca.yaml`.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Serve the site with defaults
ddc serve

# Serve on a specific port
ddc serve -p 8080

# Serve with LAN access and open browser
ddc serve --public --open

# Serve without the TUI
ddc serve --no-tui
```

### Response
#### Success Response (0)
Server started successfully and is serving the site.

#### Response Example
None

### Options
- `-c, --content <dir>`: Override the content directory (Default: From config).
- `-o, --output <dir>`: Override the output directory (Default: From config).
- `-a, --address <addr>`: Address to bind on (Default: `127.0.0.1`).
- `-p, --port <port>`: Port to serve on (Default: `4000`).
- `-P, --public`: Listen on all interfaces (LAN access) (Default: Off).
- `--open`: Open browser after starting server (Default: Off).
- `--no-tui`: Disable TUI (show plain logs) (Default: Off).

### TUI Keyboard Shortcuts
When running with the TUI (default), these shortcuts are available:
- `?`: Toggle help overlay
- `o`: Open first URL in browser
- `p`: Toggle public/local mode
- `d`: Toggle debug logging
- `l`: Cycle log level
- `f`: Cycle log filter presets
- `F`: Enter custom log filter (RUST_LOG syntax)
- `q`: Quit
- `Ctrl+C`: Force quit
```

--------------------------------

### Rust: Load Single Template with Dependency Tracking

Source: https://context7.com/bearcove/dodeca/llms.txt

Loads a single template using the `picante::tracked` macro, automatically tracking its dependencies. It requires a database connection and a `TemplateFile` as input, returning a `PicanteResult<TemplateContent>`.

```rust
use picante::PicanteResult;
use crate::db::{Db, TemplateFile, TemplateContent};

// Load a single template - automatically tracks dependency
#[picante::tracked]
pub async fn load_template<DB: Db>(
    db: &DB,
    template: TemplateFile,
) -> PicanteResult<TemplateContent> {
    template.content(db)
}
```

--------------------------------

### Accessing Site Configuration in Templates

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/internals/templates.md

Demonstrates how to access global site configuration variables like title, description, and base URL within Jinja-like templates. No external dependencies are required beyond the template engine itself.

```jinja
{{ config.title }}
{{ config.description }}
{{ config.base_url }}
```

--------------------------------

### Jinja Template Access to Extra Fields

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/frontmatter.md

Demonstrates how to access custom fields defined in the `[extra]` frontmatter table within Jinja templates. Examples include author, reading time, and iterating over tags.

```jinja
<p>By {{ page.extra.author }}</p>
<p>{{ page.extra.reading_time }} min read</p>
{% for tag in page.extra.tags %}
  <span class="tag">{{ tag }}</span>
{% endfor %}
```

--------------------------------

### Sass URL Rewriting Example

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/sass.md

Dodeca automatically rewrites URLs within your SCSS files to point to the correct cache-busted asset paths after compilation. This ensures assets like images and fonts are correctly referenced.

```scss
// Input SCSS
.hero {
  background: url('/images/hero.jpg');
}

// Output CSS (after compilation)
.hero {
  background: url('/images/hero.dec0da12.jpg');
}
```

--------------------------------

### Axum HTTP Server for Picante Content

Source: https://context7.com/bearcove/dodeca/llms.txt

Sets up an Axum HTTP server to serve dynamic content, static files, and CSS directly from a Picante database. It defines routes for different content types and integrates with a stateful database connection.

```rust
use axum::{Router, extract::Path, response::Html, routing::get, http::StatusCode, extract::State, response::Response};
use std::sync::Arc;
use crate::queries::{render_page, css_output, static_file_output};
use crate::db::Database;
use crate::models::{Route, StaticPath};

pub async fn run_server(
    db: Arc<Database>,
    addr: std::net::SocketAddr,
) -> Result<(), Box<dyn std::error::Error>> {
    let app = Router::new()
        .route("/*path", get(serve_page))
        .route("/static/*file", get(serve_static))
        .route("/styles.css", get(serve_css))
        .with_state(db);

    axum::Server::bind(&addr)
        .serve(app.into_make_service())
        .await?;

    Ok(())
}

async fn serve_page(
    Path(path): Path<String>,
    State(db): State<Arc<Database>>,
) -> Result<Html<String>, StatusCode> {
    let route = Route::from_path(&path);

    // Query Picante - only re-renders if inputs changed
    match render_page(&db, route).await {
        Ok(rendered) => {
            // Inject live reload script in dev mode
            let html = inject_livereload_script(rendered.html);
            Ok(Html(html))
        }
        Err(e) => {
            eprintln!("Render error: {e}");
            Err(StatusCode::INTERNAL_SERVER_ERROR)
        }
    }
}

async fn serve_css(
    State(db): State<Arc<Database>>,
) -> Result<Response, StatusCode> {
    match css_output(&db).await {
        Ok(css) => {
            Ok(Response::builder()
                .header("Content-Type", "text/css")
                .header("Cache-Control", "public, max-age=31536000, immutable")
                .body(css.content)
                .unwrap())
        }
        Err(e) => {
            eprintln!("CSS error: {e}");
            Err(StatusCode::INTERNAL_SERVER_ERROR)
        }
    }
}

async fn serve_static(
    Path(file): Path<String>,
    State(db): State<Arc<Database>>,
) -> Result<Response, StatusCode> {
    let static_path = StaticPath::from_str(&file);

    match static_file_output(&db, static_path).await {
        Ok(output) => {
            let mime = mime_guess::from_path(&file)
                .first_or_octet_stream();

            Ok(Response::builder()
                .header("Content-Type", mime.as_ref())
                .header("Cache-Control", "public, max-age=31536000, immutable")
                .body(output.data)
                .unwrap())
        }
        Err(e) => {
            eprintln!("Static file error: {e}");
            Err(StatusCode::NOT_FOUND)
        }
    }
}

fn inject_livereload_script(html: String) -> String {
    let script = r#"<script type="module">
    import { initLiveReload } from '/livereload.js';
    initLiveReload();
</script>"#;
    html.replace("</body>", &format!("{}\n</body>", script))
}

```

--------------------------------

### Display-Only Rust Code Block

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/guide/code-execution.md

This Markdown snippet shows a Rust code block that is intended for display only and will not be executed by Dodeca. This is useful for showcasing pseudo-code, incomplete examples, or code that is intentionally not meant to be validated during the build process.

```markdown
```rust
// This won't be executed - just displayed
let broken_code = does_not_compile();
```
```

--------------------------------

### Jinja Macro Definition and Usage

Source: https://github.com/bearcove/dodeca/blob/main/docs/content/internals/templates.md

Shows how to define reusable template fragments using Jinja macros. Macros accept arguments and can be invoked within the template. This example defines a simple button macro and then calls it with specific labels and links.

```jinja
{% macro button(label, href, class="btn") %}
  <a href="{{ href }}" class="{{ class }}">{{ label }}</a>
{% endmacro %}

{{ self::button(label="Click me", href="/action") }}
```