Knowledge documents

The assistant answers only from your documents: Markdown files, written in Markdoc, that you upload, write in the dashboard, crawl from your site or sync from your repository.

Front matter

A document may start with a front matter block. Headings of levels 1 to 3 split it into sections, the parts the assistant reads and points people to.

docs/reports/export.md

---
title: Exporting a report
about: How to export a report as CSV or PDF, and what to do when an export fails.
tags: [reports, exports]
---

## Export a report

Open the report, choose Export, then CSV or PDF.

## When an export fails

Exports over 10,000 rows run in the background and arrive by email.

Key	What it does
title	The document's title. Without it, the first level 1 heading, else the file name.
about	One line on what the document covers, which the assistant reads before choosing it. description works too.
tags	Up to 10 topic tags, in lower case, which group documents on the Knowledge page and in your help centre.
access	The roles that may read the whole document. Absent or empty, it is public.

Access by role

access in the front matter limits a whole document, and the {% access %} tag limits the part of it that it wraps. Either is a list of roles, any one of which is enough. The assistant reads a limited part only for people whose signed identity carries one of its roles (Identity signing); for everyone else it does not exist, and it never appears in your public help centre.

docs/billing/invoices.md

---
title: Invoices and payment methods
access: [billing, admin]
---

Invoices are under Settings, then Billing.

{% access roles=["owner"] %}

## Refunds over $1,000

Owners approve them from the invoice.

{% /access %}

Sync from CI

Keep your documents in your repository and send them on every build with syncDocuments() from @opem/node, on Professional and Enterprise. A document is matched by its path; prune removes synced documents no longer sent. The call underneath is PUT /api/v1/manage/knowledge/documents.

scripts/sync-docs.ts · runs in CI

import { glob, readFile } from "node:fs/promises";

import {
  createManagementClient,
  syncDocuments,
} from "@opem/node";

const opem = createManagementClient({
  secretKey: process.env.OPEM_SECRET_KEY,
});

const documents = [];
for await (const path of glob("**/*.md", { cwd: "docs" })) {
  documents.push({
    path,
    content: await readFile(`docs/${path}`, "utf8"),
  });
}

const results = await syncDocuments(opem, documents, {
  prune: true,
});
console.log(`${results.length} documents in sync`);

Crawl your site

Opem can also read pages and sitemaps from your site, weekly or on demand, with OpemBot. A page gives its roles and topic tags in <meta name="opem-access"> and <meta name="opem-tags">.