Akode.DocxGen 2.2.1

DocxGen

DocxGen turns Markdown and structured JSON into polished Word documents using your own .docx template. It can inspect placeholders, generate a JSON Schema for an AI agent, validate inputs, render the final document, and extract semantic Markdown from an existing DOCX.

The design rule is intentionally simple:

content in Markdown/JSON + design in DOCX = repeatable Word publishing

DocxGen is a cross-platform .NET 10 project. Use it as:

• the docxgen CLI or a standalone executable;
• an allowed DocxGen tool in an AI-agent workflow;
• the Akode.DocxGen NuGet library inside a .NET application;
• the document engine behind the cross-platform DocxGen UI desktop application.

It runs locally, requires no LLM, and keeps remote images and raw HTML disabled unless the caller explicitly enables them.

Desktop application

Prefer a graphical interface? akode-dev/docxgenui is an open-source, local-first desktop application powered by this Akode.DocxGen engine. It provides guided Markdown-to-Word, template rendering, and Word-to-Markdown workflows for Windows, macOS, and Linux.

Download the latest DocxGen UI installers or review its source, documentation, and issue tracker in the docxgenui repository.

What it can build

A template may be as small as one placeholder or as elaborate as a corporate report with a cover, logos, Document Control, revision tables, headers, footers, a Word table of contents, multiple Markdown sections, images, and a closing page.

The number of chapters is not fixed in JSON. Headings, paragraphs, lists, tables, code blocks, and images live in Markdown and flow naturally across as many pages as needed. Template placeholders provide the structured values:

{{ds.Document.Title}}
{{ds.Body}:MD}
{{ds.ClientLogo}:IMG(alt=Client logo)}
{{#ds.Revisions}} ... {{/ds.Revisions}}

The bundled template and sample are synthetic and safe to reuse:

templates/proposal.docx + samples/model.json + samples/proposal.md

They demonstrate one governed proposal, but DocxGen is document-type independent. Replace them with any placeholder-bearing DOCX template and its matching content model.

Install

Install the .NET tool:

dotnet tool install --global Akode.DocxGen.Tool
docxgen --help

Or download a self-contained archive from GitHub Releases. Release artifacts are built for:

To embed DocxGen in a .NET solution:

dotnet add package Akode.DocxGen

The package exposes Akode.DocxGen.DocxGenPipelineFactory and the public contracts from Akode.DocxGen.Core. See the embedding guide.

Quick start

First inspect the template instead of guessing its placeholders:

docxgen inspect --template templates/proposal.docx --json

Generate a Draft 2020-12 JSON Schema that an agent or form can follow:

docxgen generate-schema \
  --template templates/proposal.docx \
  --out artifacts/proposal.schema.json \
  --template-id proposal \
  --template-version 1.0.0 \
  --overwrite \
  --json

Create an editable model with Markdown stubs:

docxgen scaffold-model \
  --template templates/proposal.docx \
  --out artifacts/model.json \
  --with-markdown-stubs

Validate the completed model and its local assets:

docxgen validate-model \
  --template templates/proposal.docx \
  --model samples/model.json \
  --assets-dir samples \
  --json

Render and validate the final document:

docxgen render \
  --template templates/proposal.docx \
  --model samples/model.json \
  --assets-dir samples \
  --out artifacts/Proposal.docx \
  --append-document-version \
  --validate \
  --overwrite \
  --json

With document version 1.0, this writes Proposal-v1.0.docx. DocxGen never increments a business version and does not overwrite an existing file unless --overwrite is present.

Convert or extract without a governed template:

docxgen convert \
  --markdown samples/proposal.md \
  --out artifacts/Draft.docx \
  --overwrite

docxgen extract \
  --file artifacts/Draft.docx \
  --out artifacts/Draft.md \
  --overwrite \
  --json

Embedded images are exported beside extracted Markdown. Extraction preserves document meaning—headings, text formatting, links, lists, tables, code, and images—not Word's page geometry.

Commands

Every command is non-interactive. With --json, stdout contains a stable, versioned report suitable for tools and stderr remains human-readable. See the CLI reference, diagnostics, and report contract.

Agent workflow

Register the executable under the friendly tool name DocxGen, but invoke the actual binary as docxgen. Give the agent access only to the commands required by its task. A reliable document-generation sequence is:

inspect -> generate-schema/check -> scaffold-model -> validate-model -> render

The schema removes placeholder guesswork, while validate-model --json provides exact JSON Pointer paths and remediation hints. Hooks under eng/hooks/ expose the same validation contract to local and hosted agents. See agent integration.

JSON and Markdown

Each governed template can have an adjacent schema:

templates/report.docx
templates/report.schema.json

The schema owns the exact required object shape, template ID/version, and DOCX hash. A model can reference Markdown and assets without placing large content inside JSON:

{
  "modelVersion": "1.0",
  "template": {
    "id": "document-template",
    "version": "1.0.0"
  },
  "data": {
    "ds": {
      "Document": {
        "Title": "Platform modernization",
        "Version": "1.0"
      },
      "Body": {
        "$mdFile": "content.md"
      }
    }
  }
}

Supported directives include:

• { "$md": "# Inline Markdown" };
• { "$mdFile": "sections/approach.md" };
• { "$file": "assets/client-logo.png" };
• { "$text": "*literal, not Markdown*" }.

Markdown supports headings, paragraphs, emphasis, links, nested lists, task lists, fenced code, block quotes, GFM tables, horizontal rules, and local PNG, JPEG, GIF, BMP, or SVG images. Local paths are contained below --assets-dir.

Project layout

src/         production libraries and CLI
tests/       automated tests and architecture/license gates
templates/   reusable governed DOCX templates and schemas
samples/     runnable Markdown, JSON, and image inputs
docs/        public guides, contracts, architecture, and ADRs
eng/         verification scripts and agent hooks

The production packages are:

Architecture boundaries and the directory map are documented in architecture. The documentation index links user, contributor, contract, and release guides. Maintainers can configure keyless releases with the NuGet.org publishing guide.

Contributing

The project welcomes bug reports, template scenarios, documentation improvements, tests, and focused pull requests. Start with CONTRIBUTING.md and the development guide.

dotnet restore DocxGen.sln
dotnet build DocxGen.sln --configuration Release --no-restore
dotnet test DocxGen.sln --configuration Release --no-build

Please report vulnerabilities privately according to SECURITY.md. Community participation is governed by the Code of Conduct.

License

DocxGen is available under the MIT License. Runtime dependencies are locked, license-reviewed, and listed in THIRD-PARTY-NOTICES.md.