---
title: "Write documentation articles"
description: "Write a Markdown article for a client or your practice, publish it, keep it current with review dates, and show it to end users in the tray."
url: "https://support.outpostplatform.com/documentation/articles/"
product: "depot"
type: "how-to"
status: "draft"
ai_summary: "How to write, publish, review, and restore documentation articles in the Outpost console. Articles are Markdown with a live preview, mentions, and diagrams. Every save is a revision with a diff and restore. Review every N days, Mark as current records who checked it. Articles Visible to end users and Published appear under Help articles in the Outpost tray app. Needs docs:write."
availability:
  plans: ["home-lab", "essentials", "enterprise", "msp"]
  permission: "docs:write"
  preview: false
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/documentation/articles.md"
license: "CC BY 4.0"
---

# Write documentation articles

An article is a page of written documentation: a runbook, an onboarding
checklist, or the answer to a question your desk gets every week. This page
shows how to write one, publish it, keep it current, and see what changed
between versions. An article you publish and make visible to end users also
appears in the Outpost tray app on that client's endpoints.

## Before you begin

- You need the `docs:write` permission to create and change articles.
  `docs:read` is enough to read them.
- Decide where the article belongs. A client article sits under that client's
  **Documentation** > **Articles**. On the MSP plan, a practice article is
  written once and read from every client.

## Write an article

1. In the console, go to **Documentation** > **Articles** and select
   **New article**.
2. Optionally, in **Start from a template**, choose an article that someone has
   offered as a template. Outpost copies its body, summary, and labels. The
   title stays yours.
3. In **Title**, enter the title. **Slug** follows the title until you change
   it. The slug is the part of the address other people link to.
4. In **Summary**, enter one sentence. It shows in the article list and in
   search results.
5. In **Status**, choose **Draft** or **Published**. An article stays a draft
   until somebody publishes it.
6. In **Visible to**, choose **Internal** or **Visible to end users**.
7. In **Scope**, choose **This client** or **Practice**. A practice article is
   read from every client.
8. In **Labels**, enter labels separated by commas.
9. In **Review every**, enter the number of days between reviews. `0` means
   Outpost never asks.
10. Write the body in Markdown. The preview beside it is exactly what readers
    see. Use **Source**, **Split**, or **Preview** to choose the view.
11. Select **Save**.

While you write:

- Type `@` to mention another record, such as a credential, an asset, or an
  endpoint. A mention becomes a link on the article's **Relations** tab. A
  mentioned credential shows only its name. Readers open it to reveal it.
- Paste a table from a spreadsheet and it becomes a Markdown table. Merged
  cells are flattened, because Markdown tables cannot span columns.
- Paste from a word processor and the text is converted to Markdown.
- A fenced code block marked `mermaid` is drawn as a diagram.

Raw HTML is not stored. An article imported as HTML can be read but not edited.
To change one, replace it with a Markdown article.

## Publish an article

Open the article and select **Publish**. The **Publish** button shows only
while the article is not published. To take an article out of circulation,
open its **Editing** tab, set **Status** to **Archived**, and select **Save**.

## Show an article to end users

An article that is both **Published** and **Visible to end users** appears
under **Help articles** in the Outpost tray app on that client's endpoints,
where end users can search it. Drafts and **Internal** articles are never sent
to the tray. One search returns at most 50 articles, and an article body
longer than 256 KB is cut off with a note saying where it stops. See
[Tray](/tray/).

:::caution
Internal articles often name a client's accounts and workarounds. Check what
an article says before you make it visible to end users.
:::

## Keep an article current

Each article shows **Review** and **Last checked** under **About this
article** on its **Read** tab.

- **Review every** sets how often the article comes due. When it does, it
  counts toward **past review** on the Documentation **Overview** and appears
  on **Expirations** as **Article review**.
- When you have checked that an article is still true, open it and select
  **Mark as current**. Outpost records your name and the date. An article
  nobody has checked shows **Never checked** in the list.

## See what changed and restore a version

Every save writes a new version. Nothing in the history is deleted.

1. Open the article and select the **Revisions** tab.
2. Under **Versions**, select a version. Each one says why it was written, such
   as **Created**, **Edited**, **Published**, or **Restored**, who wrote it,
   and when.
3. Read **What changed**, which compares that version with the one before it.
   A comparison too long to finish says so and shows the start.
4. To bring that text back, select **Restore version** followed by its
   number. Restoring writes the text back as a new version.

## Offer an article as a template

On the article's **Editing** tab, select **Offer this article as a template
for new ones**, then select **Save**. The article is then listed in **Start
from a template** when someone writes a new article.

## Verify

Open **Documentation** > **Articles**. Your article is listed with its status.
If you set **Review every**, the **Review** column shows the next review date
rather than **Not scheduled**. For an article visible to end users, open the
Outpost tray app on one of the client's endpoints and search **Help articles**
for its title.

## If something goes wrong

| Symptom | Cause | Fix |
| --- | --- | --- |
| A search in the article list finds nothing for a word you know is in the body. | The list's search matches the title only. | Use the search bar at the top of the console, which searches inside articles. |
| An article does not appear in the tray. | It is a draft or **Internal**. | Set **Status** to **Published** and **Visible to** to **Visible to end users**. |
| **The server would not store a** construct. | The body contains something the server refuses, such as raw HTML. | Remove the named construct and save again. |

## Next steps

- [Assets and asset layouts](/documentation/assets/)
- [Track expirations](/documentation/expirations/)
- [Using the tray](/tray/using-the-tray/)