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

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 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	Build instructions and Markdown conversion details
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

# 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 specifies Docling for HTML-to-Markdown conversion:

# 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:

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:

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

The 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 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 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 contains the complete documentation in Markdown format. For HTML output, open 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}