mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-02 10:52:35 +02:00
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!
This commit is contained in:
Endi
Yangshun Tay
parent
9bb6ba113d
commit
404983c32b
7 changed files with 257 additions and 45 deletions
|
|
@ -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/
|
||||
<!-- TODO: What will the user see if pages/ is empty? -->
|
||||
|
||||
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 (
|
||||
<Layout title="Hello">
|
||||
<div
|
||||
style={{
|
||||
display: 'flex',
|
||||
justifyContent: 'center',
|
||||
alignItems: 'center',
|
||||
height: '50vh',
|
||||
fontSize: '20px',
|
||||
}}>
|
||||
<p>
|
||||
Edit <code>pages/hello.js</code> and save to reload.
|
||||
</p>
|
||||
</div>
|
||||
</Layout>
|
||||
);
|
||||
}
|
||||
|
||||
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` → `<baseUrl>/`
|
||||
- `pages/test.js` → `<baseUrl>/test`
|
||||
- `pages/foo/test.js` → `<baseUrl>/foo/test`
|
||||
- `pages/foo/index.js` → `<baseUrl>/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.
|
||||
|
||||
<!--
|
||||
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.
|
||||
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
||||
<!--
|
||||
TODO: Talk about deployment steps and different hosting options.
|
||||
|
||||
#### References
|
||||
|
||||
References:
|
||||
- https://www.gatsbyjs.org/docs/deploying-and-hosting/
|
||||
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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!
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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 (<kbd>Cmd</kbd> + <kbd>C</kbd> or <kbd>Ctrl</kbd> + <kbd>C</kbd>) 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!_
|
||||
|
||||
<Trend
|
||||
smooth
|
||||
autoDraw
|
||||
autoDrawDuration={3000}
|
||||
autoDrawEasing="ease-out"
|
||||
data={[0, 2, 5, 9, 5, 10, 3, 5, 0, 0, 1, 8, 2, 9, 0]}
|
||||
gradient={['#00c6ff', '#F0F', '#FF0']}
|
||||
radius={10}
|
||||
strokeWidth={2}
|
||||
strokeLinecap={'butt'}
|
||||
/>
|
||||
```
|
||||
|
||||
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 😉!
|
||||
|
||||
<!-- TODO: Briefly explain MDX more -->
|
||||
|
||||
## 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.
|
||||
|
||||
<!-- TODO: Briefly sidebar more -->
|
||||
|
||||
<!--
|
||||
TODO: Talk more about using the official docs plugin and how to configure the sidebar. Mention about incorporating assets and a preview of the cool Markdown features available, but don't list all the Markdown features here.
|
||||
|
||||
|
||||
#### References
|
||||
|
||||
References:
|
||||
- https://docusaurus.io/docs/en/navigation
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -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',
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue