Customizing documentation output

Both zkdoc (on-premises) and zkdoc-action (cloud) use DocFX for the final HTML build. This page explains how to add custom pages and control the output.

---

Adding custom documentation pages

By default, both tools generate a skeleton userguide/ folder with placeholder files alongside the generated API reference. You can add your own Markdown pages to this folder and they will appear in the HTML output next to the API reference.

Folder layout

The default docfx.json expects the following layout:

documentation/
├── index.md                <- project overview / landing page
├── toc.yml                 <- add entries here to surface your pages
└── userguide/
    ├── introduction.md
    ├── my-guide.md
    └── toc.yml             <- list your pages here

toc.yml example:

- name: Introduction
  href: introduction.md
- name: Getting started
  href: my-guide.md

Using a custom folder with zkdoc-action

Create a documentation folder in your repository (e.g. docs/) and pass it via the doc-folder input:

- name: Generate Documentation
  uses: Zeugwerk/zkdoc-action@v1
  with:
    username: ${{ secrets.ZEUGWERK_USERNAME }}
    password: ${{ secrets.ZEUGWERK_PASSWORD }}
    filepath: '.'
    doc-folder: docs

Place your Markdown files in docs/userguide/ and list them in docs/userguide/toc.yml. If docs/docfx.json exists, the action uses it instead of the generated default.

Using a custom folder with zkdoc

Pass the folder path via --docfx:

zkdoc --docfx docs --output documentation MyProject.plcproj

zkdoc will use docs/docfx.json if present; otherwise it generates a default one that you can edit in place.

---

Customizing the HTML output

Because docfx.json is preserved across runs you can adjust it freely:

• Replace or extend the DocFX template — add custom CSS, JavaScript, or layouts.
• Add a globalMetadata section for a site-wide title, footer text, and logos.
• Configure search, table-of-contents depth, and output paths.

See the DocFX documentation for the full template reference.

Default docfx.json generated by zkdoc

{
  "build": {
    "content": [
      {
        "files": [
          "reference/**.md",
          "reference/**/toc.yml"
        ]
      },
      {
        "files": [
          "userguide/*.md",
          "userguide/toc.yml",
          "toc.yml",
          "*.md"
        ]
      }
    ],
    "resource": [
      { "files": ["images/**"] }
    ],
    "dest": "html",
    "template": ["default", "modern", "template", "statictoc"],
    "markdownEngineName": "markdig"
  }
}