Authoring guide

This page is only published in the internal build. It documents the conventions, containers and components available to writers. See also README.md in the wecom-docs repository.

Frontmatter and audiences

Every page must declare who it is for. The build fails if audience is missing or contains an unknown value.

---
title: Service orders
description: Creating and tracking service orders.
audience: [staff, partner]   # any of: dev, admin, staff, partner
---

Audience	Meaning
dev	Developers
admin	WECOM administrators and system administrators
staff	WECOM staff using the application
partner	Partner users — the page is published in the partner build

Only pages whose audience includes partner are built into the partner site.

Containers

Staff-only content

Use an internal container for anything partners must not see. In the partner build it is removed from the output entirely — not hidden with CSS.

::: internal
Staff can filter the list by partner.
:::

::: internal Custom title
Content with a custom title.
:::

WECOM staff only

This is how a staff-only block looks.

For a short phrase inside a paragraph use the inline form:

Open the order detail page. [internal]Staff also see the audit trail.[/internal]

Open the order detail page. Staff also see the audit trail.

WARNING

Headings, tables and links inside ::: internal are removed too, so a partner page may link to internal-only pages only from inside an internal block. Everything else is checked by the partner leak check (npm run check:partner).

Partner callouts

::: partner
You can only see orders that belong to your own organisation.
:::

Partners

This is how a partner callout looks. It appears in both builds.

Standard containers

::: tip, ::: info, ::: warning, ::: danger and ::: details work as in the default VitePress theme.

TIP

A tip.

DANGER

A danger notice.

Components

Components are registered globally — use them directly in markdown.

RoleBadge

Shows a role as a friendly label.

<RoleBadge role="WECOM_OPS" /> <RoleBadge role="PARTNER_ADMIN" />

WECOM Administrator WECOM Operations WECOM SalesWECOM Accounts WECOM SupportPartner Administrator Partner Operations Partner Support

The partner build only knows partner role labels. Never use a WECOM role badge on a partner page outside an internal block — the leak check will fail.

Screenshot

<Screenshot
  src="/images/service-orders/01-list.png"
  alt="Service orders list"
  caption="The service orders list"
/>

• Files live in src/public/images/<module>/<nn>-<slug>.png, for example src/public/images/service-orders/01-list.png, and are referenced as /images/<module>/<nn>-<slug>.png.
• Click a screenshot to enlarge it; press Escape or click again to close.
• A screenshot that does not exist yet renders as a dashed placeholder with the alt text and a warning in the build log. It never breaks the build.
• Images not referenced by any partner page are removed from the partner build.

Screenshot pendingExample of a pending screenshot/images/service-orders/99-example.png

A screenshot that has not been captured yet

Diagrams

Use fenced mermaid code blocks. Diagrams render in the browser and follow the light or dark theme.

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Submitted
```

Loading diagram...

Adding a module

1. Add { slug, text } to modules in src/.vitepress/nav.mjs.
2. Create the pages that exist for it: src/system/modules/<slug>.md, src/admin/<slug>.md, src/user/<slug>.md.
3. Sidebars and the top navigation update automatically.