Overview

What it does for you

Knowledge Base publishes portfolio-wide help articles that visitors can browse and search. It is managed by global administrators, not by site-scoped editors. Build the collection structure first, then create articles within it.

This access boundary is based on whether the account is a global actor. The package does not define separate article or collection permission grants, and giving historical Knowledge Base permissions to a site-scoped account does not reveal the resources.

Create collections

Go to Knowledge base → Collections. Give each collection a title, slug, optional key and description, then set its parent and sort order when it belongs in a hierarchy. Use Visibility to decide whether the collection is public.

Articles in a private collection are not included in public knowledge-base navigation, search documents, or AI-readable output even if those articles are published.

Collection visibility does not inherit through the hierarchy. Check every child collection explicitly. A public child beneath a private parent is omitted from the navigation tree because its parent is absent, but its articles can still appear through their direct URLs, search documents, and AI-readable output.

Create and publish articles

Open Articles and select a collection. Add the title, optional slug and summary, required body, version label, search weight, and AI-readable setting. New articles default to Draft; choose Published when the current article version should be publicly available, or Archived to remove it from public output.

Public visibility requires all of the following:

• the article is Published;
• it has a current version and publication date; and
• its collection is public.

Use a higher Search weight for an article that should rank ahead of other knowledge-base results. Turn off AI readable when a public article should not be included in the package’s AI-readable knowledge output.

Every article save creates a new version and makes it the current version; the edit form proposes the next vN label. Saving with Published publishes that version immediately. Saving a currently published article as Draft or Archived removes the whole article from current public output rather than keeping the previous published version live. The older version remains in history, but the resource has no restore or republish action for it.

Article bodies are stored as plaintext HTML. Dangerous elements and event handlers are stripped at the public render boundary, not removed from the stored version. Do not put secrets in draft, archived, or private content merely because visitors cannot route to it.

Changing a collection or article slug changes its public URL. Knowledge Base does not create a redirect for the old path, so arrange one separately before changing a live slug. Public index, article, and AI-output responses allow five minutes of caching plus five minutes of stale revalidation; browser or CDN copies can briefly outlive an admin change.

Review article history and related help

Saving an article creates a version. The Versions relation shows the version label, title, current-version marker, and publication/creation dates; it is an audit view rather than an editor for old versions.

Use Related articles to link another article, select a relation type, and set its order. Related links are shown only when the related article also meets the public-visibility rules.

Relations are directional: linking B from A does not link A from B. The current public template uses the sort order but presents every relation type under the same Related articles heading.

Public routes and AI-readable output

The package exposes its index at /docs, articles below /docs/{collection}/{article}, and a public plain-text AI feed at /docs/llms.txt by default. An integrator can change the prefix or disable all package routes. The AI readable toggle affects the public AI feed only; it does not make an otherwise published article private or remove it from normal search documents.

The package ships a basic public view, but it does not add links to the site’s main navigation. Configure theme navigation and any wider search presentation separately.

Seed the demo

The demo command accepts Sites and Languages options for compatibility with portable Capell demo runners. Knowledge Base content is portfolio-wide and its records are not site- or language-scoped, so those options are deliberate no-ops: they do not filter or duplicate the seeded collections, articles, relations, or feedback. Use Force when a repeat run should restore the shipped semantic content; repeat runs keep the existing records and counts stable.

Feedback, privacy, and retention

• The public feedback endpoint accepts helpful/not-helpful votes and an optional comment of up to 2,000 characters. It is CSRF-exempt and rate-limited to 30 requests per minute by default, with no moderation queue.
• Visitor IP addresses and user agents are stored as salted SHA-256 hashes rather than raw values. Comments, votes, article bodies, and versions are not encrypted by this package.
• A repeat vote from the same IP hash for the same article version updates the existing row and comment. People sharing an outward-facing IP can therefore overwrite one another’s vote, while requests without an identifier are not deduplicated.
• The article list shows totals and helpful rate only. Individual feedback comments are not exposed in the current admin resource, so reviewing or exporting them requires an operational data workflow outside this screen.
• capell:knowledge-base:prune permanently deletes feedback older than 365 days by default. It also deletes versions older than that cutoff beyond the newest 20 per article, never deletes the current version, and processes at most 500 surplus versions per article on one run.
• The manifest declares that command as a daily job, but the package does not currently register it with Laravel’s scheduler. Add the command to the host schedule and keep Laravel’s scheduler running; large version histories may need repeated runs.

Good to know

• Article slugs must be unique within a collection. Collection slugs and keys are unique across the knowledge base.
• The public article body is sanitised, and public payloads omit authoring identifiers and raw visitor details.

---

For how to use Knowledge Base, see the admin guide. For developers: see the README.