# Markdown in Redocly

Redocly projects support enhanced Markdown that combines standard Markdown syntax with powerful Markdoc extensions, giving you rich formatting options and interactive components for your documentation.

## Standard Markdown

All standard Markdown syntax works in Redocly projects:

### Text formatting


```markdown
**Bold text** and *italic text*

~~Strikethrough text~~

`Inline code`

> Blockquotes for callouts and emphasis
```

### Headings and structure


```markdown
# Page title (H1)
## Section heading (H2)  
### Subsection heading (H3)

- Bulleted lists
- With multiple items

1. Numbered lists
2. In sequential order
```

### Links and references


```markdown
[Link text](./relative-page.md)
[External link](https://example.com)

![Image alt text](./images/screenshot.png)
```

### Code blocks


```markdown
```javascript
// Syntax highlighting for many languages
function example() {
  return "Hello world";
}
```
```

## Redocly enhancements

Redocly extends standard Markdown with additional capabilities:

### Front matter configuration

Control page behavior with YAML front matter:


```yaml
---
title: Custom page title
description: Page description for SEO
---
```

### Enhanced code blocks

Add titles, line highlighting, and annotations:


```markdown
```javascript {% title="app.js" highlight="{2,4-6}" %}
function processData() {
  const data = fetchData(); // [!code highlight]
  
  if (!data) { // [!code error] // [!code error]
    throw new Error('No data'); // [!code error] // [!code error]
  } // [!code error] // [!code error]
  
  return data.map(item => ({ // [!code ++] // [!code ++]
    id: item.id, // [!code ++] // [!code ++]
    name: item.name // [!code ++] // [!code ++]
  })); // [!code ++] // [!code ++]
}
```
```

Learn more about [code snippet configuration](/docs/realm/config/code-snippet) for all highlighting and annotation options, and explore [Markdoc code tags](/docs/realm/content/markdoc-tags/code-group) for multi-language examples.

### File trees

Display project structure with the `treeview` format:


```markdown
```treeview
project/
├── docs/
│   ├── api/
│   │   └── openapi.yaml
│   └── guides/
│       └── getting-started.md
├── images/
└── redocly.yaml
```
```

### Diagrams

Add visual diagrams using Mermaid syntax:


```markdown
```mermaid
graph TD
    A[User Request] --> B{Authentication}
    B -->|Valid| C[Process Request]
    B -->|Invalid| D[Return Error]
    C --> E[Return Response]
```
```

Learn more about [adding diagrams](/docs/realm/content/add-diagram) with additional examples and chart types.

## Markdoc tags

Redocly includes powerful Markdoc tags for interactive elements:

### Content organization


```markdoc
{% tabs %}
{% tab label="Option A" %}
Content for the first tab.
{% /tab %}
{% tab label="Option B" %}
Content for the second tab.
{% /tab %}
{% /tabs %}
```

Learn more about the [tabs tag](/docs/realm/content/markdoc-tags/tabs) for organizing content.

### Visual elements


```markdoc
{% admonition type="info" name="Important note" %}
This is an informational callout with custom styling.
{% /admonition %}

{% cards %}
{% card title="Feature 1" icon="star" to="./feature-1.md" %}
Description of the first feature.
{% /card %}
{% card title="Feature 2" icon="gear" to="./feature-2.md" %}
Description of the second feature.
{% /card %}
{% /cards %}
```

Learn more about [admonitions](/docs/realm/content/markdoc-tags/admonition) and [cards](/docs/realm/content/markdoc-tags/cards) for enhanced visual presentation.

### Images and icons

Enhanced image display with sizing, lightbox, and captions:


```markdoc
{% img src="./images/screenshot.png" alt="Application screenshot" width="400" lightbox=true %}
A screenshot showing the main application interface.
{% /img %}
```

Add inline icons for visual enhancement:


```markdoc
{% icon name="star" /%} Highlighted feature
{% icon name="warning" color="orange" /%} Important note
```

Learn more about [image handling](/docs/realm/content/markdoc-tags/img) and [icons](/docs/realm/content/markdoc-tags/icon) for visual elements.

### Code and examples


```markdoc
{% code-snippet file="./examples/sample.js" title="Sample code" /%}

{% markdoc-example %}
This shows how Markdoc syntax renders in practice.
{% /markdoc-example %}
```


```markdoc
{% code-group %}
{% code title="JavaScript" lang="javascript" %}
fetch('/api/users')
  .then(response => response.json())
  .then(data => console.log(data));
{% /code %}
{% code title="Python" lang="python" %}
import requests
response = requests.get('/api/users')
data = response.json()
print(data)
{% /code %}
{% /code-group %}
```

Learn more about [code snippets](/docs/realm/content/markdoc-tags/code-snippet), [code groups](/docs/realm/content/markdoc-tags/code-group), and [Markdoc examples](/docs/realm/content/markdoc-tags/markdoc-example) for displaying code.

### Content reuse


```markdoc
{% partial file="/_partials/shared-section.md" /%}
```

Learn more about [partials](/docs/realm/content/markdoc-tags/partial) for reusing content across pages.

### API documentation


```markdoc
{% openapi-code-sample 
   path="/users" 
   method="post" 
   lang="javascript" /%}

{% json-schema schema="user-schema.json" /%}
```

Learn more about [OpenAPI code samples](/docs/realm/content/markdoc-tags/openapi-code-sample) and [JSON schema](/docs/realm/content/markdoc-tags/json-schema) for API documentation.

## Tables

Redocly uses enhanced table formatting:


```markdoc
{% table %}
- Column 1
- Column 2  
- Column 3
---
- Row 1, Cell 1
- Row 1, Cell 2
- Row 1, Cell 3
---
- Row 2, Cell 1
- Row 2, Cell 2
- Row 2, Cell 3
{% /table %}
```

Learn more about [table formatting](/docs/realm/content/markdoc-tags/table) for structured data presentation.

## Best practices

### File organization

- Use descriptive filenames with kebab-case: `user-authentication.md`
- Organize related content in folders
- Place reusable content in `_partials/` folders


### Writing style

- Start with a clear H1 heading
- Use descriptive link text instead of "click here"
- Include alt text for images
- Break up long content with headings and lists


### Cross-references

- Use relative links for internal pages: `./other-page.md`
- Link to specific sections with anchors: `./page.md#section-name`
- Test links to ensure they work correctly


### Images and assets

- Store images in organized folders like `./images/`
- Use descriptive filenames for images
- Optimize image sizes for web display
- Consider using [static assets](/docs/realm/customization/static-assets) for predictable URLs


## Resources

- **[Markdoc tags reference](/docs/realm/content/markdoc-tags/tag-library)** - Complete library of interactive components like cards, tabs, admonitions, and code groups for enhanced content
- **[Content reuse with partials](/docs/realm/content/markdoc-tags/partial)** - Share and reuse content across multiple pages to maintain consistency and reduce duplication
- **[Project structure guide](/docs/realm/content/project-structure)** - Organize your content files and directories for optimal navigation and maintenance
- **[Links and navigation](/docs/realm/content/links)** - Create internal and external links with automatic validation and cross-references between pages and sections
- **[Static assets management](/docs/realm/customization/static-assets)** - Host images, files, and other static resources with predictable URLs and optimization
- **[Markdown configuration](/docs/realm/config/markdown)** - Customize Markdown processing, syntax highlighting, and rendering behavior