Skip to content

How to Use this Knowledge Base

This knowledge base is maintained as Markdown files in a private GitHub repository.

Local Development

Start the local documentation site with DDEV:

ddev start

Run a local build:

ddev mkdocs build

Editing Documentation

Documentation files live in the docs/ directory.

The main site configuration is controlled by mkdocs.yml.

When adding a new page, also add it to the nav section in mkdocs.yml if it should appear in the sidebar navigation.

Choosing the Right Location

Document information at the narrowest level where it remains useful:

  • Put site-specific configuration, behavior, and troubleshooting under the relevant website.
  • Put procedures that apply across several sites under Infrastructure, Git & Deployments, Development, Operations, or shared website procedures.
  • Link to shared procedures from site pages instead of duplicating them.
  • Use clear headings and terminology so pages can be found through search.

See Operational Documentation Practice for the full standard and examples.

Review and Publishing

Before publishing a substantial change:

  1. Review git diff.
  2. Build or preview the documentation locally when practical.
  3. Ask the other Online Services team member to review the content or published result.
  4. Commit with a descriptive message and push through the repository's agreed workflow.

Cool Markdown Stuff

Callouts

Use these for things someone should not miss. Technically called "admonitions", they're meant to be used for important side content.

Example Type: Note

This is an example of a "Note" callout section.

Example Type: Warning

This is an example of a "Warning" callout section.

Example Type: Danger

This is an example of a "Danger" callout section.

Example Type: Tip

There are many different types of these callouts. Try note, info, tip, success, question, warning, failure, danger, bug, example, or quote.

Collapsible sections

Good for troubleshooting, optional context, long command output, or longer explanations.

Example Closed By Default

This is an example that is closed by default.

some code could go here

Additional info here.

Example Open By Default

These instructions are already opened by default, but they can be closed.

Content tabs

Tabs are useful when documenting different environments, tools, or command variants.

git push origin dev

git push origin staging

git push origin main

Better code blocks

Add syntax highlighting, titles, line numbers, and highlighted lines.

.ddev/docker-compose.mkdocs.yaml
1
2
3
4
services:
  mkdocs:
    image: squidfunk/mkdocs-material:9
    command: serve --livereload --dev-addr=0.0.0.0:8000

Mermaid diagrams

This can be useful for deployment pipelines, environment flows, and request processes.

flowchart LR
  Local[DDEV Local] --> GitHub[GitHub Repository]
  GitHub --> Dev[Dev Server]
  Dev --> Staging[Staging Server]
  Staging --> Production[Production Server]

Definition lists

Dev
The environment used for active development and early testing.
Staging
The environment used for review, QA, and approval before production.
Production
The live public website environment.

Page metadata

You can add metadata at the top of pages for title, description, status, ownership, and validation dates.

---
title: Salesforce Synchronization
description: How a production synchronization process is configured.
status: validated
last_validated: 2026-07-14
owner: Online Services
---

Tip

Metadata must be placed at the very top of the page.