Repository settings

Reference Configuration basic

On this page

Required
Optional
Markdown
Search
Page metadata
Feed
Theme settings

Each knowledge base has its settings in config/repo.json. kb4it create writes a complete one for the theme you chose.

{
    "title": "Ops Knowledge Base",
    "tagline": "Runbooks, incidents and changes",
    "theme": "techdoc",
    "source": "source",
    "target": "target"
}

Required

Key	Meaning
`title`	Name of the site, shown in the header and the browser tab
`theme`	Theme name, see Themes
`source`	Folder with the documents
`target`	Folder where the website is written

A missing key stops the build with CONFIG_KEY_MISSING key=....

source and target are relative to the knowledge base folder, the one that holds config/. Absolute paths, ~ and $VARIABLES also work.

KB4IT removes from target the pages of documents you deleted. It only removes pages it wrote itself, so other files you keep in target stay; still, target must be a folder of its own. The build stops with an error when target is the knowledge base folder, source, config/, var/, your home folder or a filesystem root, when it holds any of them, or when it lies inside source.

Optional

Key	Default	Meaning
`tagline`		Short subtitle
`logo`, `logo_alt`	theme logo	Logo image, relative to the website, and its text for screen readers; empty uses the site `title`. The logo is also the favicon of every page; without `logo`, the page uses the theme's own logo
`workers`	half the processor cores	Documents converted at the same time
`force`	`false`	Rebuild everything on every build, like `--force`
`ignored_keys`	`[]`	Properties that get no pages; see properties
`publish_sources`	`true`	Copy the `.md` files to the website, in `target/sources/`
`fail_on_invalid`	`false`	Stop the build when a document cannot be read
`theme_path`		Use the theme in this folder instead of searching by name
`site_url`		Public address of the site, such as `https://me.github.io/kb/`. Needed for `sitemap.xml`, the feed and canonical links; changing it rebuilds every page
`og_image`		Image shown when a page is shared on social networks, a path inside the website such as `resources/share.png`; needs `site_url`
`sitemap`	`true`	With `site_url`, write `sitemap.xml` and `robots.txt`; a `robots.txt` in `source/` is used instead of the generated one
`backlinks`	`true`	At the end of each document, list the documents that link to it ("Linked from"); `false` hides the list
`feed`	blog: on; techdoc, bookshelf: off	Atom feed `feed.xml`, see feed
`hooks`		Python file with build hooks, such as `hooks/hooks.py`; see Run your own code during a build
`overrides`	`overrides`	Folder with templates and files that replace or extend the theme's; see Change one template of a theme
`search`	`true`	Full-text search in techdoc, blog and bookshelf; `false` removes the search box, `search.html` and `search-index.js`. See search
`git`, `git_server`, `git_user`, `git_repo`, `git_branch`, `git_path`	`false`	Edit links to your git server; see each theme for the format. They appear only with `"git": true` and `git_server`, `git_user`, `git_repo` and `git_branch` all set; `git_path` may stay empty

Markdown

The optional markdown block adds python-markdown extensions to the built-in ones (extra, admonition, toc, sane_lists).

"markdown": {
    "extensions": ["pymdownx.tasklist", "pymdownx.details", "nl2br"],
    "extension_configs": {
        "pymdownx.tasklist": {"custom_checkbox": true}
    }
}

Key	Default	Meaning
`extensions`	`[]`	Extension names, as python-markdown expects them. Extensions that ship with python-markdown work right away; others must be installed where KB4IT runs
`extension_configs`	`{}`	Settings per extension
`highlight`	`client`	How code blocks are coloured: `client` (highlight.js in the browser, as before), `pygments` (at build time, no JavaScript), or `none`
`pygments_style`	`default`	Pygments style for light colour schemes, with `pygments`
`pygments_style_dark`	`monokai`	Pygments style for dark colour schemes, with `pygments`
`sanitize`	`false`	`true` removes scripts, event handlers, `javascript:` links and any other markup Markdown does not make from each document. Needs nh3, part of the extras. See Raw HTML

With "highlight": "pygments" the build writes resources/pygments.css, and the pages no longer load highlight.js. Code blocks without a language are left plain.

With pymdownx.superfences (or pymdownx.highlight), code blocks follow highlight too: KB4IT sets use_pygments of pymdownx.highlight to true only in pygments mode, so in client mode highlight.js colours them. A use_pygments of your own in extension_configs wins.

Changing the block rebuilds every page. An extension that is not installed stops the build with MD_EXTENSION_MISSING name=... hint=pip install ...; kb4it verify reports it too.

The PyMdown Extensions (task lists, tabs, details, keys and more) install with KB4IT when you ask for its extras: uv tool install "KB4IT[extras]" or pipx install "KB4IT[extras]". The extras also bring nh3, which sanitize needs.

Search

techdoc, blog and bookshelf build search-index.js with the text of every document, split by section, and a search.html page. Search runs in the browser, so it also works when you open the site from disk. Results link to the section that matched.

The index grows with your documents; above 5 MB the build warns with [SEARCH] INDEX_LARGE. Turn it off with "search": false. apphelp has its own search, configured in its apphelp block.

Page metadata

Every page gets a short description and Open Graph tags, so links shared in chats and social networks show a title and a summary. The description is the document's Summary property, or its first lines cut to 160 characters; pages that are not documents use tagline. With site_url set, each page also gets a canonical link and its full address, and og_image adds a preview image.

The tags come from the template HTML_HEAD_META.tpl, which a theme can replace.

Feed

With site_url set, the blog theme writes an Atom feed, feed.xml, with the newest dated documents. techdoc and bookshelf write one when you turn it on:

"feed": {"enabled": true, "limit": 20, "categories": ["Post", "Note"], "full_content": true}

Key	Default	Meaning
`enabled`	blog `true`, others `false`	Write the feed
`limit`	`20`	Number of entries, newest first
`categories`	all	Only documents with one of these `Category` values
`full_content`	`true`	The whole document in each entry; `false` uses `Summary` or the first lines

Documents without a Date are not in the feed.

Theme settings

Each theme reads its own keys as well:

techdoc: datatable, events, admin
blog: index_posts, strict, datatable
bookshelf: datatable
apphelp: the apphelp block and version

version is the version of the application the help describes. apphelp shows it on the home page, next to the pages new in that version, and uses it to name the folder of each version; see versions. The value "kb4it" stands for the version of the installed KB4IT. The other themes ignore it.

Sample apps from older versions also contain menu, sort, timeline and webserver. KB4IT no longer reads them; you can leave them or delete them.

Linked from