zkdoc (zkdoc-action)

One of Zeugwerk’s CI/CD tools for TwinCAT. Keeping PLC docs in sync with code is hard when everything is manual. zkdoc generates HTML API docs from your PLC source -write comments in code, push, and publish (e.g. to GitHub Pages) without running DocFX or zkdoc yourself. zkdoc-action is available for all major Git hosts (GitHub, GitLab, Bitbucket) and runs on our CI/CD. For on-premises or licensed use, see zkdoc. Comment syntax: Syntax reference.

Why use it

Docs from source - API reference and comments stay in sync with code.
Professional output - API docs, examples, and structure in one site.
Low maintenance - Builds on every push; no manual doc updates.
Searchable - Generated site is indexed and searchable.
Deploy anywhere - GitHub Pages, your own server, or any HTTP host.

Quick start

Register - Contact us to register. Public repos get 30 free builds/month.
Add a workflow - The example below is for GitHub; zkdoc-action also works with GitLab CI and Bitbucket Pipelines. Create .github/workflows/docs.yml (or the equivalent in your Git host):

name: Documentation
on:
  push:
    branches: [main, develop]
  workflow_dispatch:
jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate Documentation
        uses: Zeugwerk/zkdoc-action@v1
        with:
          username: ${{ secrets.ZEUGWERK_USERNAME }}
          password: ${{ secrets.ZEUGWERK_PASSWORD }}
          filepath: '.'
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_dir: archive/docs/html

Secrets - Set ZEUGWERK_USERNAME and ZEUGWERK_PASSWORD in GitHub Secrets. For GitHub Pages, configure a deploy key (see peaceiris/actions-gh-pages).
Push - Docs build and deploy on every push (or on manual run).

How it works

Your TwinCAT code (with comments) → Git push → zkdoc-action runs on Zeugwerk CI/CD → PLC source is parsed, comments and symbols extracted, DocFX generates HTML → output is in archive/docs/html. Your workflow can then deploy that folder (e.g. to GitHub Pages).

Writing documentation comments

Use /// above POUs, methods, and declarations, and //< next to variable or enum fields. For the full reference - delimiter rules, \copydoc, cross-references, diagrams, and code formatting - see the Comment syntax reference.

Configuration

Inputs

Input	Required	Description
`username`	Yes	Zeugwerk account username
`password`	Yes	Zeugwerk account password
`filepath`	Yes	Path to `.plcproj` or folder containing `.Zeugwerk/config.json`
`doc-folder`	No	Folder with custom `docfx.json` (e.g. `docs/`)

Outputs

Artifact	Location
HTML docs	`archive/docs/html/`
Build logs	GitHub Actions UI

Filepath

Single PLC - filepath: 'MyPlcProject/MyPlcProject.plcproj'
Zeugwerk / Twinpack projects - filepath: '.' so the action discovers and uses .Zeugwerk/config.json.

Example

struckig: repo, generated docs, workflow.

Output structure

After the action completes, all generated files are placed under archive/docs/ in the workspace:

archive/docs/
├── docfx.json              ← DocFX project file (your custom one if doc-folder is set)
├── toc.yml                 ← Top-level table of contents
├── index.md                ← Landing page
├── reference/              ← Generated API Markdown
│   └── <Namespace>/
│       └── ...
├── userguide/              ← Custom documentation pages (see below)
│   └── ...
└── html/                   ← Final HTML output - deploy this folder
    └── ...

The html/ subfolder (archive/docs/html) is what you publish. The quick-start workflow deploys it to GitHub Pages via publish_dir: archive/docs/html.

Customizing documentation output

For adding custom Markdown pages, adjusting the folder layout, and customizing the DocFX HTML template, see the Customizing documentation output reference. The same options apply to zkdoc.

Pricing

Free - 30 builds/month for public repositories.
Commercial - Custom pricing for private repos. contact us.

Troubleshooting

Docs not generating - Ensure filepath points to a valid .plcproj or a directory with .Zeugwerk/config.json. Check the Actions logs.
GitHub Pages not updating - Verify deploy key and GitHub Pages settings (see peaceiris docs).
Layout or content wrong - Check docfx.json and comment syntax in Syntax reference.

Comparison: zkdoc vs. zkdoc-action

For a full feature-by-feature comparison including guidance on when to choose each tool, see the zkdoc-action vs. zkdoc comparison.

Table of Contents