mirror of
https://github.com/facebook/docusaurus.git
synced 2025-12-26 01:33:02 +00:00
Update README.md
This commit is contained in:
Frank Li
GitHub
parent
2256bc922e
commit
712b558c2e
127
README.md
127
README.md
|
|
@ -2,57 +2,87 @@
|
|||
|
||||
## Getting Started
|
||||
|
||||
In your project repo, make sure you have a `docs` folder containing all of your documentation files written in markdown. Create a `website` folder inside which you will install and run docusaurus. If you wish, you can also include a `blog` folder in your project repo at the same level as the `docs` folder for blog posts.
|
||||
### Project Structure
|
||||
|
||||
Install Docusaurus using `npm`:
|
||||
In your project repo, all of your documentation files should be placed inside a `docs` folder. Any blog posts should be inside a `blog` folder. Create a `website` folder inside which you will install and run docusaurus.
|
||||
|
||||
```
|
||||
cd website
|
||||
npm install --save-dev docusaurus
|
||||
```
|
||||
### Installation
|
||||
|
||||
In your `package.json` file, add the following scripts for docusaurus:
|
||||
Inside of your `website` folder, create a `package.json` file with the following scripts for Docusaurus:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"start": "docusaurus-start",
|
||||
"build": "docusaurus-build",
|
||||
"publish-gh-pages": "docusaurus-publish",
|
||||
"examples": "docusaurus-examples"
|
||||
{
|
||||
"scripts": {
|
||||
"start": "docusaurus-start",
|
||||
"build": "docusaurus-build",
|
||||
"publish-gh-pages": "docusaurus-publish",
|
||||
"examples": "docusaurus-examples"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To create example files for configuration, run `examples` using npm:
|
||||
Install Docusaurus using `npm` or `yarn`:
|
||||
|
||||
```
|
||||
npm install --save-dev docusaurus
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
yarn add docusaurus -dev
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Generate Examples
|
||||
|
||||
To create example files for configuration, run `examples` using `npm` or `yarn`:
|
||||
|
||||
```
|
||||
npm run examples
|
||||
```
|
||||
|
||||
This will create the following files in your website folder:
|
||||
or
|
||||
|
||||
```
|
||||
yarn run examples
|
||||
```
|
||||
|
||||
|
||||
This will create the following files/folders in your website folder:
|
||||
|
||||
```
|
||||
core/Footer.js
|
||||
example-docs/en/doc1.md
|
||||
example-docs/en/doc2.md
|
||||
example-docs/en/doc3.md
|
||||
example-docs/en/exampledoc4.md
|
||||
example-docs/en/exampledoc5.md
|
||||
example-blog/2016-03-11-blog-post.md
|
||||
example-blog/2017-04-10-blog-post-two.md
|
||||
i18n/en.js
|
||||
pages/en/help.js
|
||||
pages/en/index.js
|
||||
pages/en/users.js
|
||||
example-blog/...
|
||||
example-docs/...
|
||||
pages/...
|
||||
static/img/...
|
||||
languages.js
|
||||
siteConfig.js
|
||||
```
|
||||
|
||||
`examples` will not overwrite any existing files of the same name in your website folder.
|
||||
|
||||
## Configuration
|
||||
The provided example files contain configurations for an example site.
|
||||
The `core/Footer.js` file is a React component that acts as the footer for the site generated by Docusaurus and should be customized by the user.
|
||||
The `example-blog` folder contains examples of blog posts written in markdown.
|
||||
The `example-docs` folder contains example documentation files written in markdown.
|
||||
The `pages` folder contains example top-level pages for the site.
|
||||
The `static` folder contains static assets used by the example site.
|
||||
The `siteConfig.js` file is the main configuration file used by Docusaurus.
|
||||
|
||||
The provided example files contain configurations for an example project `deltice/test-site` and with the documents in `example-docs/` and blog posts in `example-blog/`. These are provided for your reference to help you configure your project.
|
||||
### How to Configure Your Site
|
||||
|
||||
Configure the `siteConfig.js` file which has comments guiding you through what needs to be done and how each configuration affects your website.
|
||||
|
||||
Customize `core/Footer.js` which will serve as the footer for each page on your website.
|
||||
|
||||
Include your own top-level pages as React components in `pages`.
|
||||
- These components should just be the body sections of the pages you want, and they will be included with the header and footer that the rest of Docusaurus uses.
|
||||
- Currently, if you want to add other React components to your pages, you must include all of it inside that file due to how `require` paths are set-up.
|
||||
- You may also include `.html` files directly, but this is not recommended, and these will just be served as is and will not have any of the header/footer/styles shared by the rest of Docusaurus.
|
||||
|
||||
All images and other static assets you wish to include should be placed inside the `static` folder. Any `.css` files provided in `static` will be concatenated to the standard styles provided by Docusaurus and used site-wide.
|
||||
|
||||
### Document and Blog Front Matters
|
||||
|
||||
|
|
@ -62,7 +92,7 @@ Documentation should contain front matter that follows this example:
|
|||
id: doc1 <!-- used for docs to find each other and to map links -->
|
||||
title: Document Title
|
||||
layout: docs1 <!-- used to determine different sidebar groupings -->
|
||||
category: Sidebar Category 1 <!-- Category on the sidebar under which this doc goes -->
|
||||
category: Sidebar Category 1 <!-- category on the sidebar under which this doc goes -->
|
||||
permalink: docs/en/doc1.html <!-- link to the document that is used for site -->
|
||||
previous: doc0 <!-- previous doc on sidebar for navigation -->
|
||||
next: doc2 <!-- next doc on the sidebar for navigation -->
|
||||
|
|
@ -81,23 +111,6 @@ authorFBID: 21315325 <!-- id to get author's picture -->
|
|||
```
|
||||
In the blog post you should include a line `<!--truncate-->`. This will determine under which point text will be ignored when generating the preview of your blog post. Blog posts should have the file name format: `yyyy-mm-dd-your-file-name.md`.
|
||||
|
||||
### Language Configurations
|
||||
|
||||
If you wish to support websites for other languages, the `languages.js` file provides a list of what languages you wish to enable. Files in the `i18n` folder will provide localized versions of various strings.
|
||||
|
||||
If you only wish to have an English version of your site, the `i18n` folder and the `languages.js` file are not necessary to run Docusaurus and should be deleted.
|
||||
|
||||
### Site Configurations
|
||||
|
||||
Configure the siteConfig.js file which has comments guiding you through what needs to be done and how each configuration affects your website.
|
||||
|
||||
Customize core/Footer.js which will serve as the footer for each page on your website.
|
||||
|
||||
Include your own top-level pages as React components in `pages/`. These components should just be the body sections of the pages you want, and they will be included with the header and footer that the rest of Docusaurus uses. Examples are provided for your reference. Currently, if you want to add other React components to your pages, you must include all of it inside that file due to how `require` paths are set-up. You may also include `.html` files directly, but this is not recommended, and these will just be served as is and will not have any of the header/footer/styles shared by the rest of Docusaurus.
|
||||
|
||||
All images and other static assets you wish to include should be placed inside the `static` folder. Any `.css` files provided in `static` will be concatenated to the standard styles provided by Docusaurus and used site-wide.
|
||||
|
||||
Files placed in `static/` will be accessible in the following way: `static/img/image.png` will be accessible at `img/image.png`.
|
||||
|
||||
## Using Docusaurus
|
||||
|
||||
|
|
@ -109,7 +122,14 @@ To run your website locally run the script:
|
|||
npm run start
|
||||
```
|
||||
|
||||
This will start a server hosting your website locally at `localhost:3000`. This server will ignore any occurences `siteConfig.baseUrl` in URLs, e.g. `localhost:3000/your-site/index.html` will be the same as `localhost:3000/index.html`. Any changes to configured files will be reflected by refreshing the page, i.e. the server does not need to be restarted to show changes.
|
||||
or
|
||||
|
||||
```
|
||||
yarn run start
|
||||
```
|
||||
|
||||
|
||||
This will start a server hosting your website locally at `localhost:3000`. This server will ignore any occurences `siteConfig.baseUrl` in URLs, e.g. `localhost:3000/your-site/index.html` will be the same as `localhost:3000/index.html`. Any changes to configured files will be reflected by refreshing the page, i.e. the server does not need to be restarted to show changes. You may also specify a different port to start your server on as a command line argument, e.g. `npm run start 9000`.
|
||||
|
||||
|
||||
### Build Static Pages
|
||||
|
|
@ -120,7 +140,13 @@ To create a static build of your website, run the script:
|
|||
npm run build
|
||||
```
|
||||
|
||||
This will generate `.html` files from all of your docs and other pages included in `pages/`. This allows you to check whether or not all your files are being generated correctly. The build folder is inside Docusaurus's directory inside `node_modules`.
|
||||
or
|
||||
|
||||
```
|
||||
yarn run build
|
||||
```
|
||||
|
||||
This will generate `.html` files from all of your docs and other pages included in `pages`. This allows you to check whether or not all your files are being generated correctly. The build folder is inside Docusaurus's directory inside `node_modules`.
|
||||
|
||||
### Publishing Your Website
|
||||
|
||||
|
|
@ -154,3 +180,8 @@ If you wish to manually publish your website with the `publish-gh-pages` script,
|
|||
```
|
||||
DEPLOY_USER=deltice GIT_USER=test-site-bot CIRCLE_PROJECT_USERNAME=deltice CIRCLE_PROJECT_REPONAME=test-site CIRCLE_BRANCH=master npm run publish-gh-pages
|
||||
```
|
||||
|
||||
## More Information
|
||||
|
||||
For details on how to set up translation support, read [here](/docs/en/translation.md).
|
||||
For details on how to set up documentation search, read [here](/docs/en/search.md).
|
||||
|
|
|
|||
Loading…
Reference in New Issue