mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-12 00:27:21 +02:00
126 lines
No EOL
20 KiB
HTML
126 lines
No EOL
20 KiB
HTML
<html lang="en"><head><meta charset="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1"/><title>Markdown Features · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta property="og:title" content="Markdown Features · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/index.html"/><meta property="og:description" content="## Markdown Headers"/><meta property="og:image" content="https://docusaurus.io/img/docusaurus.png"/><link rel="shortcut icon" href="/img/docusaurus.ico"/><link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-dark.min.css"/><link rel="alternate" type="application/atom+xml" href="https://docusaurus.io/blog/atom.xml" title="Docusaurus Blog ATOM Feed"/><link rel="alternate" type="application/rss+xml" href="https://docusaurus.io/blog/feed.xml" title="Docusaurus Blog RSS Feed"/><script type="text/javascript" src="https://buttons.github.io/buttons.js"></script><link rel="stylesheet" href="/css/main.css"/></head><body class="sideNavVisible"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/"><img class="logo" src="/img/docusaurus.svg"/><h2 class="headerTitle">Docusaurus</h2></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li><a href="/docs/installation.html" target="_self">Docs</a></li><li><a href="/en/help.html" target="_self">Help</a></li><li><a href="/en/about-slash.html" target="_self">About /</a></li><li><a href="/blog" target="_self">Blog</a></li><li><a href="https://github.com/facebook/docusaurus" target="_self">GitHub</a></li><li class="navSearchWrapper reactNavSearchWrapper"><input type="text" id="search_input_react" placeholder="Search"/></li></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><div class="container docsNavContainer" id="docsNav"><nav class="toc"><div class="toggleNav"><section class="navWrapper wrapper"><div class="navBreadcrumb wrapper"><div class="navToggle" id="navToggler"><i></i></div><h2><i>›</i><span>API</span></h2></div><div class="navGroups"><div class="navGroup navGroupActive"><h3>Getting Started</h3><ul><li class="navListItem"><a class="navItem" href="/docs/installation.html">Installation</a></li><li class="navListItem"><a class="navItem" href="/docs/site-preparation.html">Site Preparation</a></li><li class="navListItem"><a class="navItem" href="/docs/site-creation.html">Creating your site</a></li><li class="navListItem"><a class="navItem" href="/docs/publishing.html">Publishing your site</a></li></ul></div><div class="navGroup navGroupActive"><h3>Guides</h3><ul><li class="navListItem"><a class="navItem" href="/docs/blog.html">Adding a Blog</a></li><li class="navListItem"><a class="navItem" href="/docs/custom-pages.html">Custom Pages</a></li><li class="navListItem"><a class="navItem" href="/docs/search.html">Enabling Search</a></li><li class="navListItem"><a class="navItem" href="/docs/navigation.html">Navigation and Sidebars</a></li><li class="navListItem"><a class="navItem" href="/docs/translation.html">Translations & Localization</a></li><li class="navListItem"><a class="navItem" href="/docs/versioning.html">Versioning</a></li></ul></div><div class="navGroup navGroupActive"><h3>API</h3><ul><li class="navListItem"><a class="navItem" href="/docs/commands.html">CLI Commands</a></li><li class="navListItem navListItemActive"><a class="navItem navItemActive" href="/docs/doc-markdown.html">Markdown Features</a></li><li class="navListItem"><a class="navItem" href="/docs/api-pages.html">Pages and Styles</a></li><li class="navListItem"><a class="navItem" href="/docs/site-config.html">siteConfig.js</a></li></ul></div></div></section></div><script>
|
||
var toggler = document.getElementById('navToggler');
|
||
var nav = document.getElementById('docsNav');
|
||
toggler.onclick = function() {
|
||
nav.classList.toggle('docsSliderActive');
|
||
};
|
||
</script></nav></div><div class="container mainContainer"><div class="wrapper"><div class="post"><header class="postHeader"><a class="edit-page-link button" href="https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md" target="_blank">Edit</a><h1>Markdown Features</h1></header><article><div><span><h2><a class="anchor" aria-hidden="true" name="markdown-headers"></a><a href="#markdown-headers" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Markdown Headers</h2>
|
||
<h3><a class="anchor" aria-hidden="true" name="documents"></a><a href="#documents" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Documents</h3>
|
||
<p>Documents use the following markdown header fields that are enclosed by a line <code>---</code> on either side:</p>
|
||
<p><code>id</code>: A unique document id. If this field is not present, the document's <code>id</code> will default to it's file name (without the extension).</p>
|
||
<p><code>title</code>: The title of your document. If this field is not present, the document's <code>title</code> will default to it's <code>id</code>.</p>
|
||
<p><code>sidebar_label</code>: The text shown in the document sidebar for this document. If this field is not present, the document's <code>sidebar_label</code> will default to it's <code>title</code>.</p>
|
||
<p>For example:</p>
|
||
<pre><code class="hljs css markdown">---
|
||
id: doc1
|
||
title: My Document
|
||
<span class="hljs-section">sidebar_label: Document
|
||
---</span>
|
||
</code></pre>
|
||
<p>Versioned documents have their ids altered to include the version number when they get copied. The new <code>id</code> is <code>version-${version}-${id}</code> where <code>${version}</code> is the version number of that document and <code>${id}</code> is the original <code>id</code>. Additionally, versioned documents get an added <code>original_id</code> field with the original document id.</p>
|
||
<p>For example:</p>
|
||
<pre><code class="hljs css markdown">---
|
||
id: version-1.0.0-doc1
|
||
title: My Document
|
||
sidebar_label: Document
|
||
<span class="hljs-section">original_id: doc1
|
||
---</span>
|
||
</code></pre>
|
||
<h3><a class="anchor" aria-hidden="true" name="blog-posts"></a><a href="#blog-posts" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Blog Posts</h3>
|
||
<p>Blog Posts use the following markdown header fields that are enclosed by a line <code>---</code> on either side:</p>
|
||
<p><code>title</code>: The title of this blog post.</p>
|
||
<p><code>author</code>: The author of this blog post. If this field is omitted, no author name will be shown.</p>
|
||
<p><code>authorURL</code>: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.</p>
|
||
<p><code>authorFBID</code>: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.</p>
|
||
<p>For example:</p>
|
||
<pre><code class="hljs css markdown">---
|
||
title: My First Blog Post
|
||
author: Frank Li
|
||
authorURL: http://twitter.com/franchementli
|
||
<span class="hljs-section">authorFBID: 100002976521003
|
||
---</span>
|
||
</code></pre>
|
||
<h2><a class="anchor" aria-hidden="true" name="extra-features"></a><a href="#extra-features" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Extra Features</h2>
|
||
<p>Docusaurus supports some extra features when writing documentation in markdown.</p>
|
||
<h3><a class="anchor" aria-hidden="true" name="linking-other-documents"></a><a href="#linking-other-documents" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking other Documents</h3>
|
||
<p>You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.</p>
|
||
<p>Example:</p>
|
||
<pre><code class="hljs css markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||
</code></pre>
|
||
<p>This markdown will automatically get converted into a link to <code>/docs/other-document.html</code> (or the appropriately translated/versioned link) once it gets rendered.</p>
|
||
<p>This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.</p>
|
||
<h3><a class="anchor" aria-hidden="true" name="linking-to-images-and-other-assets"></a><a href="#linking-to-images-and-other-assets" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking to Images and Other Assets</h3>
|
||
<p>Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into <code>docs/assets</code> and <code>website/blog/assets</code>, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.</p>
|
||
<p>Example:</p>
|
||
<pre><code class="hljs css markdown">
|
||
</code></pre>
|
||
<h3><a class="anchor" aria-hidden="true" name="generating-table-of-contents"></a><a href="#generating-table-of-contents" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Generating Table of Contents</h3>
|
||
<p>You can make an autogenerated list of links, which can be useful as a table of contents for API docs.</p>
|
||
<p>In your markdown file, insert a line with the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>. Write your documentation using <code>h3</code> headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>.</p>
|
||
<p>Example:</p>
|
||
<pre><code class="hljs css markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||
|
||
Text describing my function
|
||
|
||
|
||
<span class="hljs-section">### `docdoc(file)`</span>
|
||
|
||
Text describing my function
|
||
</code></pre>
|
||
<p>will lead to a table of contents of the functions:</p>
|
||
<pre><code class="hljs css markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||
<span class="hljs-bullet">- </span><span class="hljs-code">`docdoc(file)`</span>
|
||
</code></pre>
|
||
<p>and each function will link to their corresponding sections in the page.</p>
|
||
<h2><a class="anchor" aria-hidden="true" name="syntax-highlighting"></a><a href="#syntax-highlighting" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Syntax Highlighting</h2>
|
||
<p>Syntax highlighting is enabled by default on fenced code blocks. The language should be detected automatically, but you can sometimes get better results by specifying the language. You can do so using an <a href="https://github.github.com/gfm/#example-111">info string</a>, following the three opening backticks. The following JavaScript example...</p>
|
||
<pre><code class="hljs">```javascript
|
||
ReactDOM.render(
|
||
<h1>Hello, world!</h1>,
|
||
document.getElementById('root')
|
||
);
|
||
```
|
||
</code></pre>
|
||
<p>...would be rendered with syntax highlighting like so:</p>
|
||
<pre><code class="hljs css javascript">ReactDOM.render(
|
||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">h1</span>></span>Hello, world!<span class="hljs-tag"></<span class="hljs-name">h1</span>></span></span>,
|
||
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'root'</span>)
|
||
);
|
||
</code></pre>
|
||
<p>Highlighting is provided by <a href="https://highlightjs.org">Highlight.js</a> using the theme specified in your <code>siteConfig.js</code> file as part of the <code>highlight</code> key:</p>
|
||
<pre><code class="hljs css javascript">highlight: {
|
||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>
|
||
}
|
||
</code></pre>
|
||
<p>You can find the full list of supported themes in the Highlight.js <a href="https://github.com/isagalaev/highlight.js/tree/master/src/styles"><code>styles</code></a> directory.</p>
|
||
<h3><a class="anchor" aria-hidden="true" name="registering-additional-languages"></a><a href="#registering-additional-languages" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Registering additional languages</h3>
|
||
<p>While Highlight.js provides support for <a href="https://highlightjs.org/static/demo/">many popular languages out of the box</a>, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the <code>hljs</code> constant as part of the <code>highlight</code> config key. This in turn allows you to call <a href="http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language"><code>registerLanguage</code></a>:</p>
|
||
<pre><code class="hljs css javascript">highlight: {
|
||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>,
|
||
<span class="hljs-attr">hljs</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||
hljs.registerLanguage(<span class="hljs-string">'galacticbasic'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||
<span class="hljs-comment">// ...</span>
|
||
});
|
||
}
|
||
}
|
||
</code></pre>
|
||
</span></div></article></div><div class="docs-prevnext"><a class="docs-prev button" href="commands.html">← CLI Commands</a><a class="docs-next button" href="api-pages.html">Pages and Styles →</a></div></div></div></div><footer class="nav-footer" id="footer"><section class="sitemap"><a href="/" class="nav-home"><img src="/img/docusaurus_monochrome.svg" alt="Docusaurus" width="66" height="58"/></a><div><h5>Docs</h5><a href="
|
||
/docs/en/installation.html">Getting Started</a><a href="
|
||
/docs/en/versioning.html">Versioning</a><a href="
|
||
/docs/en/translation.html">Localization</a><a href="
|
||
/docs/en/search.html">Adding Search</a></div><div><h5>Community</h5><a href="/en/users.html">User Showcase</a><a href="https://twitter.com/docusaurus">Twitter</a></div><div><h5>More</h5><a href="https://github.com/facebook/docusaurus">GitHub</a><a class="github-button" href="https://github.com/facebook/Docusaurus" data-icon="octicon-star" data-count-href="/facebook/Docusaurus/stargazers" data-count-api="/repos/facebook/Docusaurus#stargazers_count" data-count-aria-label="# stargazers on GitHub" aria-label="Star this project on GitHub">Star</a></div></section><a href="https://code.facebook.com/projects/" target="_blank" class="fbOpenSource"><img src="/img/oss_logo.png" alt="Facebook Open Source" width="170" height="45"/></a><section class="copyright"><span>Copyright © 2017 Facebook Inc.</span></section></footer></div><script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.js"></script><script>
|
||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
||
|
||
ga('create', 'UA-44373548-31', 'auto');
|
||
ga('send', 'pageview');
|
||
</script><script>window.fbAsyncInit = function() {FB.init({appId:'1615782811974223',xfbml:true,version:'v2.7'});};(function(d, s, id){var js, fjs = d.getElementsByTagName(s)[0];if (d.getElementById(id)) {return;}js = d.createElement(s); js.id = id;js.src = '//connect.facebook.net/en_US/sdk.js';fjs.parentNode.insertBefore(js, fjs);}(document, 'script','facebook-jssdk'));
|
||
</script><script>window.twttr=(function(d,s, id){var js,fjs=d.getElementsByTagName(s)[0],t=window.twttr||{};if(d.getElementById(id))return t;js=d.createElement(s);js.id=id;js.src='https://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js, fjs);t._e = [];t.ready = function(f) {t._e.push(f);};return t;}(document, 'script', 'twitter-wjs'));</script><script>
|
||
var search = docsearch({
|
||
apiKey: '3eb9507824b8be89e7a199ecaa1a9d2c',
|
||
indexName: 'docusaurus',
|
||
inputSelector: '#search_input_react'
|
||
});
|
||
</script></body></html> |