Authoring Content

Frontmatter

Every document must have YAML frontmatter. The required fields are:

---
title: My Document Title
slug: section/my-document
description: A short description shown in search results (10-300 chars).
author: your.name@contoso.com
status: published
created: 2026-04-10T00:00:00Z
updated: 2026-04-10T00:00:00Z
---

See the Frontmatter Schema Reference for all 16 available fields.

Status lifecycle

Status	Visible in nav/search	Accessible by URL
`draft`	No	Yes (contributors only)
`in-review`	No (in public search)	Yes
`published`	Yes	Yes
`archived`	No	Yes (direct URL only)

Headings

Use ATX headings (## through ######). Do not include an H1 (#) in the document body -- it is rendered from the title frontmatter field.

## Section heading (H2)
 
### Subsection (H3)
 
#### Detail (H4)

Text formatting

Syntax	Result
`bold`	bold
`italic`	italic
`~~strikethrough~~`	~~strikethrough~~
`inline code`	`inline code`

Lists

Ordered lists:

1. First item
2. Second item
3. Third item

Unordered lists:

- Item one
- Item two
- Item three

Task lists:

- [x] Completed task
- [ ] Pending task

Links and images

[Link text](https://example.com)
[Internal link](/docs/hub-docs/guides/architecture/)
 
![Alt text](/assets/images/screenshot.png)

Image paths should use relative references to /assets/images/.

Code blocks

Fenced code blocks with a language identifier for syntax highlighting:

```typescript
const greeting = 'Hello, world!';
console.log(greeting);
```

Supported languages include: typescript, javascript, bash, json, yaml, bicep, css, html, markdown, powershell, python, sql.

Tables

GitHub-Flavoured Markdown tables:

| Column A | Column B | Column C |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Callouts

Use blockquote syntax with a type label:

> [!NOTE]
> Informational context the reader should be aware of.
 
> [!TIP]
> Helpful advice for better results.
 
> [!WARNING]
> Potential issues or things to watch out for.
 
> [!DANGER]
> Critical information about destructive or irreversible actions.
 
> [!IMPORTANT]
> Key information that should not be overlooked.

All five types are supported: NOTE, TIP, WARNING, DANGER, IMPORTANT.

Horizontal rules

---

Blockquotes

> This is a blockquote.
> It can span multiple lines.

Sanctioned HTML

These HTML tags are allowed within Markdown content:

<details> and <summary> -- Collapsible sections
<kbd> -- Keyboard shortcuts
<sub> and <sup> -- Subscript and superscript

All other HTML is stripped by the sanitization pipeline.

Unsupported features

The following Markdown features are not supported and will be stripped or ignored:

Footnotes
Math / LaTeX equations
Raw HTML blocks (except sanctioned tags above)
Emoji shortcodes (:smile:)
Definition lists
Abbreviations

Content visibility

Use the access frontmatter field to control who can see a page:

access: public -- Visible to everyone without authentication
access: internal -- Requires Entra ID login

If omitted, the page inherits its access level from the section's index.md. The global default is internal.