From 8be7ac3e027cbe186fc1b3b23c861e77db81b165 Mon Sep 17 00:00:00 2001 From: Yangshun Tay Date: Thu, 2 Apr 2020 12:20:21 +0800 Subject: [PATCH] docs(v2): misc docs updates --- .../src/theme/DocItem/index.js | 11 +- website/docs/configuration.md | 49 -------- website/docs/creating-pages.md | 8 ++ website/docs/deployment.md | 106 ++++++++-------- website/docs/{sidebar.md => docs.md} | 116 +++++++++++++----- website/docs/installation.md | 14 ++- website/docs/introduction.md | 12 +- website/docs/styling-layout.md | 2 +- website/docs/versioning.md | 8 +- website/sidebars.js | 2 +- 10 files changed, 167 insertions(+), 161 deletions(-) rename website/docs/{sidebar.md => docs.md} (74%) diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/index.js b/packages/docusaurus-theme-classic/src/theme/DocItem/index.js index 69e45d6f1ef5..f25f2758b17c 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocItem/index.js +++ b/packages/docusaurus-theme-classic/src/theme/DocItem/index.js @@ -108,18 +108,17 @@ function DocItem(props) {
{version && ( - - Version: {version} - +
+ + Version: {version} + +
)} {!hideTitle && (

{title}

)} -
diff --git a/website/docs/configuration.md b/website/docs/configuration.md index 64169d7eaee4..ea06d7317463 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -144,52 +144,3 @@ const Hello = () => { 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`. ::: - -## Docs-only mode - -While Docusaurus is a performant static site generator with support for blogs, product landing and marketing pages, some sites just want the documentation component. - -Here are some steps you need to follow for a "docs-only mode": - -1. Set the `routeBasePath` property of the `docs` object in `@docusaurus/preset-classic` in `docusaurus.config.js` to the root of your site: - -```js {8} title="docusaurus.config.js" -module.exports = { - // ... - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - routeBasePath: '', // Set to empty string. - ... - }, - }, - ], - ], - // ... -}; -``` - -2. Set up a redirect to the initial document on the home page in `src/pages/index.js`, e.g. for the document `getting-started`. This is needed because by default there's no page created for the root of the docs. - -```jsx -import React from 'react'; - -import {Redirect} from '@docusaurus/router'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -function Home() { - return ; -} - -export default Home; -``` - -Now, when visiting your site, it will show your initial document instead of a landing page. - -:::tip - -There's also a "blog-only mode", for those who only want to use the blog component of Docusaurus 2. You can use the same method detailed above, except that you need to delete the `src/pages/index.js` file. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode). - -::: diff --git a/website/docs/creating-pages.md b/website/docs/creating-pages.md index 2d9e97961a78..887060f72285 100644 --- a/website/docs/creating-pages.md +++ b/website/docs/creating-pages.md @@ -5,6 +5,8 @@ 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 like a showcase page, playground page or support page. +The functionality of pages is powered by `@docusaurus/plugin-content-pages`. + ## Adding a new page @@ -75,6 +77,12 @@ my-website . ``` +:::caution + +All JavaScript/TypeScript files within the `src/pages/` directory will have corresponding website paths generated for them. Do not put reusable components or test files (ending with `.test.js`) into that directory otherwise they will be turned into pages, which might not be intended. + +::: + ## 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 expressiveness of React to build rich and interactive content. diff --git a/website/docs/deployment.md b/website/docs/deployment.md index 739836cca09d..e31bcd399a9b 100644 --- a/website/docs/deployment.md +++ b/website/docs/deployment.md @@ -13,31 +13,9 @@ Once it finishes, you should see the production build under the `build/` directo You can deploy your site to static site hosting services such as [ZEIT Now](https://zeit.co/now), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), [Render](https://render.com/static-sites), and [Surge](https://surge.sh/help/getting-started-with-surge). Docusaurus sites are statically rendered so they work without JavaScript too! -## Deploying to ZEIT Now - -Deploying your Docusaurus project to [ZEIT Now](https://zeit.co/now) will provide you with [various benefits](https://zeit.co/now) in the areas of performance and ease of use. - -Most importantly, however, deploying a Docusaurus project only takes a couple seconds: - -1. First, install their [command-line interface](https://zeit.co/download): - -```bash -npm i -g now -``` - -2. Run a single command inside the root directory of your project: - -```bash -now -``` - -**That's all.** Your docs will automatically be deployed. - -Now you can connect your site to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit. - ## Deploying to GitHub Pages -Docusaurus provides a easy way to publish to GitHub Pages. +Docusaurus provides a easy way to publish to [GitHub Pages](https://pages.github.com/). Which is hosting that comes for free with every GitHub repository. ### `docusaurus.config.js` settings @@ -105,13 +83,33 @@ GIT_USER= yarn deploy cmd /C "set "GIT_USER=" && yarn deploy" ``` - +1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). +1. Using your GitHub account, [add the Travis CI app](https://github.com/marketplace/travis-ci) to the repository you want to activate. +1. Open your Travis CI dashboard. The URL looks like https://travis-ci.com/USERNAME/REPO, and navigate to the `More options` > `Setting` > `Environment Variables` section of your repository. +1. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username). +1. Create a `.travis.yml` on the root of your repository with the following: + +```yaml title=".travis.yml" +language: node_js +node_js: + - '10' +branches: + only: + - master +cache: + yarn: true +script: + - git config --global user.name "${GH_NAME}" + - git config --global user.email "${GH_EMAIL}" + - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc + - yarn && GIT_USER="${GH_NAME}" yarn deploy +``` + +Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script. ## Deploying to Netlify @@ -142,6 +140,28 @@ Make sure to disable Netlify setting `Pretty URLs` to prevent lowercased URLs, u ::: +## Deploying to ZEIT Now + +Deploying your Docusaurus project to [ZEIT Now](https://zeit.co/now) will provide you with [various benefits](https://zeit.co/now) in the areas of performance and ease of use. + +Most importantly, however, deploying a Docusaurus project only takes a couple seconds: + +1. First, install their [command-line interface](https://zeit.co/download): + +```bash +npm i -g now +``` + +2. Run a single command inside the root directory of your project: + +```bash +now +``` + +**That's all.** Your docs will automatically be deployed. + +Now you can connect your site to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit. + ## 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. @@ -160,35 +180,7 @@ Render offers [free static site hosting](https://render.com/docs/static-sites) w That's it! Your app will be live on your Render URL as soon as the build finishes. -### Deploying to Travis CI - -Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate deployment of your website is to invoke the `yarn deploy` script whenever your website is updated. The following section covers how to do just that using [Travis CI](https://travis-ci.com/), a popular continuous integration service provider. - -1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) -1. Using your GitHub account, [add the Travis CI app](https://github.com/marketplace/travis-ci) to the repository you want to activate. -1. Open your Travis CI dashboard. The URL looks like https://travis-ci.com/USERNAME/REPO, and navigate to the `More options` > `Setting` > `Environment Variables` section of your repository. -1. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username). -1. Create a `.travis.yml` on the root of your repository with the following: - -```yaml title=".travis.yml" -language: node_js -node_js: - - '10' -branches: - only: - - master -cache: - yarn: true -script: - - git config --global user.name "${GH_NAME}" - - git config --global user.email "${GH_EMAIL}" - - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc - - yarn && GIT_USER="${GH_NAME}" yarn deploy -``` - -Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script. - -## Deploying with Surge +## Deploying to Surge Surge is a [static web hosting platform](https://surge.sh/help/getting-started-with-surge), it is used to deploy your Docusaurus project from command line in a minute. Deploying your project to Surge is easy and it is also free (including a custom domain and SSL). diff --git a/website/docs/sidebar.md b/website/docs/docs.md similarity index 74% rename from website/docs/sidebar.md rename to website/docs/docs.md index bffa432e281d..fed1dbb8d0ed 100644 --- a/website/docs/sidebar.md +++ b/website/docs/docs.md @@ -1,8 +1,36 @@ --- -id: sidebar -title: Sidebar +id: docs +title: Docs Introduction +sidebar_label: Introduction --- +The docs feature provides users with a way to organize Markdown files in a hierarchical format. + +## Document ID + +Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory. + +For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`. + +```bash +website # root directory of your site +└── docs +   ├── greeting.md + └── guide + └── hello.md +``` + +However, the last part of the `id` can be defined by user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`. + +```yml +--- +id: part1 +--- +Lorem ipsum +``` + +## Sidebar + To generate a sidebar to your Docusaurus site, you need to define a file that exports a sidebar object and pass that into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`. ```js {8-9} title="docusaurus.config.js" @@ -23,7 +51,7 @@ module.exports = { }; ``` -## Sidebar object +### Sidebar object A sidebar object is defined like this. @@ -83,30 +111,7 @@ module.exports = { }; ``` -## Document ID - -Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory. - -For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`. - -```bash -website # root directory of your site -└── docs -   ├── greeting.md - └── guide - └── hello.md -``` - -However, the last part of the `id` can be defined by user in the frontmatter. For example, if `guide/hello.md` content is defined as below, it's final `id` is `guide/part1`. - -```yml ---- -id: part1 ---- -Lorem ipsum -``` - -## Sidebar item +#### Sidebar item As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a few types we support: @@ -115,7 +120,7 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a - [Ref](#ref) - [Category](#category) -### Doc +#### Doc ```typescript type SidebarItemDoc = @@ -155,7 +160,7 @@ module.exports = { }; ``` -### Link +#### Link ```typescript type SidebarItemLink = { @@ -175,7 +180,7 @@ Sidebar item type that links to a non-document page. Example: } ``` -### Ref +#### Ref ```typescript type SidebarItemRef = { @@ -193,7 +198,7 @@ Sidebar item type that links to doc without bounding it to the sidebar. Example: } ``` -### Category +#### Category This is used to add hierarchies to the sidebar: @@ -237,7 +242,7 @@ module.exports = { }; ``` -### Collapsible categories +#### Collapsible categories For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`: @@ -250,3 +255,50 @@ module.exports = { }, } ``` + +## Docs-only mode + +If you just want the documentation feature, you can follow the instructions for a "docs-only mode": + +1. Set the `routeBasePath` property of the `docs` object in `@docusaurus/preset-classic` in `docusaurus.config.js` to the root of your site: + +```js {8} title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + routeBasePath: '', // Set to empty string. + ... + }, + }, + ], + ], + // ... +}; +``` + +2. Set up a redirect to the initial document on the home page in `src/pages/index.js`, e.g. for the document `getting-started`. This is needed because by default there's no page created for the root of the docs. + +```jsx title="src/pages/index.js" +import React from 'react'; + +import {Redirect} from '@docusaurus/router'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +function Home() { + return ; +} + +export default Home; +``` + +Now, when visiting your site, it will show your initial document instead of a landing page. + +:::tip + +There's also a "blog-only mode", for those who only want to use the blog component of Docusaurus 2. You can use the same method detailed above, except that you need to delete the `src/pages/index.js` file. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode). + +::: diff --git a/website/docs/installation.md b/website/docs/installation.md index 46d003069abb..2b6208852004 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -26,7 +26,7 @@ npx @docusaurus/init@next init my-website classic 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. -**Important Note:** If you are setting up a new Docusaurus website for a Facebook open source project, use the `facebook` template instead, which comes with some useful Facebook-specific defaults: +**[FB-Only]:** If you are setting up a new Docusaurus website for a Facebook open source project, use the `facebook` template instead, which comes with some useful Facebook-specific defaults: ```bash npx @docusaurus/init@next init my-website facebook @@ -101,10 +101,16 @@ and contents will be generated within the `/build` directory, which can be copie There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in `package.json` to the desired version. Note that all `@docusaurus/`-namespaced packages should be using the same version. +:::important + +Please update to the latest Docusaurus 2 version shown at the top of the page, not what is shown below. + +::: + ```json "dependencies": { - "@docusaurus/core": "^2.0.0-alpha.48", - "@docusaurus/preset-classic": "^2.0.0-alpha.48", + "@docusaurus/core": "^2.0.0-alpha.49", + "@docusaurus/preset-classic": "^2.0.0-alpha.49", ... } ``` @@ -126,7 +132,7 @@ You should see the correct version as output. Alternatively, if you are using Yarn, you can do: ``` -yarn upgrade @docusaurus/core@2.0.0-alpha.48 @docusaurus/preset-classic@2.0.0-alpha.48 +yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49 ``` ## Problems? diff --git a/website/docs/introduction.md b/website/docs/introduction.md index aea8fab09b8a..2a52e7338717 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -6,7 +6,7 @@ description: Docusaurus was designed from the ground up to be easily installed a import useBaseUrl from '@docusaurus/useBaseUrl'; -## :warning: Disclaimer +## Disclaimer This is an **early and alpha release** of Docusaurus 2. We are making it available early to maximize community participation and feedback. Expect it to evolve a lot over the course of the alpha-beta period. If you are adventurous enough to be an early adopter, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink:. @@ -18,7 +18,7 @@ This is an **early and alpha release** of Docusaurus 2. We are making it availab **Do not use this if** -- :x: You need a full production-ready solution (try [Docusaurus 1](https://docusaurus.io/) instead) +- :x: You need a full production-ready solution (try [Docusaurus 1](https://docusaurus.io/) instead) - :x: You need the translation features present in v1 - :x: You prefer not to work with potential breaking changes and/or features not yet working properly as we improve it during alpha period @@ -82,19 +82,19 @@ 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 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 documentation site. As a result, many have turned 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. +Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone. ### Jekyll Jekyll is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with Jekyll. -In comparison with statically generated HTML and interactivity based on `