2297 Markdown Syntax 7f8dd586

# Azure DevOps Wiki Markdown Reference

Complete Markdown syntax reference for Azure DevOps wikis.

## Basic Formatting

### Headers

```markdown
# H1 - Page Title
## H2 - Major Section
### H3 - Subsection
#### H4 - Minor Section
##### H5 - Detail
###### H6 - Fine Detail
```

### Text Emphasis

```markdown
*italic* or _italic_
**bold** or __bold__
***bold italic*** or ___bold italic___
~~strikethrough~~
```

### Line Breaks

```markdown
Line 1
Line 2 (two spaces before line break)

New paragraph (blank line between)
```

## Lists

### Unordered Lists

```markdown
- Item 1
- Item 2
  - Nested item 2a
  - Nested item 2b
- Item 3

* Also works with asterisks
+ And plus signs
```

### Ordered Lists

```markdown
1. First item
2. Second item
   1. Nested ordered
   2. Another nested
3. Third item
```

### Task Lists

```markdown
- [ ] Incomplete task
- [x] Completed task
- [ ] Another pending task
```

## Links

### Basic Links

```markdown
[Link Text](https://example.com)
[Link with Title](https://example.com "Hover title")
```

### Wiki Page Links

```markdown
# Same folder
[Related Page](./page-name)

# Subfolder
[Child Page](./folder/page-name)

# Parent folder
[Parent](../page-name)

# Absolute from wiki root
[Home](/Home)

# Another wiki in same project
[Other Wiki Page](/Wiki-Name/Page-Name)
```

### Anchor Links (Headings)

```markdown
# Within same page
[Jump to Section](#section-heading)

# In another page
[Section in Other Page](./other-page#section-heading)
```

**Anchor ID rules:**

- Spaces → hyphens
- Uppercase → lowercase
- Special characters removed
- Example: `## Team #1 : Release!` → `#team-1--release`

### Work Item Links

```markdown
#123                    <!-- Links to work item 123 -->
[Bug #123](#123)        <!-- Custom link text -->
AB#123                  <!-- Links across projects -->
```

## Images

### Basic Image

```markdown
![Alt text](image-url)
![Screenshot](/.attachments/screenshot.png)
```

### Image with Size

```markdown
![Alt text](image.png =500x300)     <!-- Width x Height -->
![Alt text](image.png =500x)        <!-- Width only -->
![Alt text](image.png =x300)        <!-- Height only -->
```

### Image as Link

```markdown
[![Alt text](thumbnail.png)](full-size.png)
```

## Code

### Inline Code

```markdown
Use the `console.log()` function for debugging.
```

### Code Blocks

````markdown
```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}
```
````

### Supported Languages

| Language | Identifier |
|----------|------------|
| JavaScript | `javascript`, `js` |
| TypeScript | `typescript`, `ts` |
| Python | `python`, `py` |
| C# | `csharp`, `cs` |
| Java | `java` |
| Go | `go` |
| Rust | `rust` |
| SQL | `sql` |
| Bash/Shell | `bash`, `shell`, `sh` |
| PowerShell | `powershell`, `ps` |
| YAML | `yaml`, `yml` |
| JSON | `json` |
| XML | `xml` |
| HTML | `html` |
| CSS | `css` |
| Markdown | `markdown`, `md` |

## Tables

### Basic Table

```markdown
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |
```

### Alignment

```markdown
| Left | Center | Right |
|:-----|:------:|------:|
| L    | C      | R     |
| L    | C      | R     |
```

### Table with Formatting

```markdown
| Feature | Status | Notes |
|---------|--------|-------|
| **Auth** | `Done` | OAuth2 implemented |
| *Cache* | `WIP` | Redis integration |
| ~~Old~~ | Removed | Deprecated v1 |
```

## Blockquotes

### Basic Quote

```markdown
> This is a quote.
> Multiple lines work too.
```

### Nested Quotes

```markdown
> Level 1
>> Level 2
>>> Level 3
```

### Alert Boxes (Azure DevOps specific)

```markdown
> [!NOTE]
> Information the user should notice.

> [!TIP]
> Optional helpful advice.

> [!IMPORTANT]
> Essential information required for success.

> [!CAUTION]
> Advises about risks or negative outcomes.

> [!WARNING]
> Dangerous outcomes with potential data loss.
```

## Horizontal Rules

```markdown
---
***
___
```

## Special Wiki Features

### Table of Contents

```markdown
[[_TOC_]]
```

Place on its own line. Auto-generates from headings.

### YAML Metadata

```markdown
---
title: Page Title
author: Team Name
updated: 2024-01-15
tags:
  - category1
  - category2
---
```

Must be at the very beginning of the file.

### User Mentions

```markdown
@username           <!-- Mention specific user -->
@<Team Name>        <!-- Mention team/group -->
```

### Page Visit Count

Automatically displayed in wiki. Access via Page Info.

## Mermaid Diagrams

### Flowchart

```markdown
::: mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
:::
```

**Note:** Use `graph` not `flowchart` (unsupported in Azure DevOps).

### Sequence Diagram

```markdown
::: mermaid
sequenceDiagram
    participant C as Client
    participant S as Server
    participant D as Database

    C->>S: Request
    S->>D: Query
    D-->>S: Results
    S-->>C: Response
:::
```

### Gantt Chart

```markdown
::: mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Research      :a1, 2024-01-01, 30d
    Development   :after a1, 60d
    section Phase 2
    Testing       :2024-04-01, 30d
    Deployment    :2024-05-01, 7d
:::
```

### Class Diagram

```markdown
::: mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog
:::
```

### State Diagram

```markdown
::: mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : Start
    Processing --> Complete : Success
    Processing --> Error : Failure
    Complete --> [*]
    Error --> Idle : Retry
:::
```

### Pie Chart

```markdown
::: mermaid
pie title Distribution
    "Category A" : 45
    "Category B" : 30
    "Category C" : 25
:::
```

### Entity Relationship

```markdown
::: mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"
:::
```

## HTML Support

### Allowed HTML Tags

```html
<br>          <!-- Line break -->
<hr>          <!-- Horizontal rule -->
<p>           <!-- Paragraph -->
<div>         <!-- Division -->
<span>        <!-- Inline container -->
<b>, <strong> <!-- Bold -->
<i>, <em>     <!-- Italic -->
<u>           <!-- Underline -->
<sub>         <!-- Subscript -->
<sup>         <!-- Superscript -->
<font>        <!-- Font styling -->
<table>, <tr>, <td>, <th>  <!-- Tables -->
<ul>, <ol>, <li>           <!-- Lists -->
<a>           <!-- Links -->
<img>         <!-- Images -->
```

### Collapsible Sections

```html
<details>
<summary>Click to expand</summary>

Content here (note the blank line after summary)

- Supports Markdown inside
- Multiple paragraphs work
- Code blocks too

</details>
```

### Colored Text

```html
<font color="red">Red text</font>
<font color="#00FF00">Green text (hex)</font>
<span style="color:blue">Blue text</span>
```

### Embedded Video

```html
<video src="https://example.com/video.mp4" width="400" controls>
</video>
```

## Mathematical Notation (KaTeX)

### Inline Math

```markdown
The formula $E = mc^2$ is famous.
```

### Block Math

```markdown
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + ... + x_n
$$
```

### Common Symbols

| Symbol | Syntax |
|--------|--------|
| Fraction | `$\frac{a}{b}$` |
| Square root | `$\sqrt{x}$` |
| Exponent | `$x^2$` |
| Subscript | `$x_i$` |
| Sum | `$\sum_{i=1}^{n}$` |
| Integral | `$\int_{a}^{b}$` |
| Greek letters | `$\alpha, \beta, \gamma$` |
| Infinity | `$\infty$` |

## Escaping Characters

### Backslash Escape

```markdown
\*Not italic\*
\#Not a heading
\[Not a link\]
\`Not code\`
```

### Characters to Escape

| Character | Escaped |
|-----------|---------|
| `*` | `\*` |
| `_` | `\_` |
| `#` | `\#` |
| `[` | `\[` |
| `]` | `\]` |
| `(` | `\(` |
| `)` | `\)` |
| `` ` `` | `` \` `` |
| `\` | `\\` |

## Limitations

### Not Supported

- JavaScript/iframes
- Custom CSS
- `flowchart` Mermaid syntax (use `graph`)
- Some HTML tags
- Font Awesome icons
- Long Mermaid arrows (`---->`)

### File Restrictions

| Restriction | Limit |
|-------------|-------|
| Page size | 18 MB |
| Attachment size | 19 MB |
| Path length | 235 chars |
| Characters in filename | No `/`, `\`, `#` |