From 404983c32bbc977c8a8b370d2472f28f4a47a0b3 Mon Sep 17 00:00:00 2001 From: Endi Date: Wed, 29 May 2019 15:08:06 +0700 Subject: [PATCH] docs(v2): install, create pages, docs, deploy (#1522) * docs(v2): install, create pages, docs, deploy * docs(v2): Docs review changes for installation, create pages, docs, deploy * docs(v2): more docs! --- website/docs/creating-pages.md | 55 ++++++++++++++-- website/docs/deployment.md | 69 +++++++++++++++++++- website/docs/installation.md | 51 ++++++++++----- website/docs/introduction.md | 12 ++++ website/docs/project-structure.md | 16 ----- website/docs/writing-documentation.md | 94 ++++++++++++++++++++++++++- website/sidebars.js | 5 +- 7 files changed, 257 insertions(+), 45 deletions(-) delete mode 100644 website/docs/project-structure.md diff --git a/website/docs/creating-pages.md b/website/docs/creating-pages.md index b0465f771c..940d15af53 100644 --- a/website/docs/creating-pages.md +++ b/website/docs/creating-pages.md @@ -3,9 +3,56 @@ id: creating-pages title: Creating Pages --- -TODO: Explain the default pages routing behavior and talk about the official pages plugin. +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. -#### References +### Creating Pages -- https://docusaurus.io/docs/en/custom-pages -- https://www.gatsbyjs.org/docs/creating-and-modifying-pages/ + + +In the `pages` directory, create a file called `hello.js` with the following contents: + +```js +import React from 'react'; +import Layout from '@theme/Layout'; + +function Hello() { + return ( + +
+

+ Edit pages/hello.js and save to reload. +

+
+ + ); +} + +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: + +- `pages/index.js` → `/` +- `pages/test.js` → `/test` +- `pages/foo/test.js` → `/foo/test` +- `pages/foo/index.js` → `/foo` + +### Using React + +React is used as the UI library to create pages. You can leverage on the expressibility of React to build rich web content. + + diff --git a/website/docs/deployment.md b/website/docs/deployment.md index 4377a88e61..ce0471ed79 100644 --- a/website/docs/deployment.md +++ b/website/docs/deployment.md @@ -3,8 +3,73 @@ id: deployment title: Deployment --- +To build the static files of your website for production, run: + +```bash +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/), [Netlify](https://www.netlify.com/). Docusaurus sites are server 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 + +First, modify your `docusaurus.config.js` and add the required params: + +| Name | Description | +| --- | --- | +| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, it is your GitHub username. In the case of Docusaurus, it is "_facebook_" which is the GitHub organization that owns Docusaurus. | +| `projectName` | The name of the GitHub repository. For example, the repository name for Docusaurus is "docusaurus", so the project name is "docusaurus". | +| `url` | URL for your GitHub Page's user/organization page. This is commonly https://_username_.github.io. | +| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | + +You may refer to GitHub Pages' documentation [User, Organization, and Project Pages](https://help.github.com/en/articles/user-organization-and-project-pages) for more details. + +Example: + +```js +module.exports = { + ... + url: 'https://endiliey.github.io', // Your website URL + baseUrl: '/', + projectName: 'endiliey.github.io', + organizationName: 'endiliey' + ... +} +``` + +### Environment Settings + +Specify the Git user as an environment variable. + +| Name | Description | +| --- | --- | +| `GIT_USER` | The username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your GitHub username. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. | + +There are two more optional parameters that are set as environment variables: + +| Name | Description | +| --- | --- | +| `USE_SSH` | Set to `true` to use SSH instead of the default HTTPS for the connection to the GitHub repo. | +| `CURRENT_BRANCH` | The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `master`, but it could be any branch (default or otherwise) except for `gh-pages`. If nothing is set for this variable, then the current branch will be used. | + +### Deploy + +Finally, to deploy your site to GitHub Pages, run: + +```bash +GIT_USER=[yourGitHubUserName] yarn run deploy +``` + + diff --git a/website/docs/installation.md b/website/docs/installation.md index 1f5c5140e2..00d59a8a81 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -3,29 +3,46 @@ id: installation title: Installation --- -Docusaurus is a website generator that runs on the React ecosystem that is great for building static content such as project documentation, your personal home page, a portfolio. However, if you're not using advanced features, you don't have to know much React at all as you can use the default templates and write your content in Markdown. +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. -## Installation +```bash +npx @docusaurus/core@next init +``` -TODO +It will then prompt you for the `name` and the `template` for your Docusaurus site. We recommend the `classic` template so that you can get started quickly. The `classic` template comes with standard documentation, blog and custom pages features. -### New Project +## Project Structure -TODO: Mention tutorial +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/`: -### Adding to an Existing Project +```sh +my-website +├── docs +│ ├── doc1.md +│ ├── doc2.md +│ ├── doc3.md +│ ├── exampledoc4.md +│ └── exampledoc5.md +├── blog +│ ├── 2019-05-29-hello-world.md +│ └── 2020-05-30-welcome.md +├── package.json +├── pages +│ └── index.js +├── sidebars.json +├── docusaurus.config.js +├── static +│ └── img +└── yarn.lock +``` -TODO +## Running the Development Server -## Staying Informed +```bash +cd my-website +npm start +``` -TODO +A browser window will open at http://localhost:3000. -- Twitter -- Blog - -## 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. - -For new feature requests, you can create a post on our [Canny board](/feedback), which is a handy tool for roadmapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first! +Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available. diff --git a/website/docs/introduction.md b/website/docs/introduction.md index f0bc30d10b..e85224994e 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -65,3 +65,15 @@ Jekyll is one of the most mature static site generators around and has been a gr ### VuePress 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 + +- [GitHub](https://github.com/facebook/docusaurus) +- [Twitter](https://twitter.com/docusaurus) +- [Blog](/blog) + +## 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. + +For new feature requests, you can create a post on our [Canny board](/feedback), which is a handy tool for roadmapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first! diff --git a/website/docs/project-structure.md b/website/docs/project-structure.md deleted file mode 100644 index f573203b83..0000000000 --- a/website/docs/project-structure.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: project-structure -title: Project Structure ---- - -``` -// TODO: Display project directory structure -``` - -- TODO: Explain what each directory and files are about. -- TODO: Explain default page routing. - -#### References - -- https://docusaurus.io/docs/en/site-creation -- https://v1.vuepress.vuejs.org/guide/directory-structure.html diff --git a/website/docs/writing-documentation.md b/website/docs/writing-documentation.md index bc33dafde8..be0e364008 100644 --- a/website/docs/writing-documentation.md +++ b/website/docs/writing-documentation.md @@ -3,9 +3,97 @@ id: writing-documentation title: Writing Documentation --- +Next, let's touch on the powerful feature in Docusaurus - documentation. + +## Using Markdown + +Create a new file within the `docs` directory called `hello.md` with the following contents: + +```md +--- +title: Hello +--- + +I can write content using [GitHub-flavored Markdown syntax](https://github.github.com/gfm/). + +## Markdown Syntax + +**Bold** _italic_ `code` [Links](#url) + +> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing. + +- Hey +- Ho +- Let's Go +``` + +Docusaurus supports Markdown syntax using [Remark](https://github.com/remarkjs/remark) for Markdown parser and is extensible via plugins. + +## Embedding React Components + +Did you know that you can now write React components within your Markdown files? This is possible because of [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown documents. + +Now we'll add a third-party chart component into the Markdown file created above. Before that, kill your web server (Cmd + C or Ctrl + C) if it's running and install `react-trend` in your website directory. + +```bash +npm install react-trend +``` + +Start the development server again and go to http://localhost:3000/docs/hello, you will see a new page created from the Markdown file. + +Edit `docs/hello.md` and append the following: + +```mdx +import Trend from 'react-trend'; + +_Here's a bar chart!_ + + +``` + +Save the file and notice that the site is hot-reloaded with the edited content. + +We just imported a React component and embedded it within our markdown 😉! + + + +## Sidebar + +Next, let's add this page to the sidebar. + +Edit the `sidebars.json` file and add the `hello` document. + +```diff +{ + "docs": { ++ "Getting started": ["hello"], + "Docusaurus": ["doc1"], + "First Category": ["doc2"], + "Second Category": ["doc3"] + }, + "docs-other": { + "First Category": ["doc4", "doc5"] + } +} +``` + +You can see that there is a sidebar now on http://localhost:3000/docs/hello. + + + + diff --git a/website/sidebars.js b/website/sidebars.js index de77ec0c41..ba17e7c01a 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -10,13 +10,12 @@ module.exports = { 'Getting Started': [ 'introduction', 'installation', - 'project-structure', + 'creating-pages', + 'writing-documentation', 'deployment', ], Guides: [ 'configuration', - 'creating-pages', - 'writing-documentation', 'assets', 'markdown', 'styling-layout',