Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(v2): various improvements #2768

Merged
merged 1 commit into from
May 18, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions website/docs/blog.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,13 +118,13 @@ module.exports = {

Accessing the feed:

The feed for RSS can be found at
The feed for RSS can be found at:

```text
https://{your-domain}/blog/rss.xml
```

and for atom
and for Atom:

```text
https://{your-domain}/blog/atom.xml
Expand All @@ -134,9 +134,7 @@ https://{your-domain}/blog/atom.xml

### Blog-only mode

You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `''` to indicate it's the root path.

**Note:** Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route!
You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path.

```js {9} title="docusaurus.config.js"
module.exports = {
Expand All @@ -155,6 +153,12 @@ module.exports = {
};
```

:::note

Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route!

:::

<!--

Adding a blog using the blog plugin.
Expand Down
10 changes: 5 additions & 5 deletions website/docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@ Builds and serves a preview of your site locally with [Webpack Dev Server](https

| Name | Default | Description |
| --- | --- | --- |
| `--port` | `3000` | Specifies the port of the dev server |
| `--host` | `localhost` | Specify a host to use. E.g., if you want your server to be accessible externally, you can use `--host 0.0.0.0` |
| `--port` | `3000` | Specifies the port of the dev server. |
| `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). |
| `--no-open` | `false` | Do not open automatically the page in the browser. |
| `--poll` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). |
Expand All @@ -64,7 +64,7 @@ Compiles your site for production.

| Name | Default | Description |
| --- | --- | --- |
| `--bundle-analyzer` | `false` | Analyze your bundle with the [webpack bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) |
| `--bundle-analyzer` | `false` | Analyze your bundle with the [webpack bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). |
| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
| `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. |

Expand All @@ -81,7 +81,7 @@ Change any Docusaurus theme components to your liking with `docusaurus swizzle`.
```shell
docusaurus swizzle <themeName> [componentName] [siteDir]

# example (leaving out the siteDir to indicate this directory)
# Example (leaving out the siteDir to indicate this directory)
docusaurus swizzle @docusaurus/theme-classic DocSidebar
```

Expand All @@ -103,7 +103,7 @@ To learn more about swizzling, check [here](#).

### `docusaurus deploy`

Deploys your site with [GitHub Pages](https://pages.github.com/).
Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the docs on [deployment](deployment.md/#deploying-to-github-pages) for more details.

#### Options

Expand Down
10 changes: 5 additions & 5 deletions website/docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@ However, it can be helpful if you have a high-level understanding of how the con

The high-level overview of Docusaurus configuration can be categorized into:

- [Site Metadata](#site-metadata)
- [Deployment Configurations](#deployment-configurations)
- [Theme, Plugin, and Preset Configurations](#theme-plugin-and-preset-configurations)
- [Custom Configurations](#custom-configurations)
- [Site metadata](#site-metadata)
- [Deployment configurations](#deployment-configurations)
- [Theme, plugin, and preset configurations](#theme-plugin-and-preset-configurations)
- [Custom configurations](#custom-configurations)

For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](docusaurus.config.js.md).

Expand Down Expand Up @@ -126,7 +126,7 @@ module.exports = {

Your configuration object will be made available to all the components of your site. And you may access them via React context as `siteConfig`.

Basic Example:
Basic example:

```jsx
import React from 'react';
Expand Down
2 changes: 1 addition & 1 deletion website/docs/creating-pages.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ In this component-based development era, it is encouraged to co-locate your styl
- 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`).
The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, 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
Expand Down
14 changes: 7 additions & 7 deletions website/docs/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,8 +117,8 @@ To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first

```js {2-3} title="docusaurus.config.js"
module.exports = {
url: 'https://docusaurus-2.netlify.com', // url to your site with no trailing slash
baseUrl: '/', // base directory of your site relative to your repo
url: 'https://docusaurus-2.netlify.com', // Url to your site with no trailing slash
baseUrl: '/', // Base directory of your site relative to your repo
// ...
};
```
Expand Down Expand Up @@ -152,7 +152,7 @@ Most importantly, however, deploying a Docusaurus project only takes a couple of
npm i -g now
```

2. Run a single command inside the root directory of your project:
1. Run a single command inside the root directory of your project:

```bash
now
Expand All @@ -168,9 +168,9 @@ Render offers [free static site hosting](https://render.com/docs/static-sites) w

1. Create a new **Web Service** on Render, and give Render permission to access your Docusaurus repo.

2. Select the branch to deploy. The default is `master`.
1. Select the branch to deploy. The default is `master`.

3. Enter the following values during creation.
1. Enter the following values during creation.

| Field | Value |
| --------------------- | ------------- |
Expand All @@ -192,13 +192,13 @@ Deploy your app in a matter of seconds using surge with the following steps:
npm install --g surge
```

2. To build the static files of your site for production in the root directory of your project, run:
1. To build the static files of your site for production in the root directory of your project, run:

```bash
npm run build
```

3. Then, run this command inside the root directory of your project:
1. Then, run this command inside the root directory of your project:

```bash
surge build/
Expand Down
12 changes: 6 additions & 6 deletions website/docs/docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Every document has a unique `id`. By default, a document `id` is the name of the
For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`.

```bash
website # root directory of your site
website # Root directory of your site
└── docs
   ├── greeting.md
└── guide
Expand Down Expand Up @@ -61,7 +61,7 @@ The document id of `_index` is reserved exclusively for the home doc page, so it

:::note

The page `docs` that you created (eg. `src/pages/docs.js`) will take precedence over the route generated via the `homePageId` option.
The page `docs` that you created (eg. `src/pages/docs.js`) will take precedence over the route generated via the `homePageId` option.

:::

Expand Down Expand Up @@ -89,7 +89,7 @@ module.exports = {

### Sidebar object

A sidebar object is defined like this.
A sidebar object is defined like this:

```typescript
type Sidebar = {
Expand Down Expand Up @@ -211,8 +211,8 @@ Sidebar item type that links to a non-document page. Example:
```js
{
type: 'link',
label: 'Custom Label', // string - the label that should be displayed.
href: 'https://example.com' // string - the target URL.
label: 'Custom Label', // The label that should be displayed (string).
href: 'https://example.com' // The target URL (string).
}
```

Expand All @@ -230,7 +230,7 @@ Sidebar item type that links to doc without bounding it to the sidebar. Example:
```js
{
type: 'ref',
id: 'doc1', // string - document id
id: 'doc1', // Document id (string).
}
```

Expand Down
2 changes: 1 addition & 1 deletion website/docs/docusaurus-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ function MyPage() {

| Field | Description |
| --- | --- |
| `ExecutionEnvironment.canUseDOM` | `true` if on client, `false` if SSR. |
| `ExecutionEnvironment.canUseDOM` | `true` if on client, `false` if prerendering. |
| `ExecutionEnvironment.canUseEventListeners` | `true` if on client and has `window.addEventListener`. |
| `ExecutionEnvironment.canUseIntersectionObserver` | `true` if on client and has `IntersectionObserver`. |
| `ExecutionEnvironment.canUseViewport` | `true` if on client and has `window.screen`. |
2 changes: 1 addition & 1 deletion website/docs/docusaurus.config.js.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ module.exports = {

### `customFields`

Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`
Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`.

- Type: `Object`

Expand Down
4 changes: 2 additions & 2 deletions website/docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,8 @@ my-website

### 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.mdx).
- `/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.mdx).
- `/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.
Expand Down
12 changes: 5 additions & 7 deletions website/docs/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,11 @@ title: Introduction
description: Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.
---

import useBaseUrl from '@docusaurus/useBaseUrl';

## Disclaimer

It has been a year since we made the first **alpha release** of Docusaurus 2 and things have been pretty stable since then. Many of Facebook's new open source websites are using Docusaurus 2 now. At this point, we highly encourage you to use Docusaurus 2 over Docusaurus 1 for your new websites. For feedback and questions, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink:

**You should use this if**
**You should use this if:**

- :white_check_mark: You want to contribute to Docusaurus 2
- :white_check_mark: You want to build a modern website with client-side routing and prerendering
Expand All @@ -19,7 +17,7 @@ It has been a year since we made the first **alpha release** of Docusaurus 2 and
- :white_check_mark: You want to ease the pain of migration in future
- :white_check_mark: You do not need support for IE11

**Do not use this if**
**Do not use this if:**

- :x: You need a fully production-ready solution (try [Docusaurus 1](https://docusaurus.io/) instead)
- :x: You need the translation features present in v1
Expand All @@ -28,7 +26,7 @@ It has been a year since we made the first **alpha release** of Docusaurus 2 and

## A better Docusaurus is coming to town

<img alt="Docusaurus " src={useBaseUrl('img/slash-introducing.svg')} />
<img alt="Docusaurus " src={require('@docusaurus/useBaseUrl').default('img/slash-introducing.svg')} />

Docusaurus 1 used to be a pure documentation site generator. In Docusaurus 2, we rebuilt it from the ground up, allowing for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n (_coming soon_).

Expand All @@ -44,8 +42,8 @@ Docusaurus is built with high attention to your experience building your site an
- Extend and customize with React
- Gain full control of your site's browsing experience by `swizzling` in your own components
- **Pluggable**
- Bootstrap your site with a basic template, then pick and plug functionalities built by us and our community.
- Open source your plugins to share with your fellow documentarians, because sharing is caring.
- Bootstrap your site with a basic template, then pick and plug functionalities built by us and our community
- Open source your plugins to share with your fellow documentarians, because sharing is caring
- ✂️ **Developer experience**
- Multiple bootstrapping templates to get your site up and running, start writing your docs right now
- Universal configuration entry point to make it more maintainable by contributors
Expand Down
30 changes: 15 additions & 15 deletions website/docs/lifecycle-apis.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,12 +111,12 @@ module.exports = function(context, options) {
name: 'docusaurus-plugin',
async contentLoaded({content, actions}) {
const {createData, addRoute} = actions;
// create a data named 'prizes.json'
// Create a data named 'prizes.json'.
const prizes = JSON.stringify(['$1', 'a cybertruck', 'nothing']);
const prizesDataPath = await createData('prizes.json', prizes);

// add '/roll' page using 'website/src/component/roll.js` as the component
// and providing 'prizes' as props
// Add '/roll' page using 'website/src/component/roll.js` as the component
// and providing 'prizes' as props.
addRoute({
path: '/roll',
component: '@site/src/components/roll.js',
Expand Down Expand Up @@ -201,7 +201,7 @@ module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
// Print out to console all the rendered routes
// Print out to console all the rendered routes.
routesPaths.map((route) => {
console.log(route);
});
Expand Down Expand Up @@ -234,7 +234,7 @@ module.exports = function (context, options) {

## `injectHtmlTags()`

Inject head and/or body html tags to Docusaurus generated html.
Inject head and/or body HTML tags to Docusaurus generated HTML.

```typescript
function injectHtmlTags(): {
Expand All @@ -247,7 +247,7 @@ type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];

interface HtmlTagObject {
/**
* Attributes of the html tag
* Attributes of the HTML tag
* E.g. `{'disabled': true, 'value': 'demo', 'rel': 'preconnect'}`
*/
attributes?: {
Expand Down Expand Up @@ -368,22 +368,22 @@ module.exports = function (context, opts) {
name: 'docusaurus-my-project-cool-plugin',

async loadContent() {
// The loadContent hook is executed after siteConfig and env has been loaded
// You can return a JavaScript object that will be passed to contentLoaded hook
// The loadContent hook is executed after siteConfig and env has been loaded.
// You can return a JavaScript object that will be passed to contentLoaded hook.
},

async contentLoaded({content, actions}) {
// contentLoaded hook is done after loadContent hook is done
// actions are set of functional API provided by Docusaurus. e.g: addRoute
// The contentLoaded hook is done after loadContent hook is done.
// `actions` are set of functional API provided by Docusaurus (e.g. addRoute)
},

async routesLoaded(routes) {
// routesLoaded hook is done after contentLoaded hook is done
// The routesLoaded hook is done after contentLoaded hook is done.
// This can be useful if you need to change any route.
},

async postBuild(props) {
// after docusaurus <build> finish
// After docusaurus <build> finish.
},

// TODO
Expand All @@ -408,7 +408,7 @@ module.exports = function (context, opts) {
},

getPathsToWatch() {
// Path to watch
// Paths to watch.
},

getThemePath() {
Expand All @@ -423,11 +423,11 @@ module.exports = function (context, opts) {
},

extendCli(cli) {
// Register an extra command to enhance the CLI of docusaurus
// Register an extra command to enhance the CLI of Docusaurus
},

injectHtmlTags() {
// Inject head and/or body html tags
// Inject head and/or body HTML tags.
},
};
};
Expand Down
Loading