This is the complete Markdown reference for Ava CMS. Ava uses CommonMark as the base parser with GitHub Flavored Markdown (GFM) extensions enabled by default.

What's what? Features marked GFM come from the GitHub Flavored Markdown extension. Features marked Ava are specific to Ava CMS.

Paragraphs

Paragraphs are separated by one or more blank lines. A single line break within text does not create a new paragraph—it's treated as a space.

Markdown

This is the first paragraph. This is the second paragraph.

Result

This is the first paragraph.

This is the second paragraph.

Line Breaks

To create a line break (<br>) without starting a new paragraph, end a line with two or more spaces, or use a backslash (\).

Markdown (two trailing spaces)

Roses are red·· Violets are blue

The ·· represents two spaces.

Result

Roses are red
Violets are blue

Markdown (backslash)

Roses are red\ Violets are blue

Result

Roses are red
Violets are blue

Headings

Create headings using # symbols (ATX style) or underlines (Setext style). There are six levels of headings.

ATX Style (Recommended)

Markdown

# Heading 1 ## Heading 2 ### Heading 3 #### Heading 4 ##### Heading 5 ###### Heading 6

Result

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Setext Style (H1 and H2 only)

Markdown

Heading 1 ========= Heading 2 ---------

Result

Heading 1

Heading 2

Emphasis (Bold & Italic)

Use asterisks (*) or underscores (_) for emphasis. One for italic, two for bold, three for both.

Style	Markdown	Result
Italic	`italic` or `_italic_`	italic
Bold	`bold` or `__bold__`	bold
Bold + Italic	`*both*` or `___both___`	*both*
Mixed	`bold and _nested italic_`	bold and nested italic

Strikethrough GFM

Wrap text in double tildes to strike it through.

Markdown

~~This text is crossed out~~

Result

~~This text is crossed out~~

Lists

Unordered Lists

Use -, *, or + followed by a space.

Markdown

- First item - Second item - Third item

Result

First item
Second item
Third item

Ordered Lists

Use numbers followed by a period. The actual numbers don't matter—Markdown will number them sequentially.

Markdown

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

Result

First item
Second item
Third item

Nested Lists

Indent items with 2–4 spaces to create nested lists.

Markdown

- Parent item - Child item - Child item - Grandchild - Another parent

Result

Parent item
- Child item
- Child item
  - Grandchild
Another parent

Mixed Lists

You can mix ordered and unordered lists by nesting.

Markdown

1. First step - Sub-point A - Sub-point B 2. Second step

Result

First step
- Sub-point A
- Sub-point B
Second step

Task Lists GFM

Create checkboxes with [ ] (unchecked) or [x] (checked).

Markdown

- [x] Write documentation - [x] Test examples - [ ] Publish

Result

Write documentation
Test examples
Publish

Images

Same syntax as links, but with a leading !. The text in brackets becomes the alt text.

Basic Image

Markdown

![A cute cat](/media/cat.jpg)

HTML Output

Image with Title

Markdown

![Cat](/media/cat.jpg "My cat Whiskers")

HTML Output

Linked Image

Wrap an image in link syntax to make it clickable.

Markdown

[![Alt text](/media/thumb.jpg)](/media/full.jpg)

HTML Output

Code

Inline Code

Wrap text in single backticks for inline code.

Markdown

Use the `echo` command.

Result

Use the echo command.

Inline Code with Backticks

To include a literal backtick, use double backticks.

Markdown

``Use `backticks` in code``

Result

Use `backticks` in code

Fenced Code Blocks

Use triple backticks or tildes. Add a language identifier for syntax highlighting.

Markdown

```php <?php echo "Hello, World!"; ```

Result

<?php
echo "Hello, World!";

Indented Code Blocks

Indent lines by 4 spaces or 1 tab. No syntax highlighting available.

Markdown

function hello() { return "Hi!"; }

Result

function hello() {
    return "Hi!";
}

Common Language Identifiers

Language	Identifier
PHP	`php`
JavaScript	`js` or `javascript`
HTML	`html`
CSS	`css`
JSON	`json`
YAML	`yaml` or `yml`
Bash / Shell	`bash` or `sh`
Plain text	`text` or `plaintext`

Blockquotes

Prefix lines with > to create a blockquote.

Basic Blockquote

Markdown

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

Result

This is a blockquote. It can span multiple lines.

Nested Blockquotes

Markdown

> Outer quote >> Nested quote >>> Deeply nested

Result

Outer quote
Nested quote
Deeply nested

Blockquotes with Other Elements

Markdown

> ### Heading in a quote > > - List item one > - List item two > > **Bold** works too.

Result

Heading in a quote

List item one
List item two

Bold works too.

Horizontal Rules

Create a horizontal line with three or more hyphens, asterisks, or underscores on their own line.

Markdown	Result
`---`
`***`
`___`

You can also use spaces between: - - - or * * *

Tables GFM

Create tables using pipes (|) and hyphens (-).

Basic Table

Markdown

| Name | Role | |---------|-----------| | Ada | Developer | | Grace | Manager |

Result

Name	Role
Ada	Developer
Grace	Manager

Column Alignment

Use colons in the separator row to control alignment.

Syntax	Alignment
`:---`	Left (default)
`:---:`	Center
`---:`	Right

Markdown

| Item | Qty | Price | |:-------|:---:|-------:| | Apples | 5 | $1.20 | | Bread | 2 | $3.50 |

Result

Item	Qty	Price
Apples	5	$1.20
Bread	2	$3.50

Escaping Characters

Prefix special characters with a backslash (\) to display them literally.

Characters You Can Escape

Character	Name	Escaped
`\`	Backslash	`\\`
`	Backtick	\`
`*`	Asterisk	`\*`
`_`	Underscore	`\_`
`{}`	Curly braces	`\{ \}`
`[]`	Square brackets	`\[ \]`
`()`	Parentheses	``
`#`	Hash	`\#`
`+`	Plus	`\+`
`-`	Hyphen	`\-`
`.`	Period	`\.`
`!`	Exclamation	`\!`
`\|`	Pipe	`\\|`

Markdown

\*This is not italic\* 1\. Not a list item

Result

*This is not italic*

1. Not a list item

Raw HTML

By default, Ava allows raw HTML in your Markdown. This is controlled by the content.markdown.allow_html setting.

Markdown

This has <mark>highlighted</mark> text. <details> <summary>Click to expand</summary> Hidden content here. </details>

Result

This has highlighted text.

Click to expand

Hidden content here.

HTML Entities

Standard HTML entities work as expected.

Entity	Result	Description
`&`	&	Ampersand
`<`	<	Less than
`>`	>	Greater than
`©`	©	Copyright
`—`	—	Em dash
` `	(non-breaking space)	Non-breaking space

Disallowed Tags

You can block specific HTML tags for security using content.markdown.disallowed_tags in your config, even when HTML is allowed.

Ava-Specific Features Ava

Automatic Heading IDs

Ava automatically adds id attributes to headings for anchor links. This is enabled by default via content.markdown.heading_ids.

Markdown

## Getting Started

HTML Output

<h2 id="getting-started">Getting Started</h2>

This lets you link directly to sections: /docs/page#getting-started

Path Aliases

Use configured aliases (like /media/) in image and link paths. Ava expands them during rendering.

Markdown

![Photo](/media/vacation.jpg)

HTML Output

Configure aliases in app/config/ava.php under paths.aliases.

Shortcodes

Ava processes shortcodes in your content after Markdown rendering. See the Shortcodes documentation for details.

Markdown

[youtube id="dQw4w9WgXcQ"]

Result

(Rendered shortcode output)

Optional Markdown Extensions Ava

Ava bundles seven optional extensions through the markdown-extensions plugin. They use extensions already shipped by league/commonmark, so no additional Composer dependencies are required. The default Ava configuration includes the plugin, but every extension defaults to never to avoid unnecessary Markdown parsing overhead.

For an existing installation, ensure 'markdown-extensions' is in the main plugins array in app/config/ava.php:

'plugins' => [ 'markdown-extensions', ],

Configuration Modes

Configure each feature with the markdown_extensions key:

'markdown_extensions' => [ 'footnotes' => 'never', 'description_lists' => 'never', 'highlight' => 'never', 'smart_punctuation' => 'never', 'external_links' => 'never', 'attributes' => 'never', 'table_of_contents' => 'never', ],

Mode	Behaviour
`always`	Enabled for every Markdown document; frontmatter cannot disable it
`never`	Disabled for every Markdown document; frontmatter cannot enable it
`opt_in`	Disabled by default, but individual documents may enable it
`opt_out`	Enabled by default, but individual documents may disable it

For example:

'markdown_extensions' => [ 'footnotes' => 'opt_out', 'description_lists' => 'opt_in', 'highlight' => 'always', 'smart_punctuation' => 'always', 'external_links' => 'always', 'attributes' => 'never', 'table_of_contents' => 'opt_in', ],

Per-Document Frontmatter

Extensions configured as opt_in or opt_out can be controlled in content frontmatter:

--- title: Example Article markdown_extensions: table_of_contents: true description_lists: true footnotes: false ---

Frontmatter values do not override extensions configured as always or never.

Supported Extensions

Footnotes

A statement with a footnote.[^source] [^source]: The footnote content.

Inline footnotes are also supported:

A statement with an inline footnote.^[The footnote content.]

The generated markup includes .footnotes, .footnote, .footnote-ref, and .footnote-backref classes for theme styling.

Description Lists

Ava : A flat-file PHP content management system. CommonMark : The Markdown implementation used by Ava.

Highlighting

This text contains ==an important passage==.

Smart Punctuation

Smart punctuation automatically converts straight quotes, apostrophes, dashes, and ellipses into typographic equivalents.

"Quoted text" -- followed by an ellipsis...

External Links

External links receive secure relationship attributes by default: rel="noopener noreferrer".

Attributes

Attributes allow IDs, classes, and other HTML attributes to be assigned from Markdown:

{#introduction .featured} ## Introduction

Inline attributes are also supported:

This is *important*{.emphasis}.

Trusted authors only. Allowing document authors to add arbitrary attributes may introduce security or styling risks.

The table of contents extension automatically inserts linked heading navigation at the top of the document.

# Guide ## Installation ## Configuration ### Advanced Configuration

content.markdown.heading_ids must remain enabled for table-of-contents links to work.

Existing Markdown Features

Ava already enables GitHub Flavoured Markdown in core, including autolinks, strikethrough, tables, task lists, and disallowed raw HTML handling. These features are not controlled by the markdown-extensions plugin.

Performance

Disabled extensions are not registered with CommonMark and therefore add no parser overhead. Ava caches Markdown converters by their resolved extension combination. Documents using the same combination share a converter, including during pre-rendered HTML rebuilds.

Theme Styling

The default theme includes responsive styling for footnotes and backreferences, description lists, highlighted text, tables of contents, and heading permalinks.

Custom themes should consider styling mark, dl, dt, dd, .table-of-contents, .heading-permalink, .footnotes, .footnote, .footnote-ref, and .footnote-backref. Smart punctuation, external links, and custom attributes generally inherit existing prose styles and require no special default styling.

Markdown Reference

Paragraphs

Line Breaks

Headings

ATX Style (Recommended)

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Setext Style (H1 and H2 only)

Heading 1

Heading 2

Emphasis (Bold & Italic)

Strikethrough GFM

Lists

Unordered Lists

Ordered Lists

Nested Lists

Mixed Lists

Task Lists GFM

Links

Inline Links

Links with Titles

Reference Links

Autolinks

Automatic URL Linking GFM

Images

Basic Image

Image with Title

Linked Image

Code

Inline Code

Inline Code with Backticks

Fenced Code Blocks

Indented Code Blocks

Common Language Identifiers

Blockquotes

Basic Blockquote

Nested Blockquotes

Blockquotes with Other Elements

Heading in a quote

Horizontal Rules

Tables GFM

Basic Table

Column Alignment

Escaping Characters

Characters You Can Escape

Raw HTML

HTML Entities

Disallowed Tags

Ava-Specific Features Ava

Automatic Heading IDs

Path Aliases

Shortcodes

Optional Markdown Extensions Ava

Configuration Modes

Per-Document Frontmatter

Supported Extensions

Footnotes

Description Lists

Highlighting

Smart Punctuation

External Links

Attributes

Table of Contents

Existing Markdown Features

Performance

Theme Styling

Related Documentation