Articles and authoring
Articles and authoring
The Knowledge Base is where your team keeps its runbooks, procedures and notes — your own estate’s documentation. It is separate from this Manual: the Manual documents lazyit itself, the Knowledge Base documents your servers, your apps, your processes.
An article is a single Markdown document. You write it in plain Markdown, preview it as you go, and publish it when it is ready.
Browsing the Knowledge Base
The Knowledge Base opens on its home page: the title with one line of figures (how many articles you can see, how many are published, how many drafts are yours, and how many folders there are), a search box, the top-level folders as cards, and the articles table.
The sidebar: views and folders
The sidebar on the left has two parts. Views are fixed shortcuts:
- All articles — the home page, with the number of articles you can see.
- My drafts — your unpublished articles. Drafts are private to their author, so this list only ever holds yours.
- Recent — the articles you opened in this browser, newest first (up to 20). The list is kept only on this device, in this browser: it is not sent to the server, not shared with anyone, and not synced to your other devices. A private window or blocked site data simply starts it empty. Clear list forgets it.
- Linked to assets and apps — articles connected to at least one asset or application.
Below them, Folders is the folder tree — see Folders and access. The highlighted entry always matches the page you are on, so a shared link opens with the same view or folder selected. On a narrow screen the sidebar folds behind a Views and folders button.
The articles table
Articles are listed as a table:
- Article — the title, a Draft label on unpublished articles (point at it: only you can see it until it’s published), a link count when the article is linked to assets or apps, and the excerpt underneath (or No summary when it has none).
- Folder — the article’s full folder path, with a padlock when that folder is restricted.
- Author — who wrote it; a teammate who has left is marked Former member.
- Reading — the estimated reading time.
- Updated — how long ago it last changed; point at it for the exact date and time.
On a narrow screen each article becomes a two-line row with its folder and date under the title. Above the table:
- All / Published / Drafts filters by status, each with its count. Drafts is the same list as My drafts.
- Sort orders the list by Updated (newest first, the default), Title (A to Z) or Created (newest first).
- Filters narrows to articles linked to assets or applications — any, a kind, or specific ones. Active filters show as chips you can remove one by one.
- Show archived (administrators only) swaps the list for the archived articles — see Archived articles.
Every choice is kept in the page address, so you can bookmark or share a filtered list.
Searching
The search box searches the full text of every article you can read — titles and bodies. Press
/ to jump to it from anywhere on the page, or ⌘K (Ctrl K) for a quick-open box that jumps
straight to an article. Each result shows the matching words highlighted, the article’s folder
and how long ago it was updated. Search covers the whole Knowledge Base, not just the folder you
are in. Right after an update, until search has been re-indexed, results fall back to matching titles
and excerpts only — a note says so — and the folder and date may be missing on some results.
Writing an article
Open the Knowledge Base and choose New article — or New article here on a folder’s page, which opens the form with that folder already chosen as the Category. The form is short:
- Title — the article’s name. The URL slug is derived from the title automatically (a short
lowercase-with-hyphensform); you do not type it. - Category — the article’s home folder. Every article lives in exactly one folder. Pick it from the searchable folder list — type to filter by the folder’s full path (e.g. Servers / Linux), so the right one is easy to find even in a deep tree. If you have not created any folders yet, use the + button to make one without leaving the form. See Folders and access.
- Excerpt (optional) — a one-line summary shown in listings.
- Content — the body, in Markdown.
The editor is a plain Markdown editor with a live preview — there is no rich-text/WYSIWYG mode by
design. The form gives the editor a wide, comfortable width, and the Save / Create draft
actions ride in a bar that stays in reach as you scroll a long article. Fenced code blocks are
syntax-highlighted on the published page, each with a copy button, and a ```mermaid block renders
as a diagram. You write raw Markdown; the formatting appears when the article is viewed.
Diagrams use Mermaid’s current look: automatic layout and a coloured theme that follows light and dark mode. Diagrams written before an update render with the new layout, so they can look different even though their source is unchanged.
Diagram labels are plain text. HTML tags in a label (<b>, <img>, links) show exactly as written
rather than being applied, and diagram settings in the source cannot change that. For a line break in
a label, use <br>; for bold or italic, use a Markdown string such as A["`**Return** asset`"].
If a code block’s fence has no language marker, lazyit makes a best-effort guess at display time
and labels it auto (for example, ```def sum(a, b): return a + b``` is highlighted as Python).
An explicit language on the fence always wins, and an ambiguous block is left as plain text rather
than mislabelled — so adding a language to the fence is still the reliable way to be sure.
While typing, two helpers offer autocomplete:
- Typing
[[starts a wiki-link to another article — see Linking and discovery. - Secret references to the Secret Manager are also supported inline; you only ever see and pick a handle, never a secret value.
Start from a Markdown file
On the New article screen you can seed the editor from a file you already have: drag a
Markdown file onto the form and its text drops straight into Content. A calm “Drop a .md
file to import its content” overlay appears while you drag. Prefer not to drag? Use the Choose a
.md file button on the same bar to pick one — the keyboard-friendly path does exactly the same
thing.
- Accepted files are
.md,.markdownand.txt, up to 1 MB. Anything else is declined with a short notice — this only imports text, so images and other file types are not accepted here (for pictures, see Adding images below). - The file is read in your browser only — nothing is uploaded. It simply fills the editor, and the article is created when you press Create draft, exactly as if you had typed it.
- If the Title is still empty, it’s filled from the file’s first
# Heading(a leading---YAML frontmatter block is skipped first), or from the file name. A title you’ve already typed is never overwritten. - If the editor already has content, importing asks you to confirm before replacing it, so a stray drop never wipes work in progress.
This is a quick way to start a draft from notes — for bringing in Word documents or a whole folder of Markdown at once, use Import instead (see Importing articles).
Formatting help (the ? button)
A ? button in the editor’s toolbar opens a short formatting cheat sheet so you never write
“blind”. It covers plain Markdown (headings, bold/italic, code, lists) and — most usefully —
lazyit’s two reserved tokens, each with a copyable example:
- Link another article —
[[article-slug]], or[[article-slug|Display text]]for custom link text. A link to an article that does not exist yet stays a forward reference. - Reference a secret —
{{ lazyit_secret.handle }}, which renders as a masked chip only a vault member can reveal — see Secret references. - External link — a standard Markdown
[text](https://…)link to anywhere outside the Knowledge Base.
Copy an example, paste it into the body, and the live preview shows exactly how the token resolves.
The same ? and live preview are available on both the New article and Edit screens.
Your work is protected
The editor guards against losing in-progress writing:
- Local autosave — as you type, your draft is saved to this browser every few seconds. It is a private safety net on your own machine, not a server save: the article only changes when you press Create draft / Save changes. If the tab crashes or closes by accident, nothing is lost.
- Restore on return — reopen New article or Edit and, if an unsaved local draft is waiting, a banner offers to Restore it (or Discard it). A saved article is never overwritten without your say-so.
- Leave warning — closing the tab, reloading, or pressing Cancel with unsaved edits asks you to confirm before discarding them. A successful save clears the local draft.
The local draft lives only in the browser you wrote it in; it is not shared with teammates or synced across devices.
Drafts and publishing
Every new article is born a Draft. A draft is private to its author — no one else can see it, and a teammate who guesses its address gets an “article not found” page, not a permission error, so the draft’s very existence stays hidden.
Publish from the article itself:
- Publish — makes the article Published and visible to the team (subject to its folder’s access rules). The first publish stamps a publish date that is never cleared.
- Unpublish — moves a published article back to Draft, hiding it from everyone but the author again.
A Draft badge marks unpublished articles on their page and in the articles table, and My drafts in the sidebar lists all of yours. Editing the body never changes the published/draft state — publishing and unpublishing are their own explicit actions.
Adding images
You can put screenshots and diagrams straight into an article. The fastest way is to paste: copy an image to your clipboard and paste it into the editor’s source pane — lazyit uploads it and inserts an image reference at the cursor. You can also drag and drop an image file onto the editor, or use the Insert image button in the editor toolbar to pick one from disk.
- Supported types are PNG, JPEG, GIF and WebP, up to 10 MB each. Other formats — including SVG — are rejected; export diagrams to PNG.
- Images belong to the article, so save the draft first. On a brand-new article that has never been saved there is nowhere to attach an image yet, so a paste shows a “save the draft first” hint.
- While an image uploads you see a short
![uploading …]()placeholder in the source pane; it is swapped for the real reference automatically once the upload finishes. - Images render on the published article and in the live preview, and are served only to people who can already read the article — an image is never exposed on a public URL.
- Only files you paste, drop or upload are stored. A hand-written link to an image on the web is not displayed (no external image loading), so keep runbook screenshots as uploaded attachments.
Editing and deleting
- Edit opens the same form on the existing article. Saving updates the body; it does not change whether the article is published. Every edit that changes the title, body or excerpt is captured in the article’s history — see Versioning.
- Delete removes the article from the Knowledge Base. This is a soft delete: the article is archived, not erased, and an administrator can restore it (see below). Its slug is also freed so a new article can reuse the name.
Archived articles
Administrators can list and restore archived articles. Above the articles table, turn on Show archived: the table then lists archived articles instead of live ones, and the date column shows when each one was archived. Every other choice still applies — a folder, the status control, Sort and Filters — so you can look for an archived article in one folder. The switch is not shown to anyone else, and the server refuses the archived list to anyone who is not an administrator.
- What you see. Archived published articles, and your own archived drafts. Another author’s archived draft never appears, the same rule as for live drafts.
- Restore. Click Restore on the row and confirm. The article goes back to its folder with the same address, status and history, and appears in the live list, search and folder counts again. Restoring needs the article-delete permission, which administrators hold by default.
- When the address is taken. Archiving frees the article’s slug, so a newer article may have taken it in the meantime. Restore then fails with Another article now uses the address … and nothing changes. Archive the article that holds the address first, then restore this one.
- Archived articles are left out of the CSV export, so Export is hidden while the switch is on. Search covers live articles only.
Who can do what
Authoring is gated by Knowledge Base permissions, and the API additionally enforces authorship:
- Reading the Knowledge Base needs the article-read permission, which every role holds by default.
- Creating, importing, editing, publishing, unpublishing and linking need the article-write permission. By default a normal writer may only edit, publish or delete their own articles — a write-permission holder who is not the author gets a permission error on someone else’s article.
- Editing any article. Two callers are exempt from the author-only rule so a runbook is never
stuck behind an unavailable author: administrators (who can always edit, publish, delete and
restore any article), and holders of the “Edit any article” capability (
article:manage). This is an admin-grantable permission you can give a trusted teammate. It bypasses authorship only — the person still needs the write permission to edit (or the delete permission to delete), and a non-admin holder still cannot touch an article in a folder they cannot see. Attribution is never lost: the original author stays recorded, and each edit is stamped with who actually made it in the article’s version history. - Administrators can always see every article, including drafts, regardless of folder restrictions. A holder of “Edit any article” can open another author’s draft by its link (its address or ID) in a folder they can read, so they can fix what they are allowed to edit. Other people’s drafts still never appear in their lists or in search.
See Roles and permissions for the full capability set.