`, as-is. However, _that is not the case_.
The Markdown syntax `` only declaratively tells Docusaurus that an image needs to be inserted here, but we may do other things like transforming a [file path to URL path](/guides/guides-markdown-features-markdown-features-assets#images), so the generated markup may differ from the output of other Markdown renderers, or a naΓ―ve hand-transcription to the equivalent JSX/HTML code.
In general, you should only assume the _semantics_ of the markup (` ``` ` fences become [code blocks](/guides/guides-markdown-features-markdown-features-code-blocks); `>` becomes [quotes](#quotes), etc.), but not the actual compiled output.
:::
## Front matter
Front matter is used to add metadata to your Markdown file. All content plugins have their own front matter schema, and use the front matter to enrich the default metadata inferred from the content or other configuration.
Front matter is provided at the very top of the file, enclosed by three dashes `---`. The content is parsed as [YAML](https://yaml.org/spec/1.2.2/).
```md
---
title: My Doc Title
more_data:
- Can be provided
- as: objects
or: arrays
---
```
:::callout{intent="info"}
The API documentation of each official plugin lists the supported attributes:
- [Docs front matter](/guides/api-plugins-plugin-content-docs#markdown-front-matter)
- [Blog front matter](/guides/api-plugins-plugin-content-blog#markdown-front-matter)
- [Pages front matter](/guides/api-plugins-plugin-content-pages#markdown-front-matter)
:::
:::callout{intent="tip" title="enhance your front matter"}
Use the [Markdown config `parseFrontMatter` function](/guides/api-docusaurus-config-js#markdown) to provide your own front matter parser, or to enhance the default parser.
It is possible to reuse the default parser to wrap it with your own custom proprietary logic. This makes it possible to implement convenient front matter transformations, shortcuts, or to integrate with external systems using front matter that Docusaurus plugins do not support.
```js title="docusaurus.config.js" {3-24}
export default {
markdown: {
parseFrontMatter: async (params) => {
// Reuse the default parser
const result = await params.defaultParseFrontMatter(params);
// Process front matter description placeholders
result.frontMatter.description =
result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
// Create your own front matter shortcut
if (result.frontMatter.i_do_not_want_docs_pagination) {
result.frontMatter.pagination_prev = null;
result.frontMatter.pagination_next = null;
}
// Rename an unsupported front matter coming from another system
if (result.frontMatter.cms_seo_summary) {
result.frontMatter.description = result.frontMatter.cms_seo_summary;
delete result.frontMatter.cms_seo_summary;
}
return result;
},
},
};
```
:::
## Quotes
Markdown quotes are beautifully styled:
```md
> Easy to maintain open source documentation websites.
>
> β Docusaurus
```
> Easy to maintain open source documentation websites.
>
> β Docusaurus
## Details
Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) HTML elements are beautifully styled:
````md
### Details element example
` paragraphs for line breaks.](https://mdxjs.com/migrating/v2/#jsx). When in doubt, use the [MDX playground](https://mdxjs.com/playground/) to troubleshoot `