mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-12 16:47:26 +02:00
54 lines
No EOL
21 KiB
HTML
54 lines
No EOL
21 KiB
HTML
<html><head><meta charset="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1"/><title>getting-started · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta property="og:title" content="getting-started · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/index.html"/><meta property="og:description" content="## Getting Started"/><meta name="robots" content="noindex"/><link rel="shortcut icon" href="/img/favicon.png"/><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></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><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/getting-started.md" target="_blank">Edit this Doc</a><h1>getting-started</h1></header><article><div><h2><a class="anchor" name="getting-started"></a>Getting Started <a class="hash-link" href="#getting-started">#</a></h2><h3><a class="anchor" name="project-structure"></a>Project Structure <a class="hash-link" href="#project-structure">#</a></h3><p>In your project repo, all of your documentation files should be placed inside a <code>docs</code> folder. Any blog posts should be inside a <code>blog</code> folder. Create a <code>website</code> folder inside which you will install and run docusaurus.</p><p>Example project structure:</p><pre class="prism language-javascript">project<span class="token operator">-</span>repo<span class="token operator">/</span>
|
|
blog<span class="token operator">/</span>
|
|
<span class="token number">2017</span><span class="token operator">-</span><span class="token number">05</span><span class="token operator">-</span><span class="token number">06</span><span class="token operator">-</span>blog<span class="token operator">-</span>post<span class="token punctuation">.</span>md
|
|
docs<span class="token operator">/</span>
|
|
en<span class="token operator">/</span>
|
|
doc1<span class="token punctuation">.</span>md
|
|
website<span class="token operator">/</span></pre><h3><a class="anchor" name="installation"></a>Installation <a class="hash-link" href="#installation">#</a></h3><p>Inside of your <code>website</code> folder, create a <code>package.json</code> file with the following scripts for Docusaurus:</p><pre class="prism language-json"><span class="token punctuation">{</span>
|
|
<span class="token property">"scripts"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
|
|
<span class="token property">"start"</span><span class="token operator">:</span> <span class="token string">"docusaurus-start"</span><span class="token punctuation">,</span>
|
|
<span class="token property">"build"</span><span class="token operator">:</span> <span class="token string">"docusaurus-build"</span><span class="token punctuation">,</span>
|
|
<span class="token property">"publish-gh-pages"</span><span class="token operator">:</span> <span class="token string">"docusaurus-publish"</span><span class="token punctuation">,</span>
|
|
<span class="token property">"examples"</span><span class="token operator">:</span> <span class="token string">"docusaurus-examples"</span>
|
|
<span class="token punctuation">}</span>
|
|
<span class="token punctuation">}</span></pre><p>Install Docusaurus using <code>npm</code> or <code>yarn</code>:</p><pre class="prism language-javascript">npm install <span class="token operator">--</span>save<span class="token operator">-</span>dev docusaurus</pre><p>or</p><pre class="prism language-javascript">yarn add docusaurus <span class="token operator">-</span>dev</pre><h2><a class="anchor" name="configuration"></a>Configuration <a class="hash-link" href="#configuration">#</a></h2><h3><a class="anchor" name="generate-examples"></a>Generate Examples <a class="hash-link" href="#generate-examples">#</a></h3><p>To create example files for configuration, run <code>examples</code> using <code>npm</code> or <code>yarn</code>:</p><pre class="prism language-javascript">npm run examples</pre><p>or</p><pre class="prism language-javascript">yarn run examples</pre><p>This will create the following files/folders in your website folder:</p><pre class="prism language-javascript">core<span class="token operator">/</span>Footer<span class="token punctuation">.</span>js
|
|
pages<span class="token operator">/</span><span class="token operator">...</span>
|
|
<span class="token keyword">static</span><span class="token regex">/img/</span><span class="token operator">...</span>
|
|
siteConfig<span class="token punctuation">.</span>js</pre><p>It will also create two folders in the level above the website folder in your project repo:</p><pre class="prism language-javascript">blog<span class="token operator">-</span>examples<span class="token operator">-</span><span class="token keyword">from</span><span class="token operator">-</span>docusaurus
|
|
docs<span class="token operator">-</span>examples<span class="token operator">-</span><span class="token keyword">from</span><span class="token operator">-</span>docusaurus</pre><p>If any of the files created by <code>yarn run examples</code> already exists, Docusaurus will not overwrite them.</p><p>The provided example files contain configurations for an example site. </p><p>The <code>core/Footer.js</code> file is a React component that acts as the footer for the site generated by Docusaurus and should be customized by the user.<br/>The <code>blog-examples-from-docusaurus</code> folder contains examples of blog posts written in markdown.<br/>The <code>docs-examples-from-docusaurus</code> folder contains example documentation files written in markdown.<br/>The <code>pages</code> folder contains example top-level pages for the site.<br/>The <code>static</code> folder contains static assets used by the example site.<br/>The <code>siteConfig.js</code> file is the main configuration file used by Docusaurus. </p><p>You will need to keep the <code>siteConfig.js</code> and <code>core/Footer.js</code> files, but may edit them as you wish.</p><p>You should keep the <code>pages</code> and <code>static</code> folders, but may change the content inside them as you wish. At the bare minimum you should have an <code>en/index.js</code> or <code>en/index.html</code> file inside <code>pages</code> and an image to use as your header icon inside <code>static</code>.</p><p>The <code>blog-examples-from-docusaurus</code> and <code>docs-examples-from-docusaurus</code> folders contain example blog and document markdown files. If you wish to run Docusaurus with these files, you need to rename the folders to <code>blog</code> and <code>docs</code>, respectively.</p><h3><a class="anchor" name="how-to-configure-your-site"></a>How to Configure Your Site <a class="hash-link" href="#how-to-configure-your-site">#</a></h3><p>Configure the <code>siteConfig.js</code> file which has comments guiding you through what needs to be done and how each configuration affects your website. You can also refer <a href="/docs/en/site-configuration.md" target="">here</a> for more details.</p><p>Customize <code>core/Footer.js</code> which will serve as the footer for each page on your website.</p><p>Include your own top-level pages as React components in <code>pages</code>:</p><ul><li>These components should just be the body sections of the pages you want, and they will be included with the header and footer that the rest of Docusaurus uses. </li><li>Currently, if you want to add other React components to your pages, you must include all of it inside each <code>.js</code> file in <code>pages</code> due to how <code>require</code> paths are set-up. </li><li>You may also include <code>.html</code> files directly, but this is not recommended, and these will just be served as is and will not have any of the header/footer/styles shared by the rest of Docusaurus.</li><li>Any files in <code>pages/en</code> will also be copied into <code>pages</code> when the server is run and when the site is statically built. i.e. Putting a file in <code>pages/en/index.js</code> will make it available at <code>/en/index.html</code> and <code>/index.html</code>.</li></ul><p>All images and other static assets you wish to include should be placed inside the <code>static</code> folder. Any <code>.css</code> files provided in <code>static</code> will be concatenated to the standard styles provided by Docusaurus and used site-wide.</p><p>A React component placed in <code>website/pages/en/index.js</code> will be available at the url <code>/en/index.html</code>. A static html page placed in <code>website/pages/en/index.html</code> will be available at the url <code>/en/index.html</code>. Provided html files will override provided React components.</p><p>A static asset placed in <code>website/static/img/image.png</code> will be available at the url <code>/img/image.png</code>.</p><p>Example:</p><pre class="prism language-javascript">localhost<span class="token punctuation">:</span><span class="token number">3000</span>$<span class="token punctuation">{</span>baseUrl<span class="token punctuation">}</span>en<span class="token operator">/</span>index<span class="token punctuation">.</span>html
|
|
localhost<span class="token punctuation">:</span><span class="token number">3000</span>$<span class="token punctuation">{</span>baseUrl<span class="token punctuation">}</span>img<span class="token operator">/</span>image<span class="token punctuation">.</span>png
|
|
$<span class="token punctuation">{</span>url<span class="token punctuation">}</span>$<span class="token punctuation">{</span>baseUrl<span class="token punctuation">}</span>en<span class="token operator">/</span>index<span class="token punctuation">.</span>html
|
|
$<span class="token punctuation">{</span>url<span class="token punctuation">}</span>$<span class="token punctuation">{</span>baseUrl<span class="token punctuation">}</span>img<span class="token operator">/</span>image<span class="token punctuation">.</span>png</pre><h3><a class="anchor" name="document-and-blog-front-matters"></a>Document and Blog Front Matters <a class="hash-link" href="#document-and-blog-front-matters">#</a></h3><p>Documentation should contain front matter that follows this example:</p><pre class="prism language-javascript"><span class="token operator">--</span><span class="token operator">-</span>
|
|
id<span class="token punctuation">:</span> doc1 <span class="token operator"><</span><span class="token operator">!</span><span class="token operator">--</span> used <span class="token keyword">for</span> docs to find each other and to map links <span class="token operator">--</span><span class="token operator">></span>
|
|
title<span class="token punctuation">:</span> Document Title
|
|
layout<span class="token punctuation">:</span> docs1 <span class="token operator"><</span><span class="token operator">!</span><span class="token operator">--</span> used to determine different sidebar groupings <span class="token operator">--</span><span class="token operator">></span>
|
|
category<span class="token punctuation">:</span> Sidebar Category <span class="token number">1</span> <span class="token operator"><</span><span class="token operator">!</span><span class="token operator">--</span> category on the sidebar under which <span class="token keyword">this</span> doc goes <span class="token operator">--</span><span class="token operator">></span>
|
|
permalink<span class="token punctuation">:</span> docs<span class="token operator">/</span>en<span class="token operator">/</span>doc1<span class="token punctuation">.</span>html <span class="token operator"><</span><span class="token operator">!</span><span class="token operator">--</span> link to the document that is used <span class="token keyword">for</span> site <span class="token operator">--</span><span class="token operator">></span>
|
|
previous<span class="token punctuation">:</span> doc0 <span class="token operator"><</span><span class="token operator">!</span><span class="token operator">--</span> previous doc on sidebar <span class="token keyword">for</span> navigation <span class="token operator">--</span><span class="token operator">></span>
|
|
next<span class="token punctuation">:</span> doc2 <span class="token operator"><</span><span class="token operator">!</span><span class="token operator">--</span> next doc on the sidebar <span class="token keyword">for</span> navigation <span class="token operator">--</span><span class="token operator">></span>
|
|
<span class="token operator"><</span><span class="token operator">!</span><span class="token operator">--</span> don<span class="token string">'t include next if this is the last doc; don'</span>t include previous <span class="token keyword">if</span> first doc <span class="token operator">--</span><span class="token operator">></span>
|
|
<span class="token operator">--</span><span class="token operator">-</span></pre><p>Blog posts should be written as markdown files with the following front matter:</p><pre class="prism language-javascript"><span class="token operator">--</span><span class="token operator">-</span>
|
|
title<span class="token punctuation">:</span> Blog Post Title
|
|
author<span class="token punctuation">:</span> Author Name
|
|
authorURL<span class="token punctuation">:</span> http<span class="token punctuation">:</span><span class="token operator">/</span><span class="token operator">/</span>twitter<span class="token punctuation">.</span>com<span class="token operator">/</span>author <span class="token operator"><</span><span class="token operator">!</span><span class="token operator">--</span> <span class="token punctuation">(</span>or some other link<span class="token punctuation">)</span> <span class="token operator">--</span><span class="token operator">></span>
|
|
authorFBID<span class="token punctuation">:</span> <span class="token number">21315325</span> <span class="token operator"><</span><span class="token operator">!</span><span class="token operator">--</span> id to <span class="token keyword">get</span> author's picture <span class="token operator">--</span><span class="token operator">></span>
|
|
<span class="token operator">--</span><span class="token operator">-</span></pre><p>In the blog post you should include a line <code><!--truncate--></code>. This will determine under which point text will be ignored when generating the preview of your blog post. Blog posts should have the file name format: <code>yyyy-mm-dd-your-file-name.md</code>.</p><h2><a class="anchor" name="using-docusaurus"></a>Using Docusaurus <a class="hash-link" href="#using-docusaurus">#</a></h2><h3><a class="anchor" name="run-the-server"></a>Run the Server <a class="hash-link" href="#run-the-server">#</a></h3><p>To run your website locally run the script:</p><pre class="prism language-javascript">npm run start</pre><p>or</p><pre class="prism language-javascript">yarn run start</pre><p>This will start a server hosting your website locally at <code>localhost:3000</code>. Any changes to configured files will be reflected by refreshing the page, i.e. the server does not need to be restarted to show changes. You may also specify a different port to start your server on by using a <code>--port</code> flag:</p><pre class="prism language-javascript">npm run start <span class="token operator">--</span> <span class="token operator">--</span>port <span class="token number">9000</span></pre><h3><a class="anchor" name="build-static-pages"></a>Build Static Pages <a class="hash-link" href="#build-static-pages">#</a></h3><p>To create a static build of your website, run the script:</p><pre class="prism language-javascript">npm run build</pre><p>or</p><pre class="prism language-javascript">yarn run build</pre><p>This will generate <code>.html</code> files from all of your docs and other pages included in <code>pages</code>. This allows you to check whether or not all your files are being generated correctly. The build folder is inside Docusaurus's directory inside <code>node_modules</code>.</p><h3><a class="anchor" name="publishing-your-website"></a>Publishing Your Website <a class="hash-link" href="#publishing-your-website">#</a></h3><p>Use CircleCI to publish your website whenever your project repo is updated. Configure your circle.yml file in your project repo to run commands to publish to GitHub Pages. An example is shown here:</p><pre class="prism language-yaml"><span class="token key atrule">machine</span><span class="token punctuation">:</span>
|
|
<span class="token key atrule">node</span><span class="token punctuation">:</span>
|
|
<span class="token key atrule">version</span><span class="token punctuation">:</span> 6.10.3
|
|
<span class="token key atrule">npm</span><span class="token punctuation">:</span>
|
|
<span class="token key atrule">version</span><span class="token punctuation">:</span> 3.10.10
|
|
|
|
<span class="token key atrule">test</span><span class="token punctuation">:</span>
|
|
<span class="token key atrule">override</span><span class="token punctuation">:</span>
|
|
<span class="token punctuation">-</span> <span class="token string">"true"</span>
|
|
|
|
<span class="token key atrule">deployment</span><span class="token punctuation">:</span>
|
|
<span class="token key atrule">website</span><span class="token punctuation">:</span>
|
|
<span class="token key atrule">branch</span><span class="token punctuation">:</span> master
|
|
<span class="token key atrule">commands</span><span class="token punctuation">:</span>
|
|
<span class="token punctuation">-</span> git config <span class="token punctuation">-</span><span class="token punctuation">-</span>global user.email "test<span class="token punctuation">-</span>site<span class="token punctuation">-</span>bot@users.noreply.github.com"
|
|
<span class="token punctuation">-</span> git config <span class="token punctuation">-</span><span class="token punctuation">-</span>global user.name "Website Deployment Script"
|
|
<span class="token punctuation">-</span> echo "machine github.com login test<span class="token punctuation">-</span>site<span class="token punctuation">-</span>bot password $GITHUB_TOKEN" <span class="token punctuation">></span> ~/.netrc
|
|
<span class="token punctuation">-</span> cd website && npm install && GIT_USER=test<span class="token punctuation">-</span>site<span class="token punctuation">-</span>bot npm run publish<span class="token punctuation">-</span>gh<span class="token punctuation">-</span>pages</pre><p>Note that in this case a GitHub user <code>test-site-bot</code> is created to use just for publishing. Make sure to give your Git user push permissions for your project and to set a GITHUB_TOKEN environment variable in Circle if you choose to publish this way.</p><p>If you wish to manually publish your website with the <code>publish-gh-pages</code> script, run the following example command with the appropriate variables for your project:</p><pre class="prism language-javascript">DEPLOY_USER<span class="token operator">=</span>deltice GIT_USER<span class="token operator">=</span>test<span class="token operator">-</span>site<span class="token operator">-</span>bot CIRCLE_PROJECT_USERNAME<span class="token operator">=</span>deltice CIRCLE_PROJECT_REPONAME<span class="token operator">=</span>test<span class="token operator">-</span>site CIRCLE_BRANCH<span class="token operator">=</span>master npm run publish<span class="token operator">-</span>gh<span class="token operator">-</span>pages</pre><h2><a class="anchor" name="more-information"></a>More Information <a class="hash-link" href="#more-information">#</a></h2><p>For details on how to set up translation support, read <a href="translation.md" target="_blank">here</a>.
|
|
For details on how to set up documentation search, read <a href="search.md" target="_blank">here</a>.</p></div></article></div><div class="docs-prevnext"></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></body></html> |