Skip to main content

Writing Docs

This guide covers how to contribute to The One Stack documentation using our custom MDX components.

Custom Components​

Import components at the top of any .mdx file:

import Callout from '@site/src/components/Callout';
import Screenshot from '@site/src/components/Screenshot';
import ApiEndpoint from '@site/src/components/ApiEndpoint';
import PermissionRequired from '@site/src/components/PermissionRequired';

Callout​

Use callouts to highlight important information:

<Callout type="tip">This is a helpful tip for the reader.</Callout>
<Callout type="warning">Be careful when performing this action.</Callout>
<Callout type="note">Additional context that may be useful.</Callout>
<Callout type="danger">This action is destructive and cannot be undone.</Callout>

Types: tip (blue), warning (yellow), note (gray), danger (red).

Screenshot​

Display screenshots with consistent styling and captions:

<Screenshot
  src="/img/hub-dashboard.png"
  alt="Hub dashboard showing organization overview"
  caption="The Hub dashboard after first login"
/>

ApiEndpoint​

Document API endpoints with method badges:

<ApiEndpoint
  method="GET"
  path="/api/v1/tickets"
  description="List all tickets for the current organization"
  auth="Hub SSO or X-Integration-Key"
/>

<ApiEndpoint
  method="POST"
  path="/api/v1/tickets"
  description="Create a new ticket"
  auth="Hub SSO with psa.tickets.create"
/>

PermissionRequired​

Show which permission is needed for a feature:

<PermissionRequired permission="psa.tickets.create" />
<PermissionRequired permission="defend.alerts.acknowledge" role="Admin" />

File Structure​

  • Each product has its own directory under docs/
  • Use index.md for the product overview page
  • Use descriptive filenames: creating-tickets.md, sla-configuration.md
  • Set sidebar_position in frontmatter to control ordering

Style Guidelines​

  • Write in second person ("you") directed at MSP technicians and admins
  • Keep paragraphs short — 2-3 sentences max
  • Use tables for comparing options or listing features
  • Include keyboard shortcuts where applicable (use Cmd for Mac, note Ctrl for Windows)
  • Link to related docs pages liberally