Editing these docs

This site is intentionally easy to edit. Content is plain Markdown (.md) — or MDX (.mdx) when a page needs components — built with Astro Starlight. You do not need to know Astro to write docs; if you can write Markdown, you can edit this site.

Run it locally

# from the repository root
npm install
npm run dev      # start a local dev server with hot reload
npm run build    # produce the static site in ./dist
npm run preview  # preview the built site

Where pages live

src/content/docs/
  index.mdx                 # the splash home page
  start-here/               # → "Start Here" sidebar group
  concepts/                 # → "Core Concepts"
  install/                  # → "Install & Self-Hosting"
  console/                  # → "Using the Console"
  sdk/                      # → "TypeScript SDK"
  frameworks/               # → "Framework Guides"
  processes/                # → "Authoring Processes"
  config-formats/           # → "Configuration Formats"
  api/                      # → "REST API Reference"
  designer/                 # → "MACHHUB Designer (VS Code)"
  skills/                   # → "AI Agent Skills"
  reference/                # → "Reference"

Each top-level folder maps to a sidebar group (configured in astro.config.mjs). The sidebar is auto-generated from the files in each folder, so to add a page you just create a Markdown file in the right folder — no sidebar edits required.

Add a new page

Create a .md file with front matter at the top:

---
title: My New Page
description: A one-sentence summary used for SEO and link previews.
sidebar:
  order: 3          # controls position within its sidebar group
---

Your content starts here.

The page URL follows the file path: concepts/historian.md → /concepts/historian/.

Callouts (asides)

Use Starlight’s aside syntax for notes, tips, and warnings:

:::note
Useful context.
:::

:::tip[Custom title]
A helpful tip.
:::

:::caution
Something to be careful about.
:::

:::danger
A serious warning.
:::

Diagrams (Mermaid)

Write a fenced code block with the mermaid language — it renders as a diagram and follows light/dark mode automatically:

```mermaid
flowchart LR
  A[Device] -->|publish| B(MQTT Broker)
  B --> C[(Historian)]
```

Use diagrams freely for architecture, sequences, and data models.

Code blocks

Fenced code blocks get syntax highlighting and a copy button:

```ts
await sdk.collection('products').getAll();
```

Images, GIFs, and screen recordings

Put screenshots and recordings under public/images/<section>/ (served as-is) and reference them with the mh-figure pattern — a <figure class="mh-figure"> wrapping an <img> (screenshot/GIF) or <video> (MP4) plus a <figcaption>:

<figure class="mh-figure">
  <img src="/images/console/home-dashboard.jpeg" alt="The Home dashboard." />
  <figcaption>The Home dashboard — Users, Groups, Tags, and License status.</figcaption>
</figure>

<figure class="mh-figure">
  <video src="/images/designer/deploy.mp4" controls muted playsinline></video>
  <figcaption>Deploy from the Designer sidebar.</figcaption>
</figure>

Figure media is clickable — it opens full screen in a dialog (see public/figure-lightbox.js). Use .mp4 for longer clips viewers may want to scrub or skip; .gif for short, single-purpose flows.

Until an asset is captured, use a labeled placeholder so the gap is obvious:

<figure>
  <div class="mh-shot">📷 Screenshot to capture: <strong>Console home</strong></div>
</figure>

Style guidelines

• Prefer short sentences and task-oriented headings.
• Link concepts the first time they appear (e.g. Collections).
• Keep terminology consistent: Processes are serverless functions; Flows are Node-RED. Tags live in the Unified Namespace.
• Show real, runnable code where you can.