3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-04-30 02:37:59 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs(v2): revise "writing docs" (#1561)

Browse source 
* Revise doc on writing docs

* More work on docs doc

* misc(v2): tweak docs

* misc(v2): fix typo
This commit is contained in:
Wei Gao 2019-06-06 04:45:40 +08:00 • committed by Yangshun Tay
parent 5962cda8b7
commit 22ed720faa
5 changed files with 352 additions and 171 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
website/components/BrowserWindow/index.js Normal file
View file

@ -0,0 +1,39 @@
/**
* Copyright (c) 2017-present, Facebook, Inc.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import React from 'react';
import classnames from 'classnames';
import styles from './styles.module.css';
function BrowserWindow({children, minHeight, url}) {
return (
<div className={styles.container} style={{minHeight}}>
<div className={styles.row}>
<div className={classnames(styles.column, styles.left)}>
<span className={styles.dot} style={{background: '#ED594A'}} />
<span className={styles.dot} style={{background: '#FDD800'}} />
<span className={styles.dot} style={{background: '#5AC05A'}} />
</div>
<div className={classnames(styles.column, styles.middle)}>
<input disabled={true} type="text" value={url} readOnly />
</div>
<div className={classnames(styles.column, styles.right)}>
<div style={{float: 'right'}}>
<span className={styles.bar} />
<span className={styles.bar} />
<span className={styles.bar} />
</div>
</div>
</div>
<div className={styles.content}>{children}</div>
</div>
);
}
export default BrowserWindow;

67
website/components/BrowserWindow/styles.module.css Normal file
View file

@ -0,0 +1,67 @@
.container {
border: 3px solid var(--ifm-color-emphasis-alpha-10);
border-top-left-radius: 4px;
border-top-right-radius: 4px;
}
.row {
display: flex;
background: var(--ifm-color-emphasis-alpha-10);
padding: 0.5rem;
}
.row:after {
content: '';
display: table;
clear: both;
}
.column {
float: left;
}
.left {
width: 15%;
}
.right {
align-self: center;
width: 10%;
}
.middle {
width: 75%;
}
.dot {
margin-right: 6px;
margin-top: 4px;
height: 12px;
width: 12px;
background-color: #bbb;
border-radius: 50%;
display: inline-block;
}
input[type='text'] {
width: 100%;
border-radius: 12.5px;
border: none;
background-color: white;
margin-top: -8px;
height: 25px;
color: #666;
padding: 5px 15px;
}
.bar {
width: 17px;
height: 3px;
background-color: #aaa;
margin: 3px 0;
display: block;
}
.content {
padding: 1rem;
}

245
website/docs/writing-docs.mdx Normal file
View file

@ -0,0 +1,245 @@
---
id: writing-docs
title: Writing Docs
---
Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as easily as possible.
Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example.
**Note:** All the following content assumes you are using `docusaurus-plugin-content-docs` or `docusaurus-preset-classic` (which contains `docusaurus-plugin-content-docs`).
## Using Markdown
Markdown is a syntax that enables you to write formatted content in an easy-to-use syntax. The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown. More on that later.
Create a markdown file, `greeting.md`, and place it under the `docs` directory of your website's root.
```bash
website # root directory of your site
├── docs
│   └── greeting.md
├── pages
├── docusaurus.config.js
├── ...
```
<!-- TODO: talk about where to put the docs, resolving docs outside of website directory, etc. -->
In the beginning of this file, specify `id` the `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.
```markdown
---
id: greeting
title: Hello
---
## Hello from Docusaurus
Are you ready to create the documentation site for your open source project?
### Headers
will show up on the table of contents on the upper right
So that your users will know what this page is all about without scrolling down or even without reading too much.
### Only h2 and h3 will be in the toc
The headers are well-spaced so that the hierarchy is clear.
- lists will help you
- present the key points
- that you want your users to remember
- and you may nest them
- multiple times
```
This will render in the browser as follows:
import BrowserWindow from '../components/BrowserWindow';
<BrowserWindow url="http://localhost:3000">
<h2>Hello from Docusaurus</h2>
Are you ready to create the documentation site for your open source project?
<h3>Headers</h3>
will show up on the table of contents on the upper right
So that your users will know what this page is all about without scrolling down or even without reading too much.
<h3>Only h2 and h3 will be in the toc</h3>
The headers are well-spaced so that the hierarchy is clear.
- lists will help you
- present the key points
- that you want your users to quickly remember
- and you may nest them - multiple layers
</BrowserWindow>
## Sidebar
To generate a sidebar to your Docusaurus site, you need to define a file that exports a JS module and pass that into `docusaurus-plugin-docs` directly or via the `docusaurus-preset-classic`. If you are using the classic preset, you can find the `sidebars.js` under the root directory already created for you, so you may edit it directly for customization.
<!-- TODO: change classic template to use `sidebars.js` from json -->
```bash
website # root directory of your site
├── docs
│   └── greeting.md
├── docusaurus.config.js
├── sidebars.js
.
```
To add a doc to the sidebar, add the `id` specified in the frontmatter of the doc into its category.
```diff
module.exports = {
docs: {
+ "Getting started": ["greeting"],
"Docusaurus": ["doc1"],
"First Category": ["doc2"],
"Second Category": ["doc3"],
}
};
```
The `docs` key in the file is just the name of that particular sidebar hierarchy, and can be renamed to something else. You can have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.
<!-- TODO: Mention subcategories -->
<!--
TODO: Talk more about using the official docs plugin and how to configure the sidebar. Mention about incorporating assets and a preview of the cool Markdown features available, but don't list all the Markdown features here.
References:
- https://docusaurus.io/docs/en/navigation
-->
## Embedding React Components
Docusaurus has built-in support for [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown files and render them as React components.
**Note:** While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax. Let's rename the previous file to `greeting.mdx`
Try this block here:
```jsx
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
```
Notice how it renders both the markup from your React component and the Markdown syntax:
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
<BrowserWindow minHeight={240} url="http://localhost:3000">
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
</BrowserWindow>
<br />
You can also import your own components defined in other files or third-party components installed via npm! Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
## Syntax Highlighting
Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX.
```jsx
console.log('Every repo must come with a mascot.');
```
<!-- TODO: We need to allow users to pick syntax highlighting themes (maybe other than swizzling) -->
Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer). Just in case you need it, [here](https://prismjs.com/#supported-languages) is a list of supported languages and their corresponding meta strings.
```jsx
console.log('Every repo must come with a mascot.');
```
**Work in Progress** Currently the Prism theme we use is [Night Owl](https://github.com/FormidableLabs/prism-react-renderer/blob/master/themes/nightOwl.js). We will support customized theme in a future version.
## Live Editor
You can create live code editors by creating a code block with `live` attached to the language meta string.
```jsx live
function Clock(props) {
const [date, setDate] = useState(new Date());
useEffect(() => {
var timerID = setInterval(() => tick(), 1000);
return function cleanup() {
clearInterval(timerID);
};
});
function tick() {
setDate(new Date());
}
return (
<div>
<h2>It is {date.toLocaleTimeString()}.</h2>
</div>
);
}
```
It will render an interactive editor. Changes to the code will reflect on the result panel live.
```jsx live
function Clock(props) {
const [date, setDate] = useState(new Date());
useEffect(() => {
var timerID = setInterval(() => tick(), 1000);
return function cleanup() {
clearInterval(timerID);
};
});
function tick() {
setDate(new Date());
}
return (
<div>
<h2>It is {date.toLocaleTimeString()}.</h2>
</div>
);
}
```
**Work in Progress** The React Live component is rather big. We want to make it an opt-in by moving it to a plugin.

170
website/docs/writing-documentation.md
View file

@ -1,170 +0,0 @@
---
id: writing-documentation
title: Writing Documentation
---
Next, let's touch on the powerful feature in Docusaurus - documentation.
## Using Markdown
Create a new file within the `docs` directory called `hello.md` with the following contents:
```markdown
---
title: Hello
---
I can write content using [GitHub-flavored Markdown syntax](https://github.github.com/gfm/).
## Markdown Syntax
**Bold** _italic_ `code` [Links](#url)
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.
- Hey
- Ho
- Let's Go
```
Docusaurus supports Markdown syntax using [Remark](https://github.com/remarkjs/remark) for Markdown parser and is extensible via plugins.
## Embedding React Components
Did you know that you can now write React components within your Markdown files? This is possible because of [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown documents.
Now we'll add a third-party chart component into the Markdown file created above. Before that, kill your web server (<kbd>Cmd</kbd> + <kbd>C</kbd> or <kbd>Ctrl</kbd> + <kbd>C</kbd>) if it's running and install `react-trend` in your website directory.
```bash
npm install react-trend
```
Start the development server again and go to http://localhost:3000/docs/hello, you will see a new page created from the Markdown file.
Edit `docs/hello.md` and append the following:
```jsx
import Trend from 'react-trend';
_Here's a bar chart!_
<Trend
smooth
autoDraw
autoDrawDuration={3000}
autoDrawEasing="ease-out"
data={[0, 2, 5, 9, 5, 10, 3, 5, 0, 0, 1, 8, 2, 9, 0]}
gradient={['#00c6ff', '#F0F', '#FF0']}
radius={10}
strokeWidth={2}
strokeLinecap={'butt'}
/>
```
Save the file and notice that the site is hot-reloaded with the edited content.
We just imported a React component and embedded it within our markdown 😉!
<!-- TODO: Briefly explain MDX more -->
## Sidebar
Next, let's add this page to the sidebar.
Edit the `sidebars.json` file and add the `hello` document.
```diff
{
"docs": {
+ "Getting started": ["hello"],
"Docusaurus": ["doc1"],
"First Category": ["doc2"],
"Second Category": ["doc3"]
},
"docs-other": {
"First Category": ["doc4", "doc5"]
}
}
```
You can see that there is a sidebar now on http://localhost:3000/docs/hello.
<!-- TODO: Briefly sidebar more -->
<!--
TODO: Talk more about using the official docs plugin and how to configure the sidebar. Mention about incorporating assets and a preview of the cool Markdown features available, but don't list all the Markdown features here.
References:
- https://docusaurus.io/docs/en/navigation
-->
## Syntax highlighting
If you're writing technical documentation you may want a way to delineate blocks of
code, sometimes known as a *code fence*. The result is also known as a *code block*.
The simplest way to show code is to wrap it between two lines consisting of 3 backticks in a row.
Example:
```jsx
console.log("Hello world");
```
And the result would be:
```jsx
console.log("Hello world");
```
## Live Editor
You can also create live code editors with a code block `live` meta string.
Example:
```jsx live
function Clock(props) {
const [date, setDate] = useState(new Date());
useEffect(() => {
var timerID = setInterval(() => tick(), 1000);
return function cleanup() {
clearInterval(timerID);
};
});
function tick() {
setDate(new Date());
}
return (
<div>
<h2>It is {date.toLocaleTimeString()}.</h2>
</div>
);
}
```
And the result would be:
```jsx live
function Clock(props) {
const [date, setDate] = useState(new Date());
useEffect(() => {
var timerID = setInterval(() => tick(), 1000);
return function cleanup() {
clearInterval(timerID);
};
});
function tick() {
setDate(new Date());
}
return (
<div>
<h2>It is {date.toLocaleTimeString()}.</h2>
</div>
);
}
```

2
website/sidebars.js
View file

@ -11,7 +11,7 @@ module.exports = {
'introduction',
'installation',
'creating-pages',
'writing-documentation',
'writing-docs',
'deployment',
],
Guides: [