mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-03 11:22:30 +02:00
docs(v2): refactor docs for better outline and welcoming PRs (#1641)
* docs(v2): refactor docs for better outline and welcoming PRs * docs(v2): update docs
This commit is contained in:
Wei Gao
Yangshun Tay
parent
e5e085b33d
commit
95fde5f827
31 changed files with 435 additions and 253 deletions
|
|
@ -1,9 +0,0 @@
|
|||
---
|
||||
id: TODO
|
||||
title: TODO
|
||||
---
|
||||
|
||||
|
||||
#### References
|
||||
|
||||
- TODO
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
id: plugins
|
||||
id: advanced-plugins
|
||||
title: Plugins
|
||||
---
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ Docusaurus Plugins are very similar to [Gatsby Plugins](https://www.gatsbyjs.org
|
|||
|
||||
In most cases, plugins are there to fetch data and create routes. A plugin could take in components as part of its options and to act as the wrapper for the page.
|
||||
|
||||
## Lifecycle methods
|
||||
## Lifecycle Methods
|
||||
|
||||
<!-- TODO: explain lifecycle methods -->
|
||||
|
||||
|
|
@ -26,11 +26,13 @@ For example, the in docusaurus-plugin-content-docs:
|
|||
In contentLoaded, for each doc Markdown file, a route is created: /doc/installation, /doc/getting-started, etc.
|
||||
-->
|
||||
|
||||
## How to create plugins
|
||||
## How to Create Plugins
|
||||
|
||||
_This section is a work in progress._
|
||||
|
||||
<!-- TODO: explain creating plugins using an example -->
|
||||
|
||||
## Official plugins
|
||||
## Official Plugins
|
||||
|
||||
### `@docusaurus/plugin-content-blog`
|
||||
|
||||
|
|
@ -175,7 +177,7 @@ module.exports = {
|
|||
|
||||
### `@docusaurus/plugin-content-gtag`
|
||||
|
||||
<!-- TODO -->
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
### `@docusaurus/plugin-content-sitemap`
|
||||
|
||||
17
website/docs/advanced-presets.md
Normal file
17
website/docs/advanced-presets.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
id: advanced-presets
|
||||
title: Presets
|
||||
---
|
||||
|
||||
_This section is a work in progress._
|
||||
|
||||
<!--
|
||||
|
||||
Advanced guide on using and configuring presets
|
||||
|
||||
References
|
||||
---
|
||||
- [classic themes](/packages/docusaurus-preset-classic/src/index.js)
|
||||
- [babel docs on presets](https://babeljs.io/docs/en/presets)
|
||||
|
||||
-->
|
||||
21
website/docs/advanced-themes.md
Normal file
21
website/docs/advanced-themes.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
id: advanced-themes
|
||||
title: Themes
|
||||
---
|
||||
|
||||
_This section is a work in progress._
|
||||
|
||||
<!--
|
||||
|
||||
Advanced guide on:
|
||||
- customizing themes
|
||||
- implementing themes
|
||||
- swizzling components
|
||||
|
||||
References
|
||||
---
|
||||
- [classic themes](packages/docusaurus-theme-classic/src/index.js)
|
||||
- [using plugins doc](using-plugins.md)
|
||||
- [vuepress docs on themes](https://v1.vuepress.vuejs.org/theme/)
|
||||
|
||||
-->
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
---
|
||||
id: analytics
|
||||
title: Adding Analytics
|
||||
---
|
||||
|
||||
TODO: Talk about using Google analytics and Google gtag plugins and how to track using your own plugins.
|
||||
|
|
@ -119,7 +119,3 @@ module.exports = function(context, opts) {
|
|||
};
|
||||
};
|
||||
```
|
||||
|
||||
#### References
|
||||
|
||||
- https://v1.vuepress.vuejs.org/plugin/option-api.html
|
||||
18
website/docs/api-themes.md
Normal file
18
website/docs/api-themes.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
id: themes
|
||||
title: Themes
|
||||
---
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
<!--
|
||||
|
||||
API for themes
|
||||
|
||||
References
|
||||
---
|
||||
- [source code on loading themes](/packages/docusaurus/src/server/themes/index.ts)
|
||||
- [using plugins doc](using-plugins.md)
|
||||
- [vuepress docs on themes](https://v1.vuepress.vuejs.org/theme/)
|
||||
|
||||
-->
|
||||
|
|
@ -1,19 +0,0 @@
|
|||
---
|
||||
id: assets
|
||||
title: Using Assets
|
||||
---
|
||||
|
||||
TODO: Talk about how to include static assets within pages and docs.
|
||||
|
||||
### Images
|
||||
|
||||
TODO: How to include images in the website and reference them from pages and docs.
|
||||
|
||||
### Videos
|
||||
|
||||
TODO: Show how to easily embed YouTube videos.
|
||||
|
||||
#### References
|
||||
|
||||
- https://v1.vuepress.vuejs.org/guide/assets.html
|
||||
- https://www.gatsbyjs.org/docs/images-and-files/
|
||||
|
|
@ -3,8 +3,15 @@ id: blog
|
|||
title: Blog
|
||||
---
|
||||
|
||||
TODO: Explain how to add a blog and using the blog plugin.
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
#### References
|
||||
<!--
|
||||
|
||||
- TODO
|
||||
Adding a blog using the blog plugin.
|
||||
|
||||
References
|
||||
---
|
||||
- [source code](/packages/docusaurus-plugin-content-blog/src/index.js)
|
||||
- [v1 doc](https://docusaurus.io/docs/en/next/adding-blog)
|
||||
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -19,32 +19,45 @@ However, it can be helpful if you have a high-level understanding of how the con
|
|||
|
||||
The configurations can be categorized into:
|
||||
|
||||
- [Site meta](#site-meta)
|
||||
- [Deployment configurations](#deployment-configurations)
|
||||
- [Theme configurations, plugins, and presets](#theme-plugins-and-presets-configurations)
|
||||
- [Custom configurations](#custom-configurations)
|
||||
- [Site Metadata](#site-metadata)
|
||||
- [Deployment Configurations](#deployment-configurations)
|
||||
- [Theme Configurations, Plugins, and Presets](#theme-plugins-and-presets-configurations)
|
||||
- [Custom Configurations](#custom-configurations)
|
||||
|
||||
### Site meta
|
||||
### Site Metadata
|
||||
|
||||
Site meta contains the essential meta information such as titles and `favicon`.
|
||||
Site metadata contains the essential global metadata such as titles and `favicon`.
|
||||
|
||||
They are used by your site app in a number of places such as your site's title and headings, browser tab icon, and SEO.
|
||||
They are used by your website in a number of places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information and for search engine optimization (SEO).
|
||||
|
||||
### Deployment configurations
|
||||
### Deployment Configurations
|
||||
|
||||
Deployment configurations are used when you deploy your site with Docusaurus' deploy command. The related fields are:
|
||||
Deployment configurations are used when you deploy your site with Docusaurus' `deploy` command. The related fields are:
|
||||
|
||||
<!-- TODO: if we use monospace for the field names, they no longer look like a link -->
|
||||
|
||||
<!-- TODO: currently these fields are only used in GH Pages, what about other deployment services such as Netlify -->
|
||||
|
||||
You may also check the doc for [Deployment](deployment.md) for more information about the fields.
|
||||
You may also check the [Deployment docs](deployment.md) for more information about the fields.
|
||||
|
||||
### Theme, plugins, and presets configurations
|
||||
### Themes, Plugins, and Presets Configurations
|
||||
|
||||
<!-- TODO: More explanation from these docs, respectively -->
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
### Custom configurations
|
||||
<!--
|
||||
|
||||
TODO:
|
||||
- briefly introduce how to pass configurations to themes, plugins, and presets
|
||||
- throw in links to them respectively
|
||||
- make sure the logic flows nicely
|
||||
|
||||
[themes](using-themes.md)
|
||||
[plugins](using-plugins.md)
|
||||
[presets](presets.md)
|
||||
|
||||
-->
|
||||
|
||||
### Custom Configurations
|
||||
|
||||
Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`
|
||||
|
||||
|
|
@ -60,7 +73,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
## Accessing configuration from your site
|
||||
## Accessing Configuration From Your Site
|
||||
|
||||
Your configuration object will be made available to all the components of your site. And you may access them via context as `siteConfig`:
|
||||
|
||||
|
|
@ -73,6 +86,7 @@ const Layout = props => {
|
|||
const context = useDocusaurusContext();
|
||||
const {siteConfig = {}} = context;
|
||||
const {title, tagline, seo} = siteConfig;
|
||||
|
||||
return (
|
||||
<React.Fragment>
|
||||
<Head defaultTitle={`${defaultTitle} · ${tagline}`}>
|
||||
|
|
@ -84,3 +98,5 @@ const Layout = props => {
|
|||
);
|
||||
};
|
||||
```
|
||||
|
||||
> If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in `docusaurus.config.js`.
|
||||
|
|
|
|||
17
website/docs/contributing.md
Normal file
17
website/docs/contributing.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
id: contributing
|
||||
title: Contributing
|
||||
---
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
<!--
|
||||
|
||||
Basically mirror the `CONTRIBUTING.md` that we have.
|
||||
|
||||
References
|
||||
---
|
||||
- [CONTRIBUTING.md](/CONTRIBUTING.md)
|
||||
- [ReactJS contributing](https://reactjs.org/docs/how-to-contribute.html)
|
||||
|
||||
-->
|
||||
|
|
@ -9,7 +9,7 @@ In this section, we will learn about creating ad-hoc pages in Docusaurus using R
|
|||
|
||||
<!-- TODO: What will the user see if pages/ is empty? -->
|
||||
|
||||
In the `pages` directory, create a file called `hello.js` with the following contents:
|
||||
In the `src/pages` directory, create a file called `hello.js` with the following contents:
|
||||
|
||||
```jsx
|
||||
import React from 'react';
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ You can deploy your site to static site hosting services such as [GitHub Pages](
|
|||
|
||||
Docusaurus provides a easy way to publish to GitHub Pages.
|
||||
|
||||
### `docusaurus.config.js` settings
|
||||
### `docusaurus.config.js` Settings
|
||||
|
||||
First, modify your `docusaurus.config.js` and add the required params:
|
||||
|
||||
|
|
@ -65,7 +65,7 @@ There are two more optional parameters that are set as environment variables:
|
|||
Finally, to deploy your site to GitHub Pages, run:
|
||||
|
||||
```bash
|
||||
GIT_USER=[yourGitHubUserName] yarn run deploy
|
||||
GIT_USER=<GITHUB_USERNAME> yarn run deploy
|
||||
```
|
||||
|
||||
<!--
|
||||
|
|
@ -75,3 +75,7 @@ References:
|
|||
- https://www.gatsbyjs.org/docs/deploying-and-hosting/
|
||||
|
||||
-->
|
||||
|
||||
## Deployment with Netlify
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
|
|
|||
|
|
@ -3,14 +3,28 @@ id: design-principles
|
|||
title: Design Principles
|
||||
---
|
||||
|
||||
- Easy to learn but most things are still achievable by users, even if it takes them more code and more time to write. No abstractions beat bad abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk: Minimal API Surface Area
|
||||
- Users won't feel overwhelmed when looking at the directory of a D2 project. It just makes sense and is easy to build on top of. Gatsby projects have a ton of config files - `gatsby-config.js`, `gatsby-node.js`, `gatsby-client.js`, which can look intimidating to beginners.
|
||||
- We should not lock in our users to use our plugins or our CSS. Certain lower-level infra level stuff like React Loadable, React Router are fine, but not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology.
|
||||
- The separations of concerns between each layer of our stack should be clear - well-abstracted and modular.
|
||||
_This section is a work in progress._
|
||||
|
||||
TODO: Explain the principles that guide the development of Docusaurus.
|
||||
- Easy to learn but most things are still achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8)
|
||||
- Intuitive project structure - users will not feel overwhelmed when looking at the project directory of a Docusaurus project. It should look intuitive and easy to build on top of.
|
||||
- The separations of concerns between each layer of our stack (content/theming/styling) should be clear - well-abstracted and modular.
|
||||
- Sensible defaults - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
|
||||
- No vendor-lock in - Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain lower-level infra level stuff like React Loadable, React Router are fine, but not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology.
|
||||
|
||||
#### References
|
||||
## How Docusaurus Works
|
||||
|
||||
<!-- moved in from how Docusaurus works @yangshun -->
|
||||
|
||||
We believe that as devlopers, knowing how a library works is helpful in allowing us to become better at using it. Hence we're dedicating effort into explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
|
||||
|
||||
<!--
|
||||
|
||||
Explain the principles that guide the development of Docusaurus.
|
||||
|
||||
References
|
||||
---
|
||||
- https://www.gatsbyjs.org/docs/behind-the-scenes/
|
||||
- https://reactjs.org/docs/design-principles.html
|
||||
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
|
||||
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -3,8 +3,14 @@ id: docusaurus-core
|
|||
title: Docusaurus Core
|
||||
---
|
||||
|
||||
TODO: Mention Docusaurus core APIs here, such as `<Link />`, `<Head />`, `prefetch`, etc.
|
||||
_This section is a work in progress._
|
||||
|
||||
#### References
|
||||
<!--
|
||||
|
||||
- TODO
|
||||
Mention Docusaurus core APIs here, such as `<Link />`, `<Head />`, `prefetch`, etc.
|
||||
|
||||
References
|
||||
---
|
||||
- [source code](/packages/docusaurus/README.MD)
|
||||
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ title: docusaurus.config.js
|
|||
|
||||
`docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site.
|
||||
|
||||
## Required fields
|
||||
## Required Fields
|
||||
|
||||
### `title`
|
||||
|
||||
|
|
@ -95,13 +95,13 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
## Optional fields
|
||||
## Optional Fields
|
||||
|
||||
### `organizationName`
|
||||
|
||||
- Type: `string`
|
||||
|
||||
The GitHub user or organization that owns the repository.
|
||||
The GitHub user or organization that owns the repository. Used by the deployment command.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
|
|
@ -115,7 +115,7 @@ module.exports = {
|
|||
|
||||
- Type: `string`
|
||||
|
||||
The name of the GitHub repository.
|
||||
The name of the GitHub repository. Used by the deployment command.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
|
|
@ -214,7 +214,7 @@ Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom fi
|
|||
module.exports = {
|
||||
customFields: {
|
||||
admin: 'endi',
|
||||
superman: 'lol'
|
||||
superman: 'lol',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,12 +0,0 @@
|
|||
---
|
||||
id: TODO
|
||||
title: TODO
|
||||
---
|
||||
|
||||
We believe that as devlopers, knowing how a library works is helpful in allowing us to become better at using it. Hence we're dedicating effort into explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
|
||||
|
||||
TODO: Elaborate more.
|
||||
|
||||
#### References
|
||||
|
||||
- https://www.gatsbyjs.org/docs/behind-the-scenes/
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
id: how-to-contribute
|
||||
title: How to Contribute
|
||||
---
|
||||
|
||||
TODO: Basically mirror the `CONTRIBUTING.md` that we have.
|
||||
|
||||
#### References
|
||||
|
||||
- https://reactjs.org/docs/how-to-contribute.html
|
||||
|
|
@ -18,7 +18,7 @@ This is a **very early and incomplete alpha release** of Docusaurus 2. We are ma
|
|||
- :x: You need a full production-ready solution (<small>try [Docusaurus 1](https://docusaurus.io/) instead</small>)
|
||||
- :x: You prefer not to work with potential breaking changes and/or features not yet working properly as we improve it during alpha period
|
||||
|
||||
## The next Docusaurus is coming to town
|
||||
## The Next Docusaurus is Coming to Town
|
||||
|
||||
<img src="https://docusaurus.io/img/slash-introducing.svg" alt="Docusaurus"/>
|
||||
|
||||
|
|
@ -70,7 +70,7 @@ We've also studied other main static site generators and would like to share our
|
|||
|
||||
### Gatsby
|
||||
|
||||
Gatsby is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby tries to do many things well, while Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.
|
||||
Gatsby is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.
|
||||
|
||||
GraphQL is also pretty core to Gatsby, although you don't necessarily need GraphQL to build a Gatsby site. In most cases when building static websites, you won't need the flexibility that GraphQL provides.
|
||||
|
||||
|
|
@ -78,7 +78,7 @@ Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and i
|
|||
|
||||
### GitBook
|
||||
|
||||
Gitbook has very clean slate design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's doc site. As a result, many have to turn to other products. [You may read about Redux's switch to Docusaurus here](https://github.com/reduxjs/redux/issues/3161).
|
||||
Gitbook has very clean slate design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's doc site. As a result, many have to turn to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161).
|
||||
|
||||
Currently, Gitbook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,14 @@
|
|||
---
|
||||
id: writing-docs
|
||||
title: Writing Docs
|
||||
id: markdown-features
|
||||
title: Markdown Features
|
||||
---
|
||||
|
||||
<!--
|
||||
combining:
|
||||
- assets
|
||||
- markdown features
|
||||
-->
|
||||
|
||||
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.
|
||||
|
|
@ -11,7 +17,7 @@ In this section, we'd like to introduce you to the tools we've picked that we be
|
|||
|
||||
**Note:** All the following content assumes you are using `docusaurus-preset-classic`.
|
||||
|
||||
## 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.
|
||||
|
||||
|
|
@ -84,45 +90,7 @@ The headers are well-spaced so that the hierarchy is clear.
|
|||
|
||||
</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
|
||||
### 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.
|
||||
|
||||
|
|
@ -173,7 +141,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
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
|
||||
### 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.
|
||||
|
||||
|
|
@ -191,7 +159,7 @@ 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.
|
||||
|
||||
## Interactive Coding Editor
|
||||
### Interactive Coding Editor
|
||||
|
||||
(Powered by [React Live](https://github.com/FormidableLabs/react-live))
|
||||
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
---
|
||||
id: markdown
|
||||
title: Markdown Features
|
||||
---
|
||||
|
||||
|
||||
#### References
|
||||
|
||||
- TODO
|
||||
|
|
@ -1,18 +0,0 @@
|
|||
---
|
||||
id: presets
|
||||
title: Presets
|
||||
---
|
||||
|
||||
TODO: Explain what presets are.
|
||||
|
||||
## Using Presets
|
||||
|
||||
TODO: How to use presets and build your own ones to share with others.
|
||||
|
||||
## Official Presets
|
||||
|
||||
TODO: List them out and explain.
|
||||
|
||||
#### References
|
||||
|
||||
- https://babeljs.io/docs/en/presets
|
||||
48
website/docs/reaching-users.md
Normal file
48
website/docs/reaching-users.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
id: reaching-users
|
||||
title: Reaching Users
|
||||
---
|
||||
|
||||
## Search
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
<!--
|
||||
|
||||
References
|
||||
---
|
||||
- [Docusaurus v1 search](https://docusaurus.io/docs/en/search)
|
||||
- [Algolia documentation](https://www.algolia.com/doc/)
|
||||
-->
|
||||
|
||||
## SEO
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
<!--
|
||||
|
||||
Covers adding SEO to doc site
|
||||
- SEO for the whole site
|
||||
- SEO for each page
|
||||
|
||||
References
|
||||
---
|
||||
- [source code](/packages/docusaurus/src/client/exports/Head.js)
|
||||
- [The Essential Meta Tags for Social Media](https://css-tricks.com/essential-meta-tags-social-media/)
|
||||
|
||||
-->
|
||||
|
||||
## Analytics
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
<!--
|
||||
|
||||
Cover actual usage guidelines of adding analytics to sites.
|
||||
|
||||
References
|
||||
---
|
||||
- [source code](packages/docusaurus-plugin-google-analytics/src/index.js)
|
||||
- [plugins](plugins.md)
|
||||
|
||||
-->
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
id: search
|
||||
title: Adding Search
|
||||
---
|
||||
|
||||
TODO: Talk about how to add Algolia search and offline search via the search plugin (TBD).
|
||||
|
||||
#### References
|
||||
|
||||
- https://docusaurus.io/docs/en/search
|
||||
45
website/docs/sidebar.md
Normal file
45
website/docs/sidebar.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
id: sidebar
|
||||
title: 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.
|
||||
|
||||
## Subcategories
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
<!--
|
||||
|
||||
Note: We're implementing a new sidebar, this following links to the legacy sidebar as a reference
|
||||
[source code](packages/docusaurus-theme-classic/src/theme/DocLegacySidebar/index.js)
|
||||
|
||||
If you are interested in this section, please follow up on our progress
|
||||
|
||||
-->
|
||||
17
website/docs/static-assets.md
Normal file
17
website/docs/static-assets.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
id: static-assets
|
||||
title: Static Assets
|
||||
---
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
A "how-to" guide on including static assets within pages and docs.
|
||||
|
||||
<!--
|
||||
### Images
|
||||
### Videos
|
||||
|
||||
**References**
|
||||
- https://v1.vuepress.vuejs.org/guide/assets.html
|
||||
- https://www.gatsbyjs.org/docs/images-and-files/
|
||||
-->
|
||||
|
|
@ -3,17 +3,40 @@ id: styling-layout
|
|||
title: Styling and Layout
|
||||
---
|
||||
|
||||
## Styling your site with Infima
|
||||
## Traditional CSS
|
||||
|
||||
The classic template of Docusaurus uses [Infima](https://infima-dev.netlify.com/) as the underlying styling framework. Infima provides powerful and flexible layout and styling for content-centric websites. For more details of Infima, check out [Infima docs](https://infima-dev.netlify.com/).
|
||||
If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `src/css/custom.css`) and import them globally by passing it as an option into the preset.
|
||||
|
||||
When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `custom.css` file under your site's `/css` directory:
|
||||
```diff
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
+ theme: {
|
||||
+ customCss: require.resolve('./src/css/custom.css'),
|
||||
+ },
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Any CSS you write within that file will be available globally and can be referenced directly using string literals. This is the most traditional approach to writing CSS and is fine for small websites that do not have much customization.
|
||||
|
||||
## Styling your Site with Infima
|
||||
|
||||
`@docusaurus/preset-classic` uses [Infima CSS](https://infima-dev.netlify.com/) as the underlying styling framework. Infima provides powerful and flexible layout and styling suitable for content-centric websites. For more details of Infima, check out [Infima docs](https://infima-dev.netlify.com/).
|
||||
|
||||
When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `src/css/custom.css` file.
|
||||
|
||||
```css
|
||||
/**
|
||||
* /css/custom.css
|
||||
* You can override the default Infima variables here.
|
||||
* this is not a complete list of --ifm- variables
|
||||
* src/css/custom.css
|
||||
* You can override the default Infima variables here.
|
||||
* Note: this is not a complete list of --ifm- variables.
|
||||
*/
|
||||
:root {
|
||||
--ifm-color-primary: #25c2a0;
|
||||
|
|
@ -28,27 +51,69 @@ When you `init` your Docusaurus 2 project, the website will be generated with ba
|
|||
|
||||
<!-- TODO need more refinement here -->
|
||||
|
||||
## Styling your components
|
||||
## Styling Approaches
|
||||
|
||||
Your whole Docusaurus 2 site is a React app. Any styling that works with React will work with your site.
|
||||
A Docusaurus site is a single-page React application. You can style it the way you style React apps.
|
||||
|
||||
Component styling can be particularly useful when you wish to customize or swizzle a component. And there are a few frameworks we recommend that work particularly well with components.
|
||||
There are a few approaches/frameworks which will work, depending on your preferences and the type of website you are trying to build. Websites that are highly interactive and behave more like web apps will benefit from a more modern styling approaches that co-locate styles with the components. Component styling can also be particularly useful when you wish to customize or swizzle a component.
|
||||
|
||||
### With CSS Modules
|
||||
### Global Styles
|
||||
|
||||
To style your components using CSS Modules, name your stylesheets as `xxx.module.css`. The build step will pick up such files as CSS Module stylesheets. Then, you may get the generated class names from the module:
|
||||
This is the most traditional way of styling that most developers (including non-front end developers) would be familiar with.
|
||||
|
||||
```js
|
||||
import styles from './styles.module.css';
|
||||
Assuming you are using `@docusaurus/preset-classic` and `src/css/custom.css` was passed in to the preset config, styles inside that file would be available globally.
|
||||
|
||||
export default () => (
|
||||
<main className={styles.main}>
|
||||
<h1 className={styles.heading}>Hello!</h1>
|
||||
<article className={styles.docContent}>My doc</article>
|
||||
</main>
|
||||
);
|
||||
```css
|
||||
/* src/css/custom.css */
|
||||
.purple-text {
|
||||
color: rebeccapurple;
|
||||
}
|
||||
```
|
||||
|
||||
### With CSS-in-JS Frameworks
|
||||
```jsx
|
||||
function MyComponent() {
|
||||
return (
|
||||
<main>
|
||||
<h1 className="purple-text">Purple Heading!</h1>
|
||||
</main>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
This section is a work in progress. [Welcoming PRs](https://github.com/facebook/Docusaurus/pulls).
|
||||
### CSS Modules
|
||||
|
||||
To style your components using [CSS Modules](https://github.com/css-modules/css-modules), name your stylesheet files with the `.module.css` suffix (e.g. `welcome.module.css`). webpack will load such CSS files as CSS modules and you have to reference the class names from the imported CSS module (as opposed to using plain strings). This is similar to the convention used in [Create React App](https://facebook.github.io/create-react-app/docs/adding-a-css-modules-stylesheet).
|
||||
|
||||
```css
|
||||
/* styles.module.css */
|
||||
.main {
|
||||
padding: 12px;
|
||||
}
|
||||
|
||||
.heading {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.contents {
|
||||
color: #ccc;
|
||||
}
|
||||
```
|
||||
|
||||
```jsx
|
||||
import styles from './styles.module.css';
|
||||
|
||||
function MyComponent() {
|
||||
return (
|
||||
<main className={styles.main}>
|
||||
<h1 className={styles.heading}>Hello!</h1>
|
||||
<article className={styles.contents}>Lorem Ipsum</article>
|
||||
</main>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
The class names which will be processed by webpack into a globally unique class name during build.
|
||||
|
||||
### CSS-in-JS
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
|
|
|||
|
|
@ -1,22 +0,0 @@
|
|||
---
|
||||
id: themes
|
||||
title: Themes
|
||||
---
|
||||
|
||||
TODO: Explain what themes are.
|
||||
|
||||
## What are Themes for?
|
||||
|
||||
TODO
|
||||
|
||||
## How to Create Themes
|
||||
|
||||
TODO
|
||||
|
||||
## Official Themes
|
||||
|
||||
TODO
|
||||
|
||||
#### References
|
||||
|
||||
- https://v1.vuepress.vuejs.org/theme/
|
||||
|
|
@ -5,38 +5,46 @@ title: Using Plugins
|
|||
|
||||
<!-- A plugin is a package that exports a class which can be instantiated with configurable options (provided by the user) and its various lifecycle methods will be invoked by the Docusaurus runtime. -->
|
||||
|
||||
Plugins are the building blocks for Docusaurus 2 sites' features. Each plugin handles its own individual feature. Plugins may work together as [presets](./presets.md).
|
||||
Plugins are the building blocks which add features to a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work be bundled together and distributed via [presets](advanced-presets.md).
|
||||
|
||||
Docusaurus 2 provides a few essential plugins such as [sitemap](#docusaurus-plugin-content-sitemap), [analytics](#docusaurus-plugin-content-analytics). And you may write your own plugins for customized features.
|
||||
Docusaurus 2 provides a few essential plugins such as [Google Analytics](#docusaurus-plugin-content-analytics) and [Sitemap](#docusaurus-plugin-content-sitemap). You may also write your own plugins for customized features.
|
||||
|
||||
In this doc, we talk about how to use plugins with Docusaurus' official plugins. To learn about the design implementation and how to write your own plugins, check out [Advanced Guides: Plugins](./plugins.md). For API reference, check out [API Reference: Plugins]('./plugins-api.md).
|
||||
In this doc, we talk about how to use plugins with Docusaurus' official plugins. To learn about the design implementation and how to write your own plugins, check out [Advanced Guides: Plugins](advanced-plugins.md). For API reference, check out [API Reference: Plugins](api-plugins.md).
|
||||
|
||||
## Using plugins
|
||||
## Using Plugins
|
||||
|
||||
To use a plugin, add the plugin to the `plugins` field of your `docusaurus.config.js`.
|
||||
|
||||
For some plugins, providing just the plugin name is sufficient. For plugins that require options, specify the plugin in a `['plugin-name', options]` array.
|
||||
For the most basic usage of plugins, you can providing just the plugin name or the absolute path to the plugin. For plugins that require options, specify the plugin as an array where the first value is the plugin name/path and second value is an options object, e.g. `['plugin-name', { path: 'foo/bar' }]` array.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
// Basic usage.
|
||||
'@docusaurus/plugin-google-analytics',
|
||||
['@docusaurus/plugin-sitemap', opts.sitemap],
|
||||
|
||||
// With options object.
|
||||
[
|
||||
'@docusaurus/plugin-sitemap',
|
||||
{
|
||||
cacheTime: 600 * 1000,
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
## Passing options to Docusaurus plugins
|
||||
## Passing Options to Docusaurus Plugins Within Preset
|
||||
|
||||
Docusaurus' classic template is scaffolded with the classic preset, which in turn includes the following official plugins. You may read more about the configurations of these plugins in our [Advanced Guides: Plugins](./plugins.md).
|
||||
Docusaurus' classic template is scaffolded with the classic preset, which in turn includes the following official plugins. You may read more about the configurations of these plugins in our [Advanced Guides: Plugins](advanced-plugins.md).
|
||||
|
||||
- `@docusaurus/plugin-content-blog`
|
||||
- `@docusaurus/plugin-content-docs`
|
||||
- `@docusaurus/plugin-content-pages`
|
||||
- `@docusaurus/plugin-content-analytics`
|
||||
- `@docusaurus/plugin-content-gtag`
|
||||
- `@docusaurus/plugin-content-sitemap`
|
||||
- `@docusaurus/plugin-google-analytics`
|
||||
- `@docusaurus/plugin-google-gtag`
|
||||
- `@docusaurus/plugin-sitemap`
|
||||
|
||||
If you initialized your site using the classic template, you do not have to specify them individually in your `docusaurus.config.js`. To provide the neccesary fields to certain plugins, i.e. `trackingID` of `@docusaurus/plugin-content-analytics`, pass them in the preset field.
|
||||
|
||||
|
|
@ -47,15 +55,19 @@ module.exports = {
|
|||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
// Will be passed to @docusaurus/plugin-content-docs.
|
||||
docs: {
|
||||
sidebarPath: require.resolve('./sidebars.js'),
|
||||
},
|
||||
// Will be passed to @docusaurus/theme-classic.
|
||||
theme: {
|
||||
customCss: require.resolve('./src/css/custom.css'),
|
||||
},
|
||||
// Will be passed to @docusaurus/plugin-google-analytics.
|
||||
googleAnalytics: {
|
||||
trackingID: 'UA-000000-2',
|
||||
},
|
||||
...
|
||||
},
|
||||
],
|
||||
],
|
||||
|
|
|
|||
|
|
@ -3,8 +3,26 @@ id: using-themes
|
|||
title: Using Themes
|
||||
---
|
||||
|
||||
TODO: Give a high-level overview about themes and what they can be used for.
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
#### References
|
||||
<!--
|
||||
|
||||
- https://v1.vuepress.vuejs.org/theme/
|
||||
Outline
|
||||
---
|
||||
High-level overview about themes:
|
||||
- how they are used
|
||||
- how to shadow components and the power of it
|
||||
|
||||
Related pieces
|
||||
---
|
||||
- [Advanced Guide – Themes](advanced-themes.md)
|
||||
- [API - Themes](api-themes.md)
|
||||
|
||||
References
|
||||
---
|
||||
- [themes RFC](https://github.com/facebook/docusaurus/issues/1438)
|
||||
- [how classic template uses themes](/packages/docusaurus/templates/classic/docusaurus.config.js)
|
||||
- [using plugins doc](using-plugins.md)
|
||||
- [vuepress docs on themes](https://v1.vuepress.vuejs.org/theme/)
|
||||
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
/**
|
||||
/*
|
||||
* Copyright (c) 2017-present, Facebook, Inc.
|
||||
*
|
||||
* This source code is licensed under the MIT license found in the
|
||||
|
|
@ -7,30 +7,36 @@
|
|||
|
||||
module.exports = {
|
||||
docs: {
|
||||
'Getting Started': [
|
||||
Docusaurus: [
|
||||
'introduction',
|
||||
'installation',
|
||||
'creating-pages',
|
||||
'writing-docs',
|
||||
'deployment',
|
||||
/*'motivation', */ 'design-principles',
|
||||
'contributing',
|
||||
],
|
||||
'Getting Started': ['installation', 'configuration'],
|
||||
Guides: [
|
||||
'assets',
|
||||
'markdown',
|
||||
'creating-pages',
|
||||
'styling-layout',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Docs',
|
||||
items: ['markdown-features', 'sidebar', 'static-assets'],
|
||||
},
|
||||
'blog',
|
||||
'reaching-users',
|
||||
'using-plugins',
|
||||
'using-themes',
|
||||
'search',
|
||||
'analytics',
|
||||
'configuration',
|
||||
'deployment',
|
||||
],
|
||||
'Advanced Guides': [
|
||||
'advanced-plugins',
|
||||
'advanced-themes',
|
||||
'advanced-presets',
|
||||
],
|
||||
'Advanced Guides': ['blog', 'plugins', 'themes', 'presets'],
|
||||
'API Reference': [
|
||||
'cli',
|
||||
'docusaurus-core',
|
||||
'docusaurus.config.js',
|
||||
'plugins-api',
|
||||
],
|
||||
Contributing: ['how-to-contribute', 'motivation', 'design-principles'],
|
||||
},
|
||||
};
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue