The zero-config way into the knowledge base. Your repo has one or more markdown files; you add one workflow file and nothing else. No mkdocs, no theme, no manifest to write, no build script, no headless flag — the action derives the manifest from the workflow inputs below.
The reusable action renders your markdown into headless HTML, packs it as
kb-docs.tar.gz, and attaches it to your latest GitHub Release. The knowledge base
picks it up on its next build and gives every doc its own catalog card and URL.
Choosing between the three onboarding types:
Type Use when Cost to your repo single-page You have markdown files, not a docs site one workflow file default (packaged) You have a real static docs site (mkdocs, Starlight…) headless build + kb-docs.json+ release workflow — see HEADLESS_RULES.mdiframe Your docs are already hosted elsewhere and can't be packaged yet an apps.jsonentry — explicit stopgap, see HEADLESS_RULES.md
With an AI agent. The
kb-docs-addskill inskills/kb-docs-add/walks an agent through this page: it picks the type, writes the one workflow file below and nothing else, and knows the fix for every message in Troubleshooting. Install withnpx skills add AbsaOSS/knowledge-base --skill kb-docs-add(Claude Code, GitHub Copilot and otherSKILL.mdreaders). This page stays the normative text.
# .github/workflows/publish-docs.yml in your docs repo
name: Publish docs
on:
release:
types: [published]
workflow_dispatch:
jobs:
publish:
runs-on: ubuntu-latest
permissions:
contents: write # required — the action uploads a release asset
steps:
- uses: actions/checkout@v4
- uses: AbsaOSS/knowledge-base/actions/publish-single-page-docs@v1
with:
docs: |
- md: docs/overview.md
title: Service Overview
description: What the service does and how to use it.
slug: my-serviceThat is the entire onboarding on your side. Multiple docs go in the same list:
docs: |
- md: docs/overview.md
title: Service Overview
description: What the service does and how to use it.
slug: my-service
icon: cube
tags: [platform, api]
- md: RELEASING.md
title: Release Process
description: How a release is cut and published.
slug: my-service-releases
icon: cog| Input | Required | Default | Description |
|---|---|---|---|
docs |
✅ | — | YAML (or JSON) list of doc definitions — see below |
release-tag |
☐ | the triggering release, else the repo's latest | Release to attach kb-docs.tar.gz to |
github-token |
☐ | ${{ github.token }} |
Needs contents: write |
npm-registry |
☐ | — | npm registry to install the action's dependencies from, for runners that cannot reach registry.npmjs.org — see below |
npm-token |
☐ | — | Bearer token for npm-registry |
node-mirror |
☐ | — | Mirror of https://nodejs.org for setup-node, when the runner reaches neither nodejs.org nor github.com release assets |
node-mirror-token |
☐ | — | Authorization header value for node-mirror |
| Field | Required | Rules |
|---|---|---|
md |
✅ | Path to the markdown file, relative to the repo root. Must exist in the checkout. |
title |
✅ | Shown on the catalog card and in the masthead. ≤ 128 characters. |
description |
✅ | One sentence for the catalog card. 10–280 characters. |
slug |
✅ | Lowercase kebab-case (^[a-z0-9]+(-[a-z0-9]+)*$), 2–32 characters. Becomes the public URL /knowledge-base/{slug}/ and must be unique across the whole knowledge base, so prefix it with your service name. |
icon |
☐ | One of book-open, cube, chip, chart-bar, shield, cog, terminal, globe, layers, lightning-bolt, document, collection, puzzle, database. Default book-open. |
tags |
☐ | Up to 5 short strings, shown as pills on the card. |
Validation runs before anything is rendered and reports every problem at once, naming the entry and the fix.
| Output | Description |
|---|---|
slugs |
Comma-separated list of published slugs |
count |
Number of docs in the bundle |
artifact |
Absolute path of the packed kb-docs.tar.gz |
release-tag |
Tag the bundle was uploaded to |
The action attaches the bundle to an existing release — it never creates one. If
the repo has no releases at all the run fails with a message saying so. Trigger
on release: published (as above) and the release is guaranteed to be there.
On GitHub-hosted runners the workflow above is complete. If your job runs on
self-hosted runners that cannot reach registry.npmjs.org — every package has
to come from an internal Artifactory — add the registry to the same step:
- uses: AbsaOSS/knowledge-base/actions/publish-single-page-docs@v1
with:
npm-registry: https://artifactory.example.com/artifactory/api/npm/npm-remote/
npm-token: ${{ secrets.ARTIFACTORY_TOKEN }} # omit for anonymous reads
docs: |
- md: docs/overview.md
…The action's own lockfile names no registry, only versions and integrity
hashes; npm fetches from the registry you name, so the same action ref installs
on both kinds of runner. The setting applies to this install only and
the token is never written to disk. A runner whose own ~/.npmrc already names
the mirror needs neither input.
Node itself comes from actions/setup-node, which tries github.com release
assets and then nodejs.org. If both are blocked and the runner image does not
carry Node 20 in its tool cache, set node-mirror to a mirror of
https://nodejs.org (an Artifactory generic remote) and node-mirror-token if
it needs one.
Open a PR against AbsaOSS/knowledge-base adding one entry to apps.json:
{
"repo": "AbsaOSS/my-service",
"version": "latest"
}Note what is not there: no slug, no name, no description, no icon, no tags, and no type. All of it is read from your manifest, so adding, renaming or removing a doc later never touches the knowledge base repo again — publish a new release and the next knowledge-base build picks it up. It is also the same entry a packaged docs site gets: the registry records where an artifact comes from, nothing more.
version accepts latest (default) or a pinned tag such as v1.4.0.
GitHub-flavoured markdown, rendered by markdown-it:
- tables, task lists, strikethrough, footnotes
- bare URLs autolinked; external links get
target="_blank" rel="noopener noreferrer" - heading anchors on
h1–h4 - syntax-highlighted fenced code (highlight.js) on the slate code surface from STYLE_GUIDE.md
```mermaidblocks, rendered client-side from a vendored mermaid bundle
Mermaid is vendored into the artifact rather than loaded from a CDN: knowledge base pages are re-hosted inside a web fragment behind a strict CSP, so every asset a doc needs must live in its own artifact. If the script never runs, the diagram source stays visible rather than disappearing.
If your markdown has no top-level # heading, the action synthesises one from
title plus description. If it has one, nothing is injected.
Markdown may contain raw HTML, as GitHub-flavoured markdown allows. It is put through an allowlist before it is packed into the artifact, because your rendered doc is re-hosted on the knowledge base's own origin alongside every other team's docs — anything that executes there executes against all of them.
Kept: the structural and inline elements the doc stylesheet renders —
headings, paragraphs, lists, tables, details/summary, figure, blockquote,
pre/code, img, a, label, emphasis and the rest of the usual inline set,
along with their class and id attributes.
Dropped, with the inner text kept where there is any:
| Removed | Why |
|---|---|
<script> |
Would run on the knowledge base origin |
on* attributes (onclick, onerror, …) |
Same |
<style> and style="…" |
CSS can exfiltrate via url() and can cover the knowledge base masthead |
<iframe>, <object>, <embed> |
Arbitrary embedded documents |
<form> and form controls (except task-list checkboxes) |
Credential-phishing surface |
javascript: and data: URLs |
Script execution by another name |
If you need something that is currently dropped and it is genuinely inert, open
an issue — the allowlist lives in actions/publish-single-page-docs/src/sanitize.js
and is asserted by the action's self-test.
There is no way to opt out. A doc that depends on inline scripting is not a single-page doc; package it as a full static site instead (see HEADLESS_RULES.md).
kb-docs.tar.gz unpacks to a kb-docs.json manifest plus one directory per doc:
kb-docs.json
my-service/
index.html
assets/doc.css
assets/mermaid.min.js ← only when that doc uses mermaid
assets/mermaid-init.js ← ditto; kept out of the HTML so the knowledge base
can serve script-src 'self'
my-service-releases/
index.html
assets/doc.css
{
"kbVersion": "1",
"apps": [
{
"slug": "my-service",
"name": "Service Overview",
"description": "What the service does and how to use it.",
"icon": "cube",
"tags": ["platform", "api"],
"entryPoint": "index.html"
}
]
}Your title becomes the app's name; everything else carries over as you wrote
it. One entry per doc.
This is the same manifest a packaged documentation site publishes, specified in
ARTIFACT.md and validated against
kb-docs.schema.json. There is no separate single-page
format: a set of markdown docs is a manifest listing several apps, a docs site is
a manifest listing one, and the knowledge base reads both the same way.
Each index.html satisfies HEADLESS_RULES.md:
data-kb-headless="true"on<html>- no
<base>tag, every asset path relative - no site-level
<header>, no sidebar, no theme toggle - light only — no dark palette, no
localStoragetheme bootstrap
The body is a single <article class="kb-doc">. All prose styling lives in
assets/doc.css, scoped to .kb-doc, so nothing leaks into the masthead or into
a host application when the page is embedded as a web fragment.
The knowledge base expands one single-page registry entry into one app per doc,
then renders each in its own reading column:
<main id="content" class="kb-single-page">
<article class="kb-doc"> … </article>
</main>.kb-single-page (in src/styles/knowledge-base.css) owns the measure — ~800px of
content, centred, with generous vertical rhythm — so every single-page doc reads
identically regardless of which repo published it. The persistent masthead is the
only navigation; there is no sidebar and no in-app chrome.
| Symptom | Cause |
|---|---|
has no GitHub Release to attach the docs bundle to |
The repo has no releases. Create one, or pass release-tag. |
md "…" does not exist in the repository |
Wrong path, or actions/checkout is missing from the job. |
slug "…" is invalid |
Slugs are lowercase kebab-case only — no underscores, capitals or spaces. |
Duplicate app slug "…" (knowledge-base build) |
Another registered app already owns that URL prefix. Rename yours and republish. |
the release artifact has no kb-docs.json at its root |
The release's kb-docs.tar.gz was not produced by this action. |
npm error … ENOTFOUND registry.npmjs.org or a 403 from a proxy at Install publisher dependencies |
The runner cannot reach the public registry. Set npm-registry (and npm-token) to your internal mirror. |
Unable to find Node version / a download error at Set up Node.js |
The runner reaches neither github.com release assets nor nodejs.org. Set node-mirror, or preinstall Node 20 in the runner's tool cache. |
-
.github/workflows/publish-docs.ymladded, withpermissions: contents: write - Every
slugis lowercase kebab-case and prefixed with your service name - Each
descriptionis 10–280 characters - The workflow ran and
kb-docs.tar.gzis attached to the release - A PR adds the
{ "repo": … }entry toapps.json