3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-04-29 10:17:55 +02:00
Code Issues Projects Releases Packages Wiki Activity

Update README, clean up getting started sections (#100)

Browse source
This commit is contained in:
Eric Nakagawa 2017-09-29 15:38:03 -07:00 • committed by Joel Marcey
parent 5c2c8570d2
commit a818d8fd7a
6 changed files with 73 additions and 417 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

202
README.md
View file

@ -1,200 +1,38 @@
# Docusaurus
## Getting Started
Docusaurus is a project for easily building, deploying, and maintaining open source project websites. __CI badges go here__
### Project Structure
* **Simple to Start** Docusaurus is built to be easy to get up and running in as little time possible. We've built Docusaurus to handle the website build process so you can focus on your project.
* **Localizable** Docusaurus ships with localization support via CrowdIn. Empower and grow your international community by translating your documentation.
* **Customizable** Docusaurus ships with the key pages and sections you need to get started. A home page, a docs section, a blog, and additional support pages.
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.
## Installation
Example project structure:
```
project-repo/
blog/
2017-05-06-blog-post.md
docs/
en/
doc1.md
website/
```
Docusaurus is available as `docusaurus` package on [npm](https://www.npmjs.com)
### Installation
The recommended way to use Docusaurs depends on your project. Here you can find short guides for the most common scenarios:
Inside of your `website` folder, create a `package.json` file with the following scripts for Docusaurus:
* [Starting from scratch](https://docusaurus.io/docs/getting-started-installation.html#starting-from-scratch)
* [Adding Docusaurus to an existing OSS project](https://docusaurus.io/docs/getting-started-installation.html#adding-docusaurus-to-a-project)
```json
{
"scripts": {
"start": "docusaurus-start",
"build": "docusaurus-build",
"publish-gh-pages": "docusaurus-publish",
"examples": "docusaurus-examples"
}
}
```
## Contributing
Install Docusaurus using `npm` or `yarn`:
We've released Docusaurus because it helps us better scale and support the many OSS projects at Facebook. We hope that other organizations can benefit from the project. We are thankful for any contributions from the community.
```
npm install --save-dev docusaurus
```
### [Code of Conduct](https://code.facebook.com/codeofconduct)
or
Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.facebook.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
```
yarn add docusaurus --dev
```
### Contributing Guide
## Configuration
Read our [contributing guide](https://docusaurus.io/docs/how-to-contribute.html) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Docusaurus.
### Generate Examples
### Beginner Friendly Bugs
To create example files for configuration, run `examples` using `npm` or `yarn`:
To help you get your feet wet and get you familiar with our contribution process, we have a list of [beginner friendly bugs](https://github.com/facebookexperimental/Docusaurus/labels/Difficulty%3A%20beginner) that contain bugs which are fairly easy to fix. This is a great place to get started.
```
npm run examples
```
### License
or
React is [? licensed](./LICENSE).
```
yarn run examples
```
This will create the following files/folders in your website folder:
```
core/Footer.js
example-blog/...
example-docs/...
pages/...
static/img/...
siteConfig.js
```
`examples` will not overwrite any existing files of the same name in your website folder.
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.
### 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
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 -->
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 -->
<!-- don't include next if this is the last doc; don't include previous if first doc -->
---
```
Blog posts should be written as markdown files with the following front matter:
```
---
title: Blog Post Title
author: Author Name
authorURL: http://twitter.com/author <!-- (or some other link) -->
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`.
## Using Docusaurus
### Run the Server
To run your website locally run the script:
```
npm run start
```
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 by using a `--port` flag:
```
npm run start -- --port 9000
```
### Build Static Pages
To create a static build of your website, run the script:
```
npm run build
```
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
Use CircleCI to publish your website whenever your project repo is updated. Configure your circle.yml file in your project repo to run commands to publish to GitHub Pages. An example is shown here:
```yaml
machine:
node:
version: 6.10.3
npm:
version: 3.10.10
test:
override:
- "true"
deployment:
website:
branch: master
commands:
- git config --global user.email "test-site-bot@users.noreply.github.com"
- git config --global user.name "Website Deployment Script"
- echo "machine github.com login test-site-bot password $GITHUB_TOKEN" > ~/.netrc
- cd website && npm install && GIT_USER=test-site-bot npm run publish-gh-pages
```
Note that in this case a GitHub user `test-site-bot` is created to use just for publishing. Make sure to give your Git user push permissions for your project and to set a GITHUB_TOKEN environment variable in Circle if you choose to publish this way.
If you wish to manually publish your website with the `publish-gh-pages` script, run the following example command with the appropriate variables for your project:
```
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/guides-translation.md).
For details on how to set up documentation search, read [here](/docs/en/guides-search.md).
React documentation is [? licensed](./LICENSE-docs).

49
docs/getting-started-publish.md Normal file
View file

@ -0,0 +1,49 @@
---
id: publish
title: Publishing Your Website
---
## Automatically Publish Your Website with Circle
You can use CircleCI to publish your website whenever your project repo is updated. Configure your circle.yml file in your project repo to run commands to publish to GitHub Pages. An example is shown here:
```yaml
machine:
node:
version: 6.10.3
npm:
version: 3.10.10
test:
override:
- "true"
deployment:
website:
branch: master
commands:
- git config --global user.email "test-site-bot@users.noreply.github.com"
- git config --global user.name "Website Deployment Script"
- echo "machine github.com login test-site-bot password $GITHUB_TOKEN" > ~/.netrc
- cd website && npm install && GIT_USER=test-site-bot npm run publish-gh-pages
```
Note that in this case a GitHub user `test-site-bot` is created to use just for publishing. Make sure to give your Git user push permissions for your project and to set a GITHUB_TOKEN environment variable in Circle.
If you wish to manually publish your website with the `publish-gh-pages` script, run the following example command with the appropriate variables for your project:
```
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
```
## Manually Publishing Your Website
Docusaurus can generate all related HTML, JavaScript, CSS, and image assets.
Run the command:
`yarn run build`
All corresponding files will be placed in a `build` folder inside your Docusaurus project folder.
From here you can copy the folder, or write a script to deploy where you wish.

227
docs/getting-started.md
View file

@ -1,227 +0,0 @@
---
---
## Getting Started
### Project Structure
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.
Example project structure:
```
project-repo/
blog/
2017-05-06-blog-post.md
docs/
en/
doc1.md
website/
```
### Installation
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"
}
}
```
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
```
or
```
yarn run examples
```
This will create the following files/folders in your website folder:
```
core/Footer.js
pages/...
static/img/...
siteConfig.js
```
It will also create two folders in the level above the website folder in your project repo:
```
blog-examples-from-docusaurus
docs-examples-from-docusaurus
```
If any of the files created by `yarn run examples` already exists, Docusaurus will not overwrite them.
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 `blog-examples-from-docusaurus` folder contains examples of blog posts written in markdown.
The `docs-examples-from-docusaurus` 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.
You will need to keep the `siteConfig.js` and `core/Footer.js` files, but may edit them as you wish.
You should keep the `pages` and `static` folders, but may change the content inside them as you wish. At the bare minimum you should have an `en/index.js` or `en/index.html` file inside `pages` and an image to use as your header icon inside `static`.
The `blog-examples-from-docusaurus` and `docs-examples-from-docusaurus` folders contain example blog and document markdown files. If you wish to run Docusaurus with these files, you need to rename the folders to `blog` and `docs`, respectively.
### 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. You can also refer [here](/docs/en/site-configuration.md) for more details.
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 each `.js` file in `pages` 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.
- Any files in `pages/en` will also be copied into `pages` when the server is run and when the site is statically built. i.e. Putting a file in `pages/en/index.js` will make it available at `/en/index.html` and `/index.html`.
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.
A React component placed in `website/pages/en/index.js` will be available at the url `/en/index.html`. A static html page placed in `website/pages/en/index.html` will be available at the url `/en/index.html`. Provided html files will override provided React components.
A static asset placed in `website/static/img/image.png` will be available at the url `/img/image.png`.
Example:
```
localhost:3000${baseUrl}en/index.html
localhost:3000${baseUrl}img/image.png
${url}${baseUrl}en/index.html
${url}${baseUrl}img/image.png
```
### Document and Blog Front Matters
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 -->
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 -->
<!-- don't include next if this is the last doc; don't include previous if first doc -->
---
```
Blog posts should be written as markdown files with the following front matter:
```
---
title: Blog Post Title
author: Author Name
authorURL: http://twitter.com/author <!-- (or some other link) -->
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`.
## Using Docusaurus
### Run the Server
To run your website locally run the script:
```
npm run start
```
or
```
yarn run start
```
This will start a server hosting your website locally at `localhost:3000`. 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 by using a `--port` flag:
```
npm run start -- --port 9000
```
### Build Static Pages
To create a static build of your website, run the script:
```
npm run build
```
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
Use CircleCI to publish your website whenever your project repo is updated. Configure your circle.yml file in your project repo to run commands to publish to GitHub Pages. An example is shown here:
```yaml
machine:
node:
version: 6.10.3
npm:
version: 3.10.10
test:
override:
- "true"
deployment:
website:
branch: master
commands:
- git config --global user.email "test-site-bot@users.noreply.github.com"
- git config --global user.name "Website Deployment Script"
- echo "machine github.com login test-site-bot password $GITHUB_TOKEN" > ~/.netrc
- cd website && npm install && GIT_USER=test-site-bot npm run publish-gh-pages
```
Note that in this case a GitHub user `test-site-bot` is created to use just for publishing. Make sure to give your Git user push permissions for your project and to set a GITHUB_TOKEN environment variable in Circle if you choose to publish this way.
If you wish to manually publish your website with the `publish-gh-pages` script, run the following example command with the appropriate variables for your project:
```
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](translation.md).
For details on how to set up documentation search, read [here](search.md).

2
website/i18n/en.json
View file

@ -9,8 +9,8 @@
"site-config": "siteConfig.js",
"installation": "Installation",
"site-preparation": "Site Preparation",
"publish": "Publishing Your Website",
"site-creation": "Creating your site",
"getting-started": "getting-started",
"blog": "Adding a Blog",
"custom-pages": "Custom Pages",
"navigation": "Navigation and Sidebars",

2
website/package.json
View file

@ -11,6 +11,6 @@
"crowdin-download": "crowdin-cli --config ../crowdin.yaml download -b master"
},
"dependencies": {
"docusaurus": "^1.0.0-alpha.35"
"docusaurus": "^1.0.0-alpha.41"
}
}

8
website/sidebars.json
View file

@ -4,6 +4,7 @@
"installation",
"site-preparation",
"site-creation",
"publish",
"publishing"
],
"Guides": [
@ -14,11 +15,6 @@
"search",
"versioning"
],
"API": [
"commands",
"api-pages",
"site-config",
"doc-markdown"
]
"API": ["commands", "api-pages", "site-config", "doc-markdown"]
}
}