Automating document generation for teams: a practical guide

Every organisation produces dozens of recurring documents: weekly status reports, project proposals, release notes, compliance reports, API documentation. Most of them follow the same structure every time. Yet most teams still produce them manually — copy an old version, update the content, fight with Word's formatting, export to PDF, email it around.

There's a better way.

The Markdown-first workflow

The pattern that scales is simple:

1. Authors write in Markdown — in their editor of choice, in a Git repo
2. CI/CD runs the conversion — on every push or on a schedule
3. Branded documents are published — to Confluence, SharePoint, email, or a shared drive

Markdown keeps content and formatting separate. Authors focus on words; the conversion pipeline handles layout, fonts, logos, and output format.

Setting up a team pipeline

1. Agree on a template

Create one canonical .docx file that defines your organisation's paragraph styles:

• Heading 1, 2, 3 — your brand's font, size, and colour
• Normal — body text style
• Code Block / Code Span — monospace with background
• Table — header row colour, borders

Upload this template once to your Wagoe Blueprint organisation. Every team member's conversions use it automatically.

2. Create a conversion script

#!/bin/bash
# convert-docs.sh
API_KEY="$WAGOE_API_KEY"
TEMPLATE_ID="$WAGOE_TEMPLATE_ID"
BASE_URL="https://your-org.wagoe.com"

for md_file in docs/**/*.md; do
  out_file="${md_file%.md}.docx"
  curl -sS -X POST "$BASE_URL/api/v1/convert" \
    -H "X-API-Key: $API_KEY" \
    -F "md-file=@$md_file" \
    -F "template-id=$TEMPLATE_ID" \
    -F "output-format=docx" \
    -o "$out_file"
  echo "Converted: $md_file → $out_file"
done

3. Wire it into GitHub Actions

name: Generate Documents
on:
  push:
    paths: ['docs/**/*.md']
  schedule:
    - cron: '0 8 * * 1'  # Every Monday at 08:00

jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Convert Markdown to DOCX
        env:
          WAGOE_API_KEY: ${{ secrets.WAGOE_API_KEY }}
          WAGOE_TEMPLATE_ID: ${{ secrets.WAGOE_TEMPLATE_ID }}
        run: ./scripts/convert-docs.sh
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: documents
          path: docs/**/*.docx

Practical use cases

Engineering teams — release notes, RFC documents, incident reports. Authors write in the same Git repo as the code. Documents are generated automatically on tag push.

Consulting firms — client proposals and deliverables. A shared template ensures every document looks identical regardless of which consultant wrote it.

Compliance teams — regular reports that follow a fixed structure. The Markdown source lives in version control with full audit history; the PDF output is generated for each reporting period.

Developer-relations teams — API documentation, tutorials, SDK changelogs. The same Markdown that feeds the developer portal also produces the printable PDF reference.

Multi-user teams

Wagoe Blueprint's Business plan supports up to 25 users per organisation. Admins can:

• Manage who has access to each template
• See per-user conversion usage
• Enforce a single canonical template across the organisation

Individual contributors don't need to know anything about templates or formatting — they write Markdown, the pipeline handles the rest.

Getting started

1. Create a free account
2. Upload your branded .docx template
3. Call the API from your existing CI/CD pipeline

The free tier includes 5 conversions per month to test the workflow. Starter plans start at €5/month for 100 conversions — enough for most small teams.