Authoring articles in Ochre

Most teams start by syncing existing docs from Notion or GitBook, or pointing the crawler at an existing docs site. That is fine. But the fastest path to a useful article is writing it directly in Ochre. Here is how the editor works.

Creating an article

From the Knowledge section, click New article. You will be asked for three things up front: a title, a category, and a slug. The slug is what shows up in the URL after /help/<workspace-slug>/. Ochre generates one from your title, but you can override it. Pick the slug carefully because changing it later breaks inbound links unless you set a canonical URL or a redirect.

The article opens in draft status. Drafts are visible to your team but invisible everywhere else. The AI agent does not see drafts either.

The editor

The editor is markdown with a few extras.

Headings and structure

Use ## for top-level sections inside an article and ### for subsections. Do not use #. The article title is already an <h1>.

Lists

Bulleted and numbered lists work the way you would expect. Nest with two-space indentation.

Code

Backticks for inline code. Triple backticks with a language hint for blocks. Syntax highlighting renders client-side.

Images

Drag and drop. Ochre uploads, generates a stable URL, and inserts the markdown. Cover images are a separate field, set in the sidebar.

Slash commands

Type / in an empty line to open the command menu. Insert callouts, dividers, and embeds. Callouts are the easiest way to make a "watch out" note stand out without writing custom HTML.

Internal links

Link to other articles using the slug. Format: [Title](/help/ochre/slug). Ochre validates these on save and warns if the slug does not exist. Cross-links matter for SEO and for AI retrieval. See Article SEO.

The /help/ochre/<slug> form is portable across the apex (ochrehq.com) and the workspace subdomain. Use it for all internal cross-links.

Sidebar fields

Every article has a sidebar with the metadata. The most important fields:

• Category and sub-category. One parent, optional one child. See Categories and sub-categories.
• Status. Draft, Published, Archived. See Article visibility and gating.
• Cover image. Optional. Shows in card grids and at the top of the article.
• Position. Sort order within the category. Lower numbers come first.
• SEO fields. Title, description, slug, OG image, robots, canonical, keywords. Full guide at Article SEO.

Saving

Ochre auto-saves as you type. There is no save button. The status indicator in the top bar shows when the last save landed.

If two people edit the same article at the same time, the last write wins. Ochre warns you if a teammate has the article open. For long edits, drop a note in the team's internal notes before starting.

Preview

The Preview button opens the article in a new tab as it would render publicly, including the help center theme. The URL is unguessable, so you can share it with a colleague before publishing.

Publishing

Click Publish. The article goes live immediately at:

• https://ochrehq.com/help/<workspace-slug>/<slug> (apex)
• https://<workspace-slug>.ochrehq.com/help/<slug> (subdomain)
• Or your custom domain if you have set one up. See Help center custom domain.

Publishing also:

• Adds the article to the sitemap if the sitemap is enabled.
• Indexes it for AI retrieval. The agent can now use it in drafts.
• Starts collecting analytics and votes.

There is no review queue. Publishing is a single click. If you want a review step, use draft status and a mention in a Slack channel.

Editing a published article

Editing a live article is non-destructive until you save. Auto-save updates the public page. If you are making a major rewrite, switch the status to Draft, finish the rewrite, and republish. The URL stays the same.

Newly-edited articles spend a short window in quarantine before the AI uses them on live tickets — a safety net so a typo cannot leak into a customer reply before the next reviewer sees it.

Length

Aim for 600 to 1500 words. Shorter than 400 and the AI agent has too little context. Longer than 2000 and customers bounce. If you are tempted to go past 2000, split it into two articles and link them.

Tone

Direct. Concrete. Skip the marketing voice. Customers reading the help center want the answer, not the brand.

Next

Once you have written a few, look at Article analytics to see what people actually read.