zkdoc-action vs. zkdoc
Part of the DevTools overview pipeline — this page helps you choose between the cloud action and the on-premises CLI for documentation.
Both tools generate HTML API documentation from TwinCAT PLC source code using DocFX. The difference is where they run and what infrastructure they require.
Feature comparison
| zkdoc-action (cloud) | zkdoc (on-premises) | |
|---|---|---|
| Infrastructure | Zeugwerk CI/CD - no setup required | Your own machine or build server |
| TwinCAT XAE required | No | No |
| OS | Ubuntu runner (managed) | Windows, Linux, or macOS |
| DocFX required | No - handled by the action | Yes - must be installed separately |
| Pipeline support | GitHub Actions, GitLab CI, Bitbucket Pipelines | Any CI that can run a .NET executable |
| Private repositories | Commercial plan | License required |
| Free tier | 30 builds/month for public repositories | - |
| Custom pages | Yes - via doc-folder input |
Yes - place Markdown in userguide/ |
| Custom HTML template | Yes - via doc-folder with custom docfx.json |
Yes - edit docfx.json directly |
| Comment syntax | /// and //< |
/// and //< (identical) |
| Output location | archive/docs/html/ |
Configurable via --output (default: documentation/html/) |
| Visibility filters | Default only | Configurable via --include-internal, --exclude-private, --exclude-protected, --filter |
| Multiple PLCs | Via filepath: '.' and config.json |
Multiple filepath arguments or config.json auto-discovery |
When to use zkdoc-action
- Your source code is hosted on GitHub, GitLab, or Bitbucket.
- You want documentation to build and publish automatically on every push with no local setup.
- Your project is open-source or you are happy with the commercial cloud plan.
- You want to deploy to GitHub Pages with minimal configuration.
When to use zkdoc
- Your code must stay inside your own network (air-gapped, compliance, IP protection).
- You run an on-premises CI/CD system and want to keep documentation builds there too.
- You need fine-grained control over visibility filters, output structure, or the DocFX template.
- You want to generate documentation locally during development and preview it before pushing.
Using both together
Both tools use the same comment syntax (/// and //<) and the same .Zeugwerk/config.json for project discovery, so you can switch between them or run them in parallel without changing your source code. A common pattern is to use zkdoc-action for public API docs on GitHub Pages and zkdoc locally to preview changes before pushing.