mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-04 03:42:34 +02:00
docs(v2): proofread docs for alpha.20 (#1658)
* docs(v2): proofread docs for alpha.20 * docs(v2): update creating pages doc * docs(v2): further updates to creating pages doc * chore(v2): update CHANGELOG
This commit is contained in:
Yangshun Tay
GitHub
parent
9266dda072
commit
c021367a18
19 changed files with 185 additions and 102 deletions
0
packages/docusaurus-init/bin/index.js
Normal file → Executable file
0
packages/docusaurus-init/bin/index.js
Normal file → Executable file
|
|
@ -4,6 +4,10 @@
|
|||
|
||||
- Added Google analytics and Google gtag plugins.
|
||||
- Moved source components to `/src`. Please create a `website/src` directory and move your `/pages` and `/theme` code into it. This is to make it easier to integrate your website with external build/static analysis tooling (you can now just pass in `src/**/*.js` as the path to process).
|
||||
- Added more documentation thanks to @wgao19.
|
||||
- Deprecate the current docs plugin. The docs plugin as of 2.0.0-alpha.19 is heavily based on V1 specifications and we intend to create a better one that fixes some of the inconsistencies in V1. If you have swizzled any doc components, you will have to update their names. You are highly encourages to not swizzle the legacy doc components until we have completed the new docs plugin.
|
||||
- Render the NotFound page if an unspecified route was accessed.
|
||||
- Clicking on the logo in the mobile sliding navigation will now bring you to the homepage.
|
||||
|
||||
## 2.0.0-alpha.19
|
||||
|
||||
|
|
|
|||
|
|
@ -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,13 +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`
|
||||
|
||||
|
|
@ -164,22 +164,22 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
### `@docusaurus/plugin-content-analytics`
|
||||
### `@docusaurus/plugin-google-analytics`
|
||||
|
||||
The classic template ships with this plugin for Google Analytics. To use this analytics, specify the plugin in the `plugins` field, and provide your Google Analytics configuration in [theme config](./using-themes.md).
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
plugins: ['@docusaurus/plugin-content-analytics'],
|
||||
plugins: ['@docusaurus/plugin-google-analytics'],
|
||||
};
|
||||
```
|
||||
|
||||
### `@docusaurus/plugin-content-gtag`
|
||||
### `@docusaurus/plugin-google-gtag`
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
### `@docusaurus/plugin-content-sitemap`
|
||||
### `@docusaurus/plugin-sitemap`
|
||||
|
||||
The classic template ships with this plugin.
|
||||
|
||||
|
|
@ -187,7 +187,7 @@ The classic template ships with this plugin.
|
|||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
'@docusaurus/plugin-content-sitemap',
|
||||
'@docusaurus/plugin-sitemap',
|
||||
{
|
||||
cacheTime: 600 * 1000, // 600 sec - cache purge period
|
||||
changefreq: 'weekly',
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ title: Configuration
|
|||
|
||||
Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We will guard the fields of this file, and facilitate making this data object accessible across your site.
|
||||
|
||||
Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on docs while having certain fields easy to customize.
|
||||
Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to easily customize fields.
|
||||
|
||||
For reference to each of the configurable fields, you may refer to the API reference of [docusaurus.config.js](docusaurus.config.js.md).
|
||||
|
||||
|
|
@ -24,13 +24,13 @@ The configurations can be categorized into:
|
|||
- [Theme Configurations, Plugins, and Presets](#theme-plugins-and-presets-configurations)
|
||||
- [Custom Configurations](#custom-configurations)
|
||||
|
||||
### Site Metadata
|
||||
### Site metadata
|
||||
|
||||
Site metadata contains the essential global metadata such as titles and `favicon`.
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -38,9 +38,9 @@ Deployment configurations are used when you deploy your site with Docusaurus' `d
|
|||
|
||||
<!-- TODO: currently these fields are only used in GH Pages, what about other deployment services such as Netlify -->
|
||||
|
||||
You may also check the [Deployment docs](deployment.md) for more information about the fields.
|
||||
You may also check the [deployment docs](deployment.md) for more information about the fields.
|
||||
|
||||
### Themes, Plugins, and Presets Configurations
|
||||
### Themes, Plugins, and Presets configurations
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ TODO:
|
|||
|
||||
-->
|
||||
|
||||
### Custom Configurations
|
||||
### Custom configurations
|
||||
|
||||
Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`
|
||||
|
||||
|
|
@ -73,7 +73,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
## Accessing Configuration From Your Site
|
||||
## Accessing configuration from components
|
||||
|
||||
Your configuration object will be made available to all the components of your site. And you may access them via context as `siteConfig`:
|
||||
|
||||
|
|
|
|||
|
|
@ -3,13 +3,13 @@ id: creating-pages
|
|||
title: Creating Pages
|
||||
---
|
||||
|
||||
In this section, we will learn about creating ad-hoc pages in Docusaurus using React. This is most useful for creating one-off standalone pages.
|
||||
In this section, we will learn about creating ad-hoc pages in Docusaurus using React. This is most useful for creating one-off standalone pages like a showcase page, playground page or support page.
|
||||
|
||||
### Creating Pages
|
||||
## Adding a new page
|
||||
|
||||
<!-- TODO: What will the user see if pages/ is empty? -->
|
||||
|
||||
In the `src/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';
|
||||
|
|
@ -39,20 +39,41 @@ export default Hello;
|
|||
|
||||
Once you save the file, the development server will automatically reload the changes. Now open http://localhost:3000/hello, you will see the new page you just created.
|
||||
|
||||
Any file you create under `pages` directory will be automatically converted to a page, converting the directory hierarchy into paths. For example:
|
||||
Each page doesn't come with any styling. You will need to import the `Layout` component from `@theme/Layout` and wrap your contents within that component if you want the navbar and/or footer to appear.
|
||||
|
||||
- `pages/index.js` → `<baseUrl>/`
|
||||
- `pages/test.js` → `<baseUrl>/test`
|
||||
- `pages/foo/test.js` → `<baseUrl>/foo/test`
|
||||
- `pages/foo/index.js` → `<baseUrl>/foo`
|
||||
## Routing
|
||||
|
||||
### Using React
|
||||
If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example:
|
||||
|
||||
React is used as the UI library to create pages. You can leverage on the expressibility of React to build rich web content.
|
||||
- `/src/pages/index.js` → `<baseUrl>/`
|
||||
- `/src/pages/test.js` → `<baseUrl>/test`
|
||||
- `/src/pages/foo/test.js` → `<baseUrl>/foo/test`
|
||||
- `/src/pages/foo/index.js` → `<baseUrl>/foo`
|
||||
|
||||
In this component-based development era, it is encouraged to co-locate your styling, markup and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a "Support" page, you could do one of the following:
|
||||
|
||||
- Add a `/src/pages/support.js` file
|
||||
- Create a `/src/pages/support/` directory and a `/src/pages/support/index.js` file.
|
||||
|
||||
The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For e.g. a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. **Note:** this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (`support/index.js`).
|
||||
|
||||
```sh
|
||||
my-website
|
||||
├── src
|
||||
│ └── pages
|
||||
│ ├── styles.module.css
|
||||
│ ├── index.js
|
||||
│ └── support
|
||||
│ ├── index.js
|
||||
│ └── styles.module.css
|
||||
.
|
||||
```
|
||||
|
||||
## Using React
|
||||
|
||||
React is used as the UI library to create pages. Every page component should export a React component and you can leverage on the expressibility of React to build rich and interactive content.
|
||||
|
||||
<!--
|
||||
TODO:
|
||||
- Explain that each page needs to be wrapped with `@theme/Layout`.
|
||||
- That v2 is different from v1, users can write interactive components with lifecycles.
|
||||
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -11,13 +11,13 @@ npm build
|
|||
|
||||
Once it finishes, you should see the production build under the `build/` directory.
|
||||
|
||||
You can deploy your site to static site hosting services such as [GitHub Pages](https://pages.github.com/), [Render](https://render.com/static-sites), and [Netlify](https://www.netlify.com/). Docusaurus sites are server rendered so they work without JavaScript too!
|
||||
You can deploy your site to static site hosting services such as [GitHub Pages](https://pages.github.com/), [Now](https://zeit.co/now), [Netlify](https://www.netlify.com/), and [Render](https://render.com/static-sites). Docusaurus sites are statically rendered so they work without JavaScript too!
|
||||
|
||||
## Deploying to 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:
|
||||
|
||||
|
|
@ -45,7 +45,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
### Environment Settings
|
||||
### Environment settings
|
||||
|
||||
Specify the Git user as an environment variable.
|
||||
|
||||
|
|
@ -76,6 +76,14 @@ References:
|
|||
|
||||
-->
|
||||
|
||||
## Deploying to Now
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
## Deploying to Netlify
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
## Deploying to Render
|
||||
|
||||
Render offers [free static site hosting](https://render.com/docs/static-sites) with fully managed SSL, custom domains, a global CDN and continuous auto deploys from your Git repo. Deploy your app in just a few minutes by following these steps.
|
||||
|
|
@ -84,16 +92,12 @@ Render offers [free static site hosting](https://render.com/docs/static-sites) w
|
|||
|
||||
2. Select the branch to deploy. The default is `master`.
|
||||
|
||||
2. Enter the following values during creation.
|
||||
3. Enter the following values during creation.
|
||||
|
||||
| Field | Value |
|
||||
| ------- | ----- |
|
||||
| **Environment** | `Static Site` |
|
||||
| **Build Command** | `yarn build` |
|
||||
| **Publish Directory** | `build` |
|
||||
| Field | Value |
|
||||
| --------------------- | ------------- |
|
||||
| **Environment** | `Static Site` |
|
||||
| **Build Command** | `yarn build` |
|
||||
| **Publish Directory** | `build` |
|
||||
|
||||
That's it! Your app will be live on your Render URL as soon as the build finishes.
|
||||
|
||||
## Deployment with Netlify
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
|
|
|||
|
|
@ -5,17 +5,19 @@ title: Design Principles
|
|||
|
||||
_This section is a work in progress._
|
||||
|
||||
- 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.
|
||||
- **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be 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** - Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with.
|
||||
- **Layered architecture** - 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.
|
||||
|
||||
## How Docusaurus Works
|
||||
## 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.
|
||||
We believe that as developers, 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.
|
||||
|
||||
_This section is a work in progress._
|
||||
|
||||
<!--
|
||||
|
||||
|
|
|
|||
|
|
@ -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,7 +95,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
## Optional Fields
|
||||
## Optional fields
|
||||
|
||||
### `organizationName`
|
||||
|
||||
|
|
|
|||
|
|
@ -3,39 +3,68 @@ id: installation
|
|||
title: Installation
|
||||
---
|
||||
|
||||
The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a Docusaurus site skeleton. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.
|
||||
Docusaurus is essentially a set of npm [packages](https://github.com/facebook/docusaurus/tree/master/packages) that can be installed over npm.
|
||||
|
||||
## Requirements
|
||||
|
||||
- [Node.js](https://nodejs.org/en/download/) version 8 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed
|
||||
- [Yarn](https://yarnpkg.com/en/) version >= 1.5 (which can be checked by running `yarn version`). Yarn is a performant package manager for JavaScript and replaces the `npm` client. It is not strictly necessary but highly encouraged.
|
||||
|
||||
## Scaffold project website
|
||||
|
||||
The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.
|
||||
|
||||
```bash
|
||||
npx @docusaurus/init@next init [name] [template]
|
||||
```
|
||||
|
||||
If you do not specify `name` or `template`, it will prompt you for the missing inputs. We recommend the `classic` template so that you can get started quickly. The `classic` template comes with standard documentation, blog and custom pages features.
|
||||
If you do not specify `name` or `template`, it will prompt you for them. We recommend the `classic` template so that you can get started quickly and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.
|
||||
|
||||
## Project Structure
|
||||
## Project structure
|
||||
|
||||
Assuming you chose the classic template and named your site `my-website`, you will see the following files generated under a new directory `my-website/`:
|
||||
|
||||
```sh
|
||||
my-website
|
||||
├── blog
|
||||
│ ├── 2019-05-28-hola.md
|
||||
│ ├── 2019-05-29-hello-world.md
|
||||
│ └── 2020-05-30-welcome.md
|
||||
├── docs
|
||||
│ ├── doc1.md
|
||||
│ ├── doc2.md
|
||||
│ ├── doc3.md
|
||||
│ └── mdx.md
|
||||
├── blog
|
||||
│ ├── 2019-05-29-hello-world.md
|
||||
│ └── 2020-05-30-welcome.md
|
||||
├── package.json
|
||||
├── pages
|
||||
│ └── index.js
|
||||
├── sidebars.json
|
||||
├── docusaurus.config.js
|
||||
├── src
|
||||
│ ├── css
|
||||
│ │ └── custom.css
|
||||
│ └── pages
|
||||
│ ├── styles.module.css
|
||||
│ └── index.js
|
||||
├── static
|
||||
│ └── img
|
||||
├── docusaurus.config.js
|
||||
├── package.json
|
||||
├── README.md
|
||||
├── sidebars.js
|
||||
└── yarn.lock
|
||||
```
|
||||
|
||||
## Running the Development Server
|
||||
### Project structure rundown
|
||||
|
||||
- `/blog/` - Contains the blog markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md).
|
||||
- `/docs/` - Contains the markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](markdown-features).
|
||||
- `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
|
||||
- `/src/pages` - Any files within this directory will be converted into a website page. More details can be found in the [pages guide](creating-pages.md).
|
||||
- `/static/` - Static directory. Any contents inside here will be copied into the root of the final `build` directory.
|
||||
- `/docusaurus.config.js` - A config file containing the site configuration. This is the equivalent of `siteConfig.js` in Docusaurus 1.
|
||||
- `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them.
|
||||
- `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar.
|
||||
|
||||
## Running the development server
|
||||
|
||||
To preview your changes as you edit the files, you can run a local development server that will serve your website and it will reflect the latest chages
|
||||
|
||||
```bash
|
||||
cd my-website
|
||||
|
|
@ -45,3 +74,17 @@ npm start
|
|||
By default, a browser window will open at http://localhost:3000.
|
||||
|
||||
Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available.
|
||||
|
||||
## Build
|
||||
|
||||
Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website:
|
||||
|
||||
```bash
|
||||
npm build
|
||||
```
|
||||
|
||||
and contents will be generated within the `/build` directory, which can be copied to any static file hosting service like [GitHub pages](https://pages.github.com/), [Now](https://zeit.co/now) or [Netlify](https://www.netlify.com/). Check out the docs on [deployment](deployment.md) for more details.
|
||||
|
||||
## Problems?
|
||||
|
||||
Ask for help on [StackOverflow](https://stackoverflow.com/questions/tagged/docusaurus), on our [GitHub repository](https://github.com/facebook/docusaurus) or [Twitter](https://twitter.com/docusaurus).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
## A better Docusaurus is coming to town
|
||||
|
||||
<img src="https://docusaurus.io/img/slash-introducing.svg" alt="Docusaurus"/>
|
||||
|
||||
|
|
@ -62,7 +62,7 @@ Docusaurus 2 is born to be compassionately accessible to all your users, and lig
|
|||
- ⚡️ **Lightning fast** Docusaurus 2 follows [The PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast
|
||||
- 🦖 **Accessible** Attention to accessibility, making your site equally accessible to all users
|
||||
|
||||
## Comparison with other Tools
|
||||
## Comparison with other tools
|
||||
|
||||
Across all static site generators, Docusaurus has a unique focus on doc sites and has out-of-the-box structure you need.
|
||||
|
||||
|
|
@ -92,13 +92,15 @@ In comparison with statically generated HTML and interactivity based on `<script
|
|||
|
||||
VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you wanted a Vue-based solution, VuePress would be a decent choice.
|
||||
|
||||
## Staying Informed
|
||||
<!-- TODO: Add a Next.js comparison -->
|
||||
|
||||
## Staying informed
|
||||
|
||||
- [GitHub](https://github.com/facebook/docusaurus)
|
||||
- [Twitter](https://twitter.com/docusaurus)
|
||||
- [Blog](/blog)
|
||||
|
||||
## Something Missing?
|
||||
## Something missing?
|
||||
|
||||
If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please [file an issue](https://github.com/facebook/docusaurus) for us, or send a tweet mentioning the [@docusaurus](https://twitter.com/docusaurus) Twitter account.
|
||||
|
||||
|
|
|
|||
|
|
@ -21,20 +21,21 @@ In this section, we'd like to introduce you to the tools we've picked that we be
|
|||
|
||||
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.
|
||||
Create a markdown file, `greeting.md`, and place it under the `docs` directory.
|
||||
|
||||
```bash
|
||||
website # root directory of your site
|
||||
├── docs
|
||||
│ └── greeting.md
|
||||
├── pages
|
||||
├── src
|
||||
│ └── 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.
|
||||
In the top of the file, specify `id` the `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
|
@ -90,7 +91,7 @@ The headers are well-spaced so that the hierarchy is clear.
|
|||
|
||||
</BrowserWindow>
|
||||
|
||||
### 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.
|
||||
|
||||
|
|
@ -141,7 +142,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.
|
||||
|
||||
|
|
@ -159,7 +160,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 code editor
|
||||
|
||||
(Powered by [React Live](https://github.com/FormidableLabs/react-live))
|
||||
|
||||
|
|
@ -231,4 +232,4 @@ function Clock(props) {
|
|||
}
|
||||
```
|
||||
|
||||
**Note** The React Live component is rather big in bundle size. It is an opt-in.
|
||||
**Note:** The React Live component is rather big in bundle size. It is an opt-in.
|
||||
|
|
|
|||
|
|
@ -5,17 +5,18 @@ title: Plugins
|
|||
|
||||
Plugins are one of the best ways to add functionality to our Docusaurus. Plugins allow third-party developers to extend or modify the default functionality that Docusaurus provides.
|
||||
|
||||
## Installing a Plugin
|
||||
## Installing a plugin
|
||||
|
||||
A plugin is usually a dependency, so you install them like other packages in node using NPM.
|
||||
A plugin is an npm package, so you install them like other npm packages using npm.
|
||||
|
||||
```bash
|
||||
yarn add docusaurus-plugin-name
|
||||
```
|
||||
|
||||
Then you add it in your site's `docusaurus.config.js` plugin arrays:
|
||||
Then you add it in your site's `docusaurus.config.js`'s `plugins` option:
|
||||
|
||||
```jsx
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
'@docusaurus/plugin-content-pages',
|
||||
|
|
@ -34,6 +35,7 @@ module.exports = {
|
|||
Docusaurus can also load plugins from your local directory, you can do something like the following:
|
||||
|
||||
```jsx
|
||||
// docusaurus.config.js
|
||||
const path = require('path');
|
||||
|
||||
module.exports = {
|
||||
|
|
@ -45,7 +47,7 @@ module.exports = {
|
|||
|
||||
Plugins are modules which export a function that takes in the context, options and returns a plain JavaScript object that has some properties defined.
|
||||
|
||||
For examples, please refer to several official plugins created.
|
||||
For examples, please refer to several [official plugins](https://github.com/facebook/docusaurus/tree/master/packages) created.
|
||||
|
||||
```jsx
|
||||
const DEFAULT_OPTIONS = {
|
||||
|
|
@ -3,7 +3,7 @@ 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.
|
||||
To generate a sidebar to your Docusaurus site, you need to define a file that exports a JS module and pass that into the `@docusaurus/plugin-docs` plugin directly or via `@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 -->
|
||||
|
||||
|
|
@ -29,7 +29,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
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.
|
||||
The `docs` key in the exported object 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
|
||||
|
||||
|
|
|
|||
|
|
@ -3,28 +3,29 @@ id: static-assets
|
|||
title: Static Assets
|
||||
---
|
||||
|
||||
In general, every website needs assets: images, stylesheets, favicons and etc. In such cases,
|
||||
you can create a folder named `static` at the root of your project. Every file you put into that folder will be copied into the generated build folder. E.g. if you add a file named `sun.jpg` to the static folder, it’ll be copied to `build/sun.jpg`
|
||||
In general, every website needs assets: images, stylesheets, favicons and etc. In such cases, you can create a directory named `static` at the root of your project. Every file you put into that directory will be copied into the the root of the generated `build` folder with the directory hierarchy preserved. E.g. if you add a file named `sun.jpg` to the static folder, it’ll be copied to `build/sun.jpg`.
|
||||
|
||||
This means that if the site's baseUrl is `/`, an image in `static/img/docusaurus_keytar.svg` is available at `docusaurus_keytar.svg`.
|
||||
This means that if the site's `baseUrl` is `/`, an image in `/static/img/docusaurus_keytar.svg` is available at `<baseUrl>/docusaurus_keytar.svg`.
|
||||
|
||||
<!-- TODO: Yangshun: This is inaccurate for sites with a non '/' baseUrl -->
|
||||
|
||||
## Referencing your static asset
|
||||
|
||||
You can reference assets from the static folder in your code with absolute path, i.e. starting with a slash /.
|
||||
|
||||
Markdown example:
|
||||
### Markdown example
|
||||
|
||||
```markdown
|
||||
<!-- reference static/img/docusaurus.png -->
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
|
||||
|
||||
|
||||
JSX example:
|
||||
### JSX example
|
||||
|
||||
```jsx
|
||||
// reference static/img/slash-birth.png
|
||||
|
|
@ -35,8 +36,7 @@ Result:
|
|||
|
||||
<img src="/img/slash-birth.png" alt="docusaurus mascot" />
|
||||
|
||||
|
||||
Keep in mind that:
|
||||
|
||||
- None of the files in static folder will be post-processed or minified.
|
||||
- Missing files will not be called at compilation time, and will cause 404 errors for your users.
|
||||
- Missing files will not be called at compilation time, and will result in a 404 error.
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ title: Styling and Layout
|
|||
|
||||
## Traditional CSS
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
```diff
|
||||
// docusaurus.config.js
|
||||
|
|
@ -26,15 +26,15 @@ module.exports = {
|
|||
|
||||
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
|
||||
## 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/).
|
||||
`@docusaurus/preset-classic` uses [Infima](https://infima-dev.netlify.com/) as the underlying styling framework. Infima provides flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). For more details, check out the [Infima website](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
|
||||
/**
|
||||
* src/css/custom.css
|
||||
* /src/css/custom.css
|
||||
* You can override the default Infima variables here.
|
||||
* Note: this is not a complete list of --ifm- variables.
|
||||
*/
|
||||
|
|
@ -49,22 +49,24 @@ When you `init` your Docusaurus 2 project, the website will be generated with ba
|
|||
}
|
||||
```
|
||||
|
||||
In future, we will provide an easier way to generate the different shades of colors.
|
||||
|
||||
<!-- TODO need more refinement here -->
|
||||
|
||||
## Styling Approaches
|
||||
## Styling approaches
|
||||
|
||||
A Docusaurus site is a single-page React application. You can style it the way you style React apps.
|
||||
|
||||
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.
|
||||
|
||||
### Global Styles
|
||||
### Global styles
|
||||
|
||||
This is the most traditional way of styling that most developers (including non-front end developers) would be familiar with.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
```css
|
||||
/* src/css/custom.css */
|
||||
/* /src/css/custom.css */
|
||||
.purple-text {
|
||||
color: rebeccapurple;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
id: themes
|
||||
id: themes-api
|
||||
title: Themes
|
||||
---
|
||||
|
||||
|
|
@ -7,11 +7,11 @@ title: Using Plugins
|
|||
|
||||
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 [Google Analytics](#docusaurus-plugin-content-analytics) and [Sitemap](#docusaurus-plugin-content-sitemap). You may also write your own plugins for customized features.
|
||||
Docusaurus 2 provides a few essential plugins such as [Google Analytics](advanced-plugins.md#docusaurusplugin-google-analytics) and [Sitemap](advanced-plugins.md#docusaurusplugin-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](advanced-plugins.md). For API reference, check out [API Reference: Plugins](api-plugins.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](plugins-api.md).
|
||||
|
||||
## Using Plugins
|
||||
## Using plugins
|
||||
|
||||
To use a plugin, add the plugin to the `plugins` field of your `docusaurus.config.js`.
|
||||
|
||||
|
|
@ -35,9 +35,9 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
## Passing Options to Docusaurus Plugins Within Preset
|
||||
## Passing options to Docusaurus plugins via 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](advanced-plugins.md).
|
||||
Docusaurus' classic template is scaffolded with the classic preset, which 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`
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ High-level overview about themes:
|
|||
Related pieces
|
||||
---
|
||||
- [Advanced Guide – Themes](advanced-themes.md)
|
||||
- [API - Themes](api-themes.md)
|
||||
- [API - Themes](themes-api.md)
|
||||
|
||||
References
|
||||
---
|
||||
|
|
|
|||
|
|
@ -16,10 +16,11 @@ module.exports = {
|
|||
Guides: [
|
||||
'creating-pages',
|
||||
'styling-layout',
|
||||
'static-assets',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Docs',
|
||||
items: ['markdown-features', 'sidebar', 'static-assets'],
|
||||
items: ['markdown-features', 'sidebar'],
|
||||
},
|
||||
'blog',
|
||||
'reaching-users',
|
||||
|
|
@ -37,6 +38,7 @@ module.exports = {
|
|||
'docusaurus-core',
|
||||
'docusaurus.config.js',
|
||||
'plugins-api',
|
||||
'themes-api',
|
||||
],
|
||||
},
|
||||
};
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue