Documentation

Additional topics

Besides creating documentation of source code that contains structured text, zkdoc also allows the user to add additional content. This content can be provided by custom markdown files (.md) that are organized by using table-of-content Files (toc.yml). Custom topics for the documentation can be added by following these steps.

Folder structure

Create the following folder structure in the root of your repository or if specified in the zkdoc-action, the working directory.

Note

If this folder structure is not present in the repository or the working directory, respectively, zkdoc automatically generates this folder structure.

.
├── documentation
    ├── index.md
    ├── toc.yml
    └── userguide
        ├── introduction.md
        └── toc.yml

Add custom files

Add the following files to your repository. Note that this is only an example to give you an idea on how the markdown files related to the table-of-content files.

./documentation/index.md

Markdown file that should describe your project. Usually this file is similar to github's README.md file.

# Welcome to <projectname>

./documentation/toc.yml

The folder reference is autogenerated by zkdoc and contains all source code documentation for your project. In order to show it on the generated HTML website there has to be a reference to this folder in a toc.yml file.

- name: API Reference
  href: reference/

./documentation/userguide/introduction.md

Markdown for additional content you want to documentate.

# Userguide

./documentation/userguide/toc.yml

Table of content for all markdown files that are located in the userguide/ folder.

- name: Introduction
  href: introduction.md

Customization

zkdoc internally uses DocFX for the final processing step to convert Markdown Files to html. This makes it possible to completely change the output of zkdoc by overwriting the (default) docfx.json file. This includes custom templates as they are described here. Feel free to change the style of the documentation as you like, however, we would appreciate it if you kept the Footer, which references to our website or mention us in another way.

The default content of this file is

./docfx.json

{
  "build": {
    "content": [
      {
        "files": [
          "userguide/toc.yml",
          "userguide/*.md",
          "reference/toc.yml",
          "reference/**/toc.yml",		  
          "reference/**/*.md",
          "toc.yml",
          "*.md"
        ]
      }
    ],
    "dest": "html",
    "fileMetadataFiles": [],
    "template": [
      "statictoc", "template"
    ],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  }
}

The markdown flavor that can be used in custom files is described here.