Skip to content

[kb-docs] docs: document knowledge-base v1.3.1 #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
github-actions wants to merge 1 commit into
base: master
Choose a base branch
from
+1,480 −44
Draft

[kb-docs] docs: document knowledge-base v1.3.1 #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .kb-sync/features.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
# `synced` is empty until the first full run documents a release.

synced:
tag: null
sha: null
tag: v1.3.1
sha: f95eb35b47051b66fb0154319780aefe4431ba17

# Upstream paths that never carry user-facing behaviour; changes here are ignored.
ignore:
Expand Down
77 changes: 39 additions & 38 deletions data/showcase.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,14 @@ content: |
<path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20"/>
<path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z"/>
</svg>
<span class="sc-nav__title">Docs Example</span>
<span class="sc-nav__title">Knowledge Base</span>
</a>
<div class="sc-nav__links">
<a href="docs/" class="sc-nav__link">Overview</a>
<a href="docs/customising/" class="sc-nav__link">Customising</a>
<a href="docs/adding-pages/" class="sc-nav__link">Adding Pages</a>
<a href="docs/" class="sc-nav__cta">Read the Docs</a>
<a href="docs/kb/onboarding/" class="sc-nav__link">Publish Your Docs</a>
<a href="docs/kb/registry/" class="sc-nav__link">Run a Knowledge Base</a>
<a href="docs/kb/embedding/" class="sc-nav__link">Embed</a>
<a href="docs/" class="sc-nav__cta">Read the Guide</a>
</div>
</nav>
<!-- ── /Navigation ── -->
Expand All @@ -27,68 +28,68 @@ content: |
<section class="sc-hero" aria-label="Hero">
<div class="sc-hero__bg" role="presentation"></div>
<div class="sc-hero__content">
<span class="sc-hero__eyebrow">MkDocs Template</span>
<span class="sc-hero__eyebrow">User Guide</span>
<h1 class="sc-hero__title">
Publish your docs to the<br>
<span>Knowledge Base</span>
One portal for all<br>
<span>your documentation</span>
</h1>
<p class="sc-hero__sub">A minimal, branded template. Clone it, write Markdown, tag a release — your documentation is live.</p>
<p class="sc-hero__sub">The Knowledge Base collects documentation from every team's repository into a single branded portal. Publish from a Markdown file or a full docs site, run the portal yourself, or embed it in your app.</p>
<div class="sc-hero__actions">
<a href="docs/" class="sc-btn sc-btn--primary">Read the Docs</a>
<a href="#" class="sc-btn sc-btn--outline">Full User Guide</a>
<a href="docs/kb/onboarding/" class="sc-btn sc-btn--primary">Publish your docs</a>
<a href="docs/" class="sc-btn sc-btn--outline">Read the Guide</a>
</div>
</div>
</section>

<!-- ── Features ── -->
<section aria-label="What is included">
<div class="sc-section">
<p class="sc-section__label">What is included</p>
<h2 class="sc-section__title">Everything you need, nothing you don't</h2>
<p class="sc-section__sub">The template ships with a pre-built theme, a build script, and a CI/CD pipeline. You only ever touch your content and configuration.</p>
<p class="sc-section__label">What it does</p>
<h2 class="sc-section__title">Publish, run and embed</h2>
<p class="sc-section__sub">Teams keep their docs in their own repositories. The Knowledge Base aggregates them at build time into one static site.</p>

<div class="sc-features">
<div class="sc-feature-card">
<div class="sc-feature-card__icon">
<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20"/><path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z"/></svg>
</div>
<h3 class="sc-feature-card__title">Markdown-first content</h3>
<p class="sc-feature-card__text">Write in plain Markdown. MkDocs builds it into polished HTML — no HTML knowledge needed.</p>
<h3 class="sc-feature-card__title">Three ways to publish</h3>
<p class="sc-feature-card__text">Single-page docs from Markdown with one workflow file, a packaged static site, or an iframe stopgap for docs hosted elsewhere.</p>
</div>
<div class="sc-feature-card">
<div class="sc-feature-card__icon">
<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/></svg>
</div>
<h3 class="sc-feature-card__title">Zero build setup</h3>
<p class="sc-feature-card__text">Run <code>npm run build</code> and you're done. The script installs dependencies, builds the docs, and packages the artefact.</p>
<h3 class="sc-feature-card__title">A checked contract</h3>
<p class="sc-feature-card__text">Every requirement has a rule ID. Run the checker locally, on pull requests with <code>check-docs</code>, and on every release.</p>
</div>
<div class="sc-feature-card">
<div class="sc-feature-card__icon">
<svg viewBox="0 0 24 24" aria-hidden="true"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>
</div>
<h3 class="sc-feature-card__title">Branded theme</h3>
<p class="sc-feature-card__text">Pre-built CSS with a customisable colour palette and typography. Theme files stay untouched.</p>
<h3 class="sc-feature-card__title">Run your own</h3>
<p class="sc-feature-card__text">A reusable build workflow, a hardened nginx image and a deployment-repo pattern, including private networks and mirrors.</p>
</div>
<div class="sc-feature-card">
<div class="sc-feature-card__icon">
<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg>
</div>
<h3 class="sc-feature-card__title">Headless &amp; standalone modes</h3>
<p class="sc-feature-card__text">Build a standalone site or a headless fragment that slots directly into the knowledge base chrome.</p>
<h3 class="sc-feature-card__title">Embed anywhere</h3>
<p class="sc-feature-card__text">Serve the portal as a web fragment inside a host app, with no page reloads and no third-party requests.</p>
</div>
<div class="sc-feature-card">
<div class="sc-feature-card__icon">
<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="3"/><path d="M19.07 4.93a10 10 0 0 1 0 14.14M4.93 4.93a10 10 0 0 0 0 14.14"/></svg>
</div>
<h3 class="sc-feature-card__title">CI/CD pipeline included</h3>
<p class="sc-feature-card__text">A GitHub Actions workflow builds and packages your docs on every tagged release — just push and go.</p>
<h3 class="sc-feature-card__title">Release-driven</h3>
<p class="sc-feature-card__text">Publish a GitHub Release and the action attaches <code>kb-docs.tar.gz</code>. The portal picks it up on its next build.</p>
</div>
<div class="sc-feature-card">
<div class="sc-feature-card__icon">
<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/></svg>
</div>
<h3 class="sc-feature-card__title">Expandable structure</h3>
<p class="sc-feature-card__text">Add Markdown pages or standalone HTML pages at any time. Navigation updates automatically from page frontmatter.</p>
<h3 class="sc-feature-card__title">Docs Template</h3>
<p class="sc-feature-card__text">This guide is built with the MkDocs Docs Template: clone it, write Markdown, tag a release.</p>
</div>
</div>
</div>
Expand All @@ -99,29 +100,29 @@ content: |
<section aria-label="How it works">
<div class="sc-section">
<p class="sc-section__label">How it works</p>
<h2 class="sc-section__title">From clone to live docs in three steps</h2>
<p class="sc-section__sub">No framework expertise required. The template is designed for teams who want to focus on content, not tooling.</p>
<h2 class="sc-section__title">From repo to portal in three steps</h2>
<p class="sc-section__sub">The same path works for a Markdown file or a full docs site.</p>

<div class="sc-steps">
<div class="sc-step">
<div class="sc-step__num">1</div>
<div>
<p class="sc-step__title">Clone and configure</p>
<p class="sc-step__text">Clone this repo, update <code>kb-docs.json</code> with your <code>slug</code> and <code>name</code>, and set <code>site_name</code> in <code>mkdocs.yml</code>. That's the only configuration you need.</p>
<p class="sc-step__title">Pick a type</p>
<p class="sc-step__text">Add one workflow for single-page docs, or make your site's build headless and describe it in <code>kb-docs.json</code>.</p>
</div>
</div>
<div class="sc-step">
<div class="sc-step__num">2</div>
<div>
<p class="sc-step__title">Write your content</p>
<p class="sc-step__text">Replace the starter Markdown files in <code>docs/</code> with your own content. Add pages by creating <code>.md</code> files — navigation is generated automatically from frontmatter.</p>
<p class="sc-step__title">Publish a release</p>
<p class="sc-step__text">The publish action validates your docs against the contract rules and attaches <code>kb-docs.tar.gz</code> to the release.</p>
</div>
</div>
<div class="sc-step">
<div class="sc-step__num">3</div>
<div>
<p class="sc-step__title">Tag a release</p>
<p class="sc-step__text">Push a version tag (e.g. <code>v1.0.0</code>). The GitHub Actions workflow builds your docs, packages them, and attaches the artefact to the release — ready for the knowledge base to consume.</p>
<p class="sc-step__title">Register</p>
<p class="sc-step__text">Open a PR adding <code>{ "repo": "owner/name" }</code> to the deployment's registry. Everything else is read from your manifest.</p>
</div>
</div>
</div>
Expand All @@ -132,20 +133,20 @@ content: |
<!-- ── CTA banner ── -->
<section class="sc-cta" aria-label="Call to action">
<h2 class="sc-cta__title">Ready to publish your documentation?</h2>
<p class="sc-cta__sub">Read the template docs to get started, or visit the full user guide for setup and registration.</p>
<p class="sc-cta__sub">Start with the onboarding guide, or read how to run and embed the Knowledge Base.</p>
<div class="sc-cta__actions">
<a href="docs/" class="sc-btn sc-btn--light">Get Started</a>
<a href="#" class="sc-btn sc-btn--ghost">Full User Guide</a>
<a href="docs/kb/onboarding/" class="sc-btn sc-btn--light">Get Started</a>
<a href="docs/" class="sc-btn sc-btn--ghost">Full User Guide</a>
</div>
</section>

<!-- ── Footer ── -->
<footer class="sc-footer">
<span>Knowledge Base Docs Example &mdash; MkDocs Template</span>
<span>Knowledge Base User Guide &mdash; built with the Docs Template</span>
<span>
<a href="docs/">Docs</a>
&ensp;&middot;&ensp;
<a href="#">Knowledge Base</a>
<a href="docs/kb/how-it-works/">How it works</a>
</span>
</footer>

Expand Down
12 changes: 8 additions & 4 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,19 @@ At build time it:
4. Produces a single static `dist/`, served by nginx in Docker or embedded into a
host application as a web fragment.

The output makes no third-party requests at runtime.
The output makes no third-party requests at runtime. This guide describes release
**v1.3.1**.

## Who this guide is for

| You want to… | Start with |
|---|---|
| Publish your team's documentation to the Knowledge Base | Publishing your docs |
| Run your own Knowledge Base deployment | Running a Knowledge Base |
| Embed the Knowledge Base inside a host application | Embedding |
| Understand how the portal works and what readers see | [How it works](kb/how-it-works.md) |
| Publish your team's documentation to the Knowledge Base | [Choosing how to onboard](kb/onboarding.md) |
| Check your docs against the contract | [Contract rules and the checker](kb/rules.md) |
| Run your own Knowledge Base deployment | [Registry](kb/registry.md), [Building](kb/building.md), [Deployment](kb/deployment.md) |
| Embed the Knowledge Base inside a host application | [Web fragment embedding](kb/embedding.md) |
| Let an AI agent onboard a repo | [Agent skill](kb/agent-skill.md) |
| Start a new docs site quickly | [Using the Docs Template](template.md) |

## About this site
Expand Down
102 changes: 102 additions & 0 deletions docs/kb/actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
title: GitHub Actions
order: 25
section: Publish Your Docs
---

# GitHub Actions

Three reusable composite actions live in `AbsaOSS/knowledge-base/actions/`. They share
one pinned dependency tree, so your repo needs no toolchain, `package.json` or lockfile
for them. They run on Node 20.

All three also take `npm-registry`, `npm-token`, `node-mirror` and `node-mirror-token`
for runners without public internet; see [Private networks](private-networks.md).

## publish-docs

Validates a built headless site against the [contract](rules.md), packs
`kb-docs.tar.gz`, and attaches it to a release (replacing an existing asset of that
name).

```yaml
- uses: AbsaOSS/knowledge-base/actions/publish-docs@v1
with:
manifest: kb-docs.json
dist: dist
```

| Input | Required | Default | Description |
|---|---|---|---|
| `manifest` | no | `kb-docs.json` | Path to the manifest, relative to the workspace. |
| `dist` | no | `dist` | The built headless output. With one app, that app's directory; with several, a directory holding one subdirectory per slug. |
| `release-tag` | no | triggering release, else the latest | Release to attach to. |
| `github-token` | no | `{% raw %}${{ github.token }}{% endraw %}` | Needs `contents: write`. |
| `notify-repo` | no | empty | `owner/name` of a deployment repo to notify after publishing. Needs `notify-token`; skipped silently if either is unset. |
| `notify-token` | no | empty | Token with `contents: write` on `notify-repo` only. The default token cannot dispatch to another repository. |
| `npm-registry`, `npm-token`, `node-mirror`, `node-mirror-token` | no | empty | See [Private networks](private-networks.md). |

| Output | Description |
|---|---|
| `slugs` | Comma-separated slugs published. |
| `count` | Number of apps in the artifact. |
| `artifact` | Absolute path of the packed `kb-docs.tar.gz`. |
| `release-tag` | Tag of the release it was uploaded to. |

With `notify-repo` and `notify-token` set, a successful publish fires a
`repository_dispatch` of type `kb-docs-published` carrying `{ repo, tag, slugs }` at the
deployment repo, so it rebuilds without waiting for its schedule. A failed notify never
fails the publish. See [Deployment](deployment.md#rebuilding-when-a-docs-repo-publishes).

## check-docs

Runs the same checks on a pull request without packing or uploading anything. Findings
are annotated by rule ID and summarised on the run. Add it next to the publish workflow
with the same build step and `dist`.

```yaml
on: pull_request

jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm run build -- --headless
- uses: AbsaOSS/knowledge-base/actions/check-docs@v1
with:
manifest: kb-docs.json
dist: dist
```

| Input | Required | Default | Description |
|---|---|---|---|
| `manifest` | no | `kb-docs.json` | Path to the manifest. |
| `dist` | no | `dist` | The built headless output, as for `publish-docs`. |
| `strict` | no | `false` | `"true"` also fails on warnings. Errors always fail. |
| `npm-registry`, `npm-token`, `node-mirror`, `node-mirror-token` | no | empty | See [Private networks](private-networks.md). |

| Output | Description |
|---|---|
| `errors` | Number of error findings. |
| `warnings` | Number of warning findings. |

## publish-single-page-docs

Renders Markdown into headless HTML and publishes it. See [Single-page docs](single-page.md).

| Input | Required | Default | Description |
|---|---|---|---|
| `docs` | yes | — | YAML or JSON list of doc definitions (`md`, `title`, `description`, `slug`, optional `icon`, `tags`). |
| `release-tag` | no | triggering release, else the latest | Release to attach to. |
| `github-token` | no | `{% raw %}${{ github.token }}{% endraw %}` | Needs `contents: write`. |
| `npm-registry`, `npm-token`, `node-mirror`, `node-mirror-token` | no | empty | See [Private networks](private-networks.md). |

Outputs: `slugs`, `count`, `artifact`, `release-tag`, as for `publish-docs`.

## Versioning

Pin to the floating major tag (`@v1`), not a branch. Pushing a `vMAJOR.MINOR.PATCH`
tag moves the major tag to it. A breaking contract change is a new major (`@v2`) with a
`kbVersion` bump, so repos pinned to `@v1` keep publishing against the contract they
were written for.
51 changes: 51 additions & 0 deletions docs/kb/agent-skill.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
---
title: Agent skill
order: 27
section: Publish Your Docs
---

# The `kb-docs-add` agent skill

An agent skill that onboards a repo's docs for you. It follows the open `SKILL.md`
format, so it works in Claude Code, GitHub Copilot and other readers.

## Install

```bash
# interactive
npx skills add AbsaOSS/knowledge-base --skill kb-docs-add

# non-interactive, project scope, named agents
npx skills add AbsaOSS/knowledge-base --skill kb-docs-add -a claude-code -a github-copilot -y

# user scope
npx skills add AbsaOSS/knowledge-base --skill kb-docs-add -g
```

Or copy the directory by hand:

| Agent | Project | Personal |
|---|---|---|
| Claude Code | `.claude/skills/kb-docs-add/` | `~/.claude/skills/kb-docs-add/` |
| GitHub Copilot | `.github/skills/kb-docs-add/` | `~/.copilot/skills/kb-docs-add/` |
| Open spec | `.agents/skills/kb-docs-add/` | `~/.agents/skills/kb-docs-add/` |

Then ask the agent to "add this repo's docs to the knowledge base".

## Modes

**Onboard.** It classifies the repo and writes the minimum:

| It finds | Type | It writes |
|---|---|---|
| Markdown files, no site generator | single-page | one workflow file |
| A docs site (MkDocs, Starlight, Docusaurus, Jekyll…) | packaged | `kb-docs.json`, the smallest change to make the build headless, one workflow file |
| Docs hosted elsewhere | iframe | nothing; it explains the registry entry |

It pins actions to `@v1`, checks slugs and descriptions against the limits, and tells
you the two steps only you can do: publish a release and register the repo.

**Audit.** For a repo that is already onboarded, it runs the contract checker from a
scratch clone of the Knowledge Base, fixes each finding by [rule ID](rules.md) at its
source (never in built output, never in a third-party theme), and reports what the
checker cannot see, such as URLs built at runtime.
Loading