mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-12 16:47:26 +02:00
99 lines
No EOL
16 KiB
HTML
99 lines
No EOL
16 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 name="generator" content="Docusaurus"/><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"/><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 async="" defer="" src="https://buttons.github.io/buttons.js"></script><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-dark.min.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/en/installation.html" target="_self">Docs</a></li><li><a href="/en/help.html" target="_self">Help</a></li><li><a href="/blog" target="_self">Blog</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/en/installation.html">Installation</a></li><li class="navListItem"><a class="navItem" href="/docs/en/site-preparation.html">Site Preparation</a></li><li class="navListItem"><a class="navItem" href="/docs/en/site-creation.html">Creating your site</a></li><li class="navListItem"><a class="navItem" href="/docs/en/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/en/custom-pages.html">Custom Pages</a></li><li class="navListItem"><a class="navItem" href="/docs/en/navigation.html">Navigation and Sidebars</a></li><li class="navListItem"><a class="navItem" href="/docs/en/blog.html">Adding a Blog</a></li><li class="navListItem"><a class="navItem" href="/docs/en/translation.html">Translations & Localization</a></li><li class="navListItem"><a class="navItem" href="/docs/en/search.html">Enabling Search</a></li><li class="navListItem"><a class="navItem" href="/docs/en/versioning.html">Versioning</a></li></ul></div><div class="navGroup navGroupActive"><h3>API</h3><ul><li class="navListItem"><a class="navItem" href="/docs/en/commands.html">CLI Commands</a></li><li class="navListItem navListItemActive"><a class="navItem navItemActive" href="/docs/en/api-pages.html">Pages and Styles</a></li><li class="navListItem"><a class="navItem" href="/docs/en/site-config.html">siteConfig.js</a></li><li class="navListItem"><a class="navItem" href="/docs/en/doc-markdown.html">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</a><h1>Pages and Styles</h1></header><article><div><span><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/en/site-config.html">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><code class="language-jsx"><span class="hljs-keyword">const</span> Marked = CompLibrary.Marked;
|
||
|
||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">Marked</span>></span>[Markdown syntax for a link](http://www.example.com)<span class="hljs-tag"></<span class="hljs-name">Marked</span>></span></span>
|
||
</code></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><code class="language-jsx"><Container padding={["bottom", "top"]} background="light">
|
||
...
|
||
</Container>
|
||
</code></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><code><GridBlock
|
||
align=<span class="hljs-string">"center"</span>
|
||
contents={[
|
||
{
|
||
<span class="hljs-attribute">content</span>: <span class="hljs-string">"Learn how to use this project"</span>,
|
||
image: siteConfig<span class="hljs-selector-class">.baseUrl</span> + <span class="hljs-string">"img/learn.png"</span>,
|
||
title: `[Learn](${siteConfig.baseUrl}docs/tutorial.html)`,
|
||
imageLink: siteConfig<span class="hljs-selector-class">.baseUrl</span> + <span class="hljs-string">"docs/tutorial.html"</span>
|
||
},
|
||
{
|
||
<span class="hljs-attribute">content</span>: <span class="hljs-string">"Questions gathered from the community"</span>,
|
||
image: siteConfig<span class="hljs-selector-class">.baseUrl</span> + <span class="hljs-string">"img/faq.png"</span>,
|
||
imageAlign: <span class="hljs-string">"top"</span>,
|
||
title: <span class="hljs-string">"Frequently Asked Questions"</span>
|
||
},
|
||
{
|
||
<span class="hljs-attribute">content</span>: <span class="hljs-string">"Lots of documentation is on this site"</span>,
|
||
title: <span class="hljs-string">"More"</span>
|
||
}
|
||
]}
|
||
layout=<span class="hljs-string">"threeColumn"</span>
|
||
/>
|
||
</code></pre>
|
||
<p>More examples of how these components are used can be found in the <a href="/docs/en/site-preparation.html">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><code class="language-jsx"><p><span class="xml"><span class="hljs-tag"><<span class="hljs-name">translate</span>></span>I like translations<span class="hljs-tag"></<span class="hljs-name">translate</span>></span></span><span class="xml"><span class="hljs-tag"></<span class="hljs-name">p</span>></span></span>
|
||
</code></pre>
|
||
<p>You can also provide an optional description attribute to provide context for translators. e.g,</p>
|
||
<pre><code class="language-jsx"><a href="/community">
|
||
<translate desc="footer link to page referring to community github and slack">Community</translate>
|
||
</a>
|
||
</code></pre>
|
||
<p>Add the following require statement as well:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">"../../server/translate.js"</span>).translate;
|
||
</code></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">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 code block colors using the <code>colors</code> field in <code>siteConfig</code> as specified <a href="/docs/en/site-config.html">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/en/commands.html">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>
|
||
</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="site-config.html">siteConfig.js →</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"><span>Copyright © 2017 Facebook Inc.</span></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><script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script><script>hljs.initHighlightingOnLoad();</script></body></html> |