# Where Can I Find Documentation for Embabel-Agent? Official Sources and Local Build Guide

> Find embabel-agent documentation on the official docs site or build it locally with Maven. Access source files in the embabel-agent repository for quick reference.

- Repository: [Embabel/embabel-agent](https://github.com/embabel/embabel-agent)
- Tags: documentation
- Published: 2026-08-14

---

**The official documentation for embabel-agent lives at `https://docs.embel.com/embabel-agent/guide/1.5.0-SNAPSHOT/`, with source files in `embabel-agent-docs/src/main/asciidoc/` and a local build option using Maven.**

Finding comprehensive documentation for the Embabel Agent framework requires knowing where to look. The project maintains both a hosted documentation site and a fully reproducible documentation build pipeline within the repository itself. This guide covers all documentation sources with exact file paths and build commands from the source code.

## Official Live Documentation

The primary documentation for embabel-agent is published at:

```

https://docs.embel.com/embabel-agent/guide/1.5.0-SNAPSHOT/

```

This URL is linked directly from the project [`README.md`](https://github.com/embabel/embabel-agent/blob/main/README.md) badge labeled **"Docs"**. The live site contains:

- **User-level guide** — complete framework walkthrough
- **Quick-start tutorials** — get running in minutes
- **API reference** — detailed method and class documentation
- **Architectural overview** — design patterns and component relationships

The site uses a custom fragment notation for internal links (e.g., `[[reference.flow__topic]]`), which corresponds to section anchors in the generated output.

## Documentation Source Structure in the Repository

According to the embabel-agent source code, documentation originates from AsciiDoc sources and undergoes a multi-stage build process:

| Path | Purpose |
|------|---------|
| `embel-agent-docs/src/main/asciidoc/*.adoc` | Source AsciiDoc files — the **source of truth** for all documentation |
| [`embel-agent-docs/README.md`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-docs/README.md) | Build instructions and Markdown conversion details |
| [`README.md`](https://github.com/embabel/embabel-agent/blob/main/README.md) | Project overview with links to live docs and examples |
| `target/generated-docs/` | Maven build output directory (created at build time) |

Any updates to the documentation must be made in the `.adoc` source files; the generated output should never be edited directly.

## Building Documentation Locally

You can generate the full documentation site from source using Maven, then convert it to Markdown for offline reading or custom tooling.

### Step 1: Build with Maven

```bash

# Clone and enter the repository

git clone https://github.com/embel/embel-agent
cd embel-agent

# Generate HTML documentation

mvn generate-resources

```

This produces HTML output in `target/generated-docs/`.

### Step 2: Convert HTML to Markdown with Docling

The [`embel-agent-docs/README.md`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-docs/README.md) specifies **Docling** for HTML-to-Markdown conversion:

```bash

# Install Docling

pip install docling

# Convert the generated HTML to Markdown

docling ./target/generated-docs/index.html \
       --from html \
       --to md \
       --output ./target/generated-docs \
       --image-export-mode placeholder

```

After conversion, the main documentation file is available at:

```

target/generated-docs/index.md

```

## Accessing Documentation at Runtime

The generated documentation can be embedded and loaded as a Spring resource. This pattern enables in-application help systems or diagnostic outputs:

```kotlin
import org.springframework.core.io.ClassPathResource
import java.nio.file.Files

fun loadEmbeddedDocs(): String {
    val resource = ClassPathResource("embel-agent-docs/target/generated-docs/index.md")
    return Files.readString(resource.file.toPath())
}

```

This snippet demonstrates how to read the converted Markdown documentation at runtime — useful for implementing a `help` command or debug panel.

## Examples Repository

Practical illustrations of framework usage reside in a separate repository:

```

https://github.com/embel/embel-agent-examples

```

The main documentation site references these examples throughout. Clone this repository alongside `embel-agent` to follow along with the guides:

```bash
git clone https://github.com/embel/embel-agent-examples

```

The [`README.md`](https://github.com/embabel/embabel-agent/blob/main/README.md) in the examples repository serves as the entry point, organized to match the documentation structure.

## Summary

- **Primary documentation URL**: `https://docs.embel.com/embel-agent/guide/1.5.0-SNAPSHOT/` — bookmark this for daily reference
- **Source files**: Edit `embel-agent-docs/src/main/asciidoc/*.adoc` to contribute documentation changes
- **Local build**: Run `mvn generate-resources` then use Docling to convert to Markdown
- **Runtime access**: Load [`target/generated-docs/index.md`](https://github.com/embabel/embabel-agent/blob/main/target/generated-docs/index.md) as a classpath resource in Spring applications
- **Working examples**: Clone `embel/embel-agent-examples` for runnable code samples

## Frequently Asked Questions

### How do I contribute to the embel-agent documentation?

Documentation contributions require editing the AsciiDoc source files under `embel-agent-docs/src/main/asciidoc/`. After making changes, run `mvn generate-resources` to verify the build succeeds, then submit a pull request with your `.adoc` modifications. Never edit files in `target/generated-docs/` directly, as these are overwritten during each build.

### What version of the documentation should I reference?

The live site currently publishes version `1.5.0-SNAPSHOT` as shown in the URL path. Check the badge link in [`README.md`](https://github.com/embabel/embabel-agent/blob/main/README.md) to confirm you are viewing the latest version. The snapshot designation indicates active development; pinned release versions appear in the URL path when available.

### Can I read the documentation without internet access?

Yes. Build the documentation locally using the Maven and Docling commands described above. The resulting [`target/generated-docs/index.md`](https://github.com/embabel/embabel-agent/blob/main/target/generated-docs/index.md) contains the complete documentation in Markdown format. For HTML output, open [`target/generated-docs/index.html`](https://github.com/embabel/embabel-agent/blob/main/target/generated-docs/index.html) directly in a browser after the `mvn generate-resources` step.

### Why does the documentation use AsciiDoc instead of Markdown?

The project chose AsciiDoc for its superior support for technical documentation features: includes, cross-references, conditional content, and table generation. The Docling conversion pipeline then produces Markdown for consumption by tools that require it, giving the project flexibility to publish in multiple formats from a single source.