Source References

Doc pages link to source code through two MDX components: <Source> for inline links and <CodeBlock> for embedded code. Both validate at build time. If a referenced file or region is missing, the build fails.

Inline links: <Source>

Use <Source> to point at a file, a line, or a named region.

Whole file

<Source path="backend/src/oms/oms-server.ts" label="OMS" />

Renders: OMS

Specific line

<Source path="backend/src/oms/oms-server.ts" line={1} />

Renders: backend/src/oms/oms-server.ts:1

Named region

<Source path="backend/src/schemas/orders.ts" region="docs:order-new-schema" />

Renders: backend/src/schemas/orders.ts:44-62

The label defaults to path:start-end. Pass label to override.

Embedded code: <CodeBlock>

Use <CodeBlock> when the actual code is the point: schemas, formulas, topic constants, type definitions.

<CodeBlock
  path="backend/src/schemas/orders.ts"
  region="docs:order-new-schema"
  title="Order submission schema"
/>

Renders:

export const OrderNewSchema = z.object({
  clientOrderId: ClientOrderIdSchema.optional(),
  orderId: OrderIdSchema.optional(),
  userId: UserIdSchema,
  userRole: z.string().optional(),
  asset: SymbolSchema,
  side: OrderSideSchema,
  quantity: z.number().positive(),
  limitPrice: z.number().positive().optional(),
  expiresAt: TimestampMsSchema.optional(),
  strategy: StrategySchema.optional(),
  algoParams: AlgoParamsSchema.optional(),
  instrumentType: InstrumentTypeSchema.optional(),
  optionSpec: OptionSpecSchema.optional(),
  bondSpec: BondSpecSchema.optional(),
  desk: DeskSchema.optional(),
  ts: TimestampMsSchema.optional(),
});
export type OrderNew = z.infer<typeof OrderNewSchema>;

Order submission schema ↗

<CodeBlock> requires a region. Pinning by line number is too brittle for embedded code.

Region markers

Mark a code block in the source file with a line comment:

// #region docs:order-new-schema
export const OrderNewSchema = z.object({
  /* ... */
});
export type OrderNew = z.infer<typeof OrderNewSchema>;
// #endregion docs:order-new-schema

Conventions:

• Prefix every region ID with docs: so they do not collide with editor folding regions.
• Both // and # line-comment styles are supported (TypeScript, JavaScript, shell, Python, YAML).
• Region bodies are dedented automatically.
• A region must contain at least one line of content; empty regions fail the build.

Pinning to a release

By default, links resolve against main. To pin a build to a specific commit or tag, set DOCS_GIT_REF before building:

DOCS_GIT_REF=v1.19.3 npm run build

Used by tagged-release deploys so historical doc snapshots stay accurate.