mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-10 23:57:22 +02:00
41 lines
No EOL
20 KiB
HTML
41 lines
No EOL
20 KiB
HTML
<html><head><meta charset="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1"/><title>Pages and Styles · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta property="og:title" content="Pages and Styles · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/index.html"/><meta property="og:description" content="Docusaurus provides support for writing pages as React components inside the `website/pages` folder which will share the same header, footer, and styles as the rest of the site."/><meta name="robots" content="noindex"/><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="/css/main.css"/><script async="" defer="" src="https://buttons.github.io/buttons.js"></script></head><body class="sideNavVisible"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/"><img src="/img/docusaurus.svg"/><h2>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="https://github.com/facebookexperimental/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#content">Installation</a></li><li class="navListItem"><a class="navItem" href="/docs/site-preparation.html#content">Site Preparation</a></li><li class="navListItem"><a class="navItem" href="/docs/site-creation.html#content">Creating your site</a></li></ul></div><div class="navGroup navGroupActive"><h3>Guides</h3><ul><li class="navListItem"><a class="navItem" href="/docs/custom-pages.html#content">Custom Pages</a></li><li class="navListItem"><a class="navItem" href="/docs/navigation.html#content">Navigation and Sidebars</a></li><li class="navListItem"><a class="navItem" href="/docs/blog.html#content">Adding a Blog</a></li><li class="navListItem"><a class="navItem" href="/docs/translation.html#content">Translations</a></li><li class="navListItem"><a class="navItem" href="/docs/search.html#content">Enabling Search</a></li><li class="navListItem"><a class="navItem" href="/docs/versioning.html#content">Versioning</a></li></ul></div><div class="navGroup navGroupActive"><h3>API</h3><ul><li class="navListItem"><a class="navItem" href="/docs/commands.html#content">CLI Commands</a></li><li class="navListItem navListItemActive"><a class="navItem navItemActive" href="/docs/api-pages.html#content">Pages and Styles</a></li><li class="navListItem"><a class="navItem" href="/docs/site-config.html#content">siteConfig.js</a></li><li class="navListItem"><a class="navItem" href="/docs/doc-markdown.html#content">Markdown Features</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/facebookexperimental/docusaurus/edit/master/docs/api-pages.md" target="_blank">Edit this Doc</a><h1>Pages and Styles</h1></header><article><div><p>Docusaurus provides support for writing pages as React components inside the <code>website/pages</code> folder which will share the same header, footer, and styles as the rest of the site.</p><h2><a class="anchor" name="urls-for-pages"></a>Urls for Pages <a class="hash-link" href="#urls-for-pages">#</a></h2><p>Any <code>.js</code> files in <code>website/pages</code> will be rendered to static html using the path of the file after "pages". Files in <code>website/pages/en</code> will also get copied out into <code>pages</code> and will OVERRIDE any files of the same name in <code>pages</code>. For example, the page for the <code>website/pages/en/help.js</code> file will be found at the url <code>${baseUrl}en/help.js</code> as well as the url <code>${baseUrl}help.js</code>, where <code>${baseUrl}</code> is the <code>baseUrl</code> field set in your <a href="/docs/site-config.html" target="">siteConfig.js file</a>.</p><h2><a class="anchor" name="page-require-paths"></a>Page Require Paths <a class="hash-link" href="#page-require-paths">#</a></h2><p>Docusaurus provides a few useful React components for users to write their own pages, found in the <code>CompLibrary</code> module. This module is provided as part of Docusaurus in <code>node_modules/docusaurus</code>, so to access it, pages in the <code>pages</code> folder are temporarily copied into <code>node_modules/docusaurus</code> when rendering to static html. As seen in the example files, this means that a user page at <code>pages/en/index.js</code> uses a require path to <code>"../../core/CompLibrary.js"</code> to import the provided components.</p><p>What this means to the user is that if you wish to use the <code>CompLibrary</code> module, make sure the require path is set correctly. For example, a page at <code>page/mypage.js</code> would use a path <code>"../core/CompLibrary.js"</code>.</p><p>If you wish to use your own components inside the website folder, use <code>process.cwd()</code> which will refer to the <code>website</code> folder to construct require paths. For example, if you add a component to <code>website/core/mycomponent.js</code>, you can use the require path, <code>"process.cwd() + /core/mycomponent.js"</code>.</p><h2><a class="anchor" name="provided-components"></a>Provided Components <a class="hash-link" href="#provided-components">#</a></h2><p>Docusaurus provides the following components in <code>CompLibrary</code>:</p><h3><a class="anchor" name="complibrarymarked"></a><code>CompLibrary.Marked</code> <a class="hash-link" href="#complibrarymarked">#</a></h3><p>A React component that parses Markdown to html.</p><p>Example:</p><pre class="prism language-jsx"><span class="token keyword">const</span> Marked <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>Marked<span class="token punctuation">;</span>
|
||
|
||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Marked</span><span class="token punctuation">></span></span><span class="token punctuation">[</span>Markdown syntax <span class="token keyword">for</span> a link<span class="token punctuation">]</span><span class="token punctuation">(</span>http<span class="token punctuation">:</span><span class="token operator">/</span><span class="token operator">/</span>www<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com<span class="token punctuation">)</span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>Marked</span><span class="token punctuation">></span></span></pre><h3><a class="anchor" name="complibrarycontainer"></a><code>CompLibrary.Container</code> <a class="hash-link" href="#complibrarycontainer">#</a></h3><p>A React container component using Docusaurus styles. Has optional padding and background color attributes that you can configure.</p><p>Padding choices: <code>all</code>, <code>bottom</code>, <code>left</code>, <code>right</code>, <code>top</code>.<br/>Background choices: <code>dark</code>, <code>highlight</code>, <code>light</code>.</p><p>Example:</p><pre class="prism language-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span> <span class="token attr-name">padding</span><span class="token script language-javascript"><span class="token punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span><span class="token string">"bottom"</span><span class="token punctuation">,</span> <span class="token string">"top"</span><span class="token punctuation">]</span><span class="token punctuation">}</span></span> <span class="token attr-name">background</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>light<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||
<span class="token operator">...</span>
|
||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>Container</span><span class="token punctuation">></span></span></pre><h3><a class="anchor" name="complibrarygridblock"></a><code>CompLibrary.GridBlock</code> <a class="hash-link" href="#complibrarygridblock">#</a></h3><p>A React component to organize text and images. </p><p>The <code>align</code> attribute determines text alignment. Text alignment defaults to <code>left</code> and can be set to <code>center</code> or <code>right</code>.</p><p>The <code>layout</code> attribute determines number of column sections per GridBlock. <code>layout</code> defaults to <code>twoColumn</code> and can be set to <code>threeColumn</code> or <code>fourColumn</code> as well.</p><p>The <code>contents</code> attribute is an array containing the contents of each section of the GridBlock. Each content object can have the following fields: </p><ul><li><code>content</code> for the text of this section, which is parsed from markdown</li><li><code>image</code> for the path to an image to display </li><li><code>imageAlign</code> field for image alignment relative to the text, which defaults to <code>top</code> and can be set to <code>bottom</code>, <code>left</code>, or <code>right</code></li><li><code>title</code> for the title to display for this section, which is parsed from markdown</li><li><code>imageLink</code> for a link destination from clicking the image</li></ul><p>Example:</p><pre class="prism language-javascript"><span class="token operator"><</span>GridBlock
|
||
align<span class="token operator">=</span><span class="token string">"center"</span>
|
||
contents<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span>
|
||
<span class="token punctuation">{</span>
|
||
content<span class="token punctuation">:</span> <span class="token string">"Learn how to use this project"</span><span class="token punctuation">,</span>
|
||
image<span class="token punctuation">:</span> siteConfig<span class="token punctuation">.</span>baseUrl <span class="token operator">+</span> <span class="token string">"img/learn.png"</span><span class="token punctuation">,</span>
|
||
title<span class="token punctuation">:</span> <span class="token template-string"><span class="token string">`[Learn](</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>siteConfig<span class="token punctuation">.</span>baseUrl<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">docs/tutorial.html)`</span></span><span class="token punctuation">,</span>
|
||
imageLink<span class="token punctuation">:</span> siteConfig<span class="token punctuation">.</span>baseUrl <span class="token operator">+</span> <span class="token string">"docs/tutorial.html"</span>
|
||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||
<span class="token punctuation">{</span>
|
||
content<span class="token punctuation">:</span> <span class="token string">"Questions gathered from the community"</span><span class="token punctuation">,</span>
|
||
image<span class="token punctuation">:</span> siteConfig<span class="token punctuation">.</span>baseUrl <span class="token operator">+</span> <span class="token string">"img/faq.png"</span><span class="token punctuation">,</span>
|
||
imageAlign<span class="token punctuation">:</span> <span class="token string">"top"</span><span class="token punctuation">,</span>
|
||
title<span class="token punctuation">:</span> <span class="token string">"Frequently Asked Questions"</span>
|
||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||
<span class="token punctuation">{</span>
|
||
content<span class="token punctuation">:</span> <span class="token string">"Lots of documentation is on this site"</span><span class="token punctuation">,</span>
|
||
title<span class="token punctuation">:</span> <span class="token string">"More"</span>
|
||
<span class="token punctuation">}</span>
|
||
<span class="token punctuation">]</span><span class="token punctuation">}</span>
|
||
layout<span class="token operator">=</span><span class="token string">"threeColumn"</span>
|
||
<span class="token operator">/</span><span class="token operator">></span></pre><p>More examples of how these components are used can be found in the <a href="/docs/site-preparation.html" target="">generated example files</a> as well as in Docusaurus's own repo for its website set-up.</p><h2><a class="anchor" name="translating-strings"></a>Translating Strings <a class="hash-link" href="#translating-strings">#</a></h2><p>When translations are enabled, any pages inside <code>website/pages/en</code> will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the <code>languages.js</code> file. E.g. The url for a French page of <code>website/pages/en/help.js</code> would be found at <code>${baseUrl}fr/help.html</code>.</p><p>When writing pages that you wish to translate, wrap any strings to be translated inside a <code><translate></code> tag. e.g.,</p><pre class="prism language-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span>I like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span></pre><p>You can also provide an optional description attribute to provide context for translators. e.g,</p><pre class="prism language-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>footer link to page referring to community github and slack<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Community<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</span><span class="token punctuation">></span></span></pre><p>Add the following require statement as well:</p><pre class="prism language-js"><span class="token keyword">const</span> translate <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"../../server/translate.js"</span><span class="token punctuation">)</span><span class="token punctuation">.</span>translate<span class="token punctuation">;</span></pre><p>Note that this path is valid for files inside <code>pages/en</code> and should be adjusted accordingly if files are in different locations, as discussed <a href="#page-require-paths" target="">above</a>.</p><h2><a class="anchor" name="using-static-assets"></a>Using Static Assets <a class="hash-link" href="#using-static-assets">#</a></h2><p>Static assets should be placed into the <code>website/static</code> folder. They can be accesssed by their paths, excluding "static". For example, if the site's <code>baseUrl</code> is "/docusaurus/", an image in <code>website/static/img/logo.png</code> is available at <code>/docusaurus/img/logo.png</code>.</p><h2><a class="anchor" name="styles"></a>Styles <a class="hash-link" href="#styles">#</a></h2><p>You should configure your site's primary, secondary, and Prism colors using the <code>colors</code> field in <code>siteConfig</code> as specified <a href="site-config.md" target="_blank">here</a>. You can also configure other colors in the same way as described in the <code>siteConfig</code> doc.</p><p>You can provide your own custom styles by adding them anywhere in the <code>website/static</code> folder. Any <code>.css</code> files you provide in the <code>static</code> folder will get concatenated to the end of Docusaurus's provided styles, allowing you to add to or override Docusaurus default styles as you wish.</p><p>An easy way to figure out what classes you wish to override or add to is to <a href="/docs/commands.html" target="">start your server locally</a> and use your browser's inspect element tool.</p><h2><a class="anchor" name="adding-static-pages"></a>Adding Static Pages <a class="hash-link" href="#adding-static-pages">#</a></h2><p>Static <code>.html</code> files can also be used, but they will not include Docusaurus's header, footer, or styles by default. These can be added to the <code>static</code> folder in the same way as other static assets. Alternatively, they can be placed in the <code>pages</code> folder and would be served as-is instead of being rendered from React.</p><p>If you wish to use Docusaurus's stylesheet, you can access it at <code>${baseUrl}css/main.css</code>. If you wish to use separate css for these static pages, you can exclude them from being concatenated to Docusaurus's styles by adding them into the <code>siteConfig.separateCss</code> field.</p></div></article></div><div class="docs-prevnext"><a class="docs-prev button" href="commands.html#content">← Previous</a><a class="docs-next button" href="site-config.html#content">Next →</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/installation.html">Getting Started</a></div><div><h5>Community</h5><a href="/en/users.html">User Showcase</a></div><div><h5>More</h5><a href="https://github.com/facebookexperimental/docusaurus">GitHub</a><a class="github-button" href="https://github.com/facebookexperimental/docusaurus" data-icon="octicon-star" data-count-href="/facebookexperimental/docusaurus/stargazers" data-count-api="/repos/facebookexperimental/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">Copyright © 2017 Facebook Inc.</section></footer></div><script type="text/javascript" src="//cdn.jsdelivr.net/docsearch.js/1/docsearch.min.js"></script><script>
|
||
var search = docsearch({
|
||
apiKey: '3eb9507824b8be89e7a199ecaa1a9d2c',
|
||
indexName: 'docusaurus',
|
||
inputSelector: '#search_input_react'
|
||
});
|
||
</script></body></html> |