3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-07-24 03:58:49 +02:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'master' of https://github.com/facebookexperimental/Docusaurus into new-docs

Browse source
This commit is contained in:
Frank Li 2017-08-08 13:56:55 -07:00
commit c182a96be9
31 changed files with 1098 additions and 233 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/doc-markdown.md
View file

@ -1,6 +1,6 @@
---
id: doc-markdown
title: Documentation Markdown Features
title: Markdown Features
---
Docusaurus supports some extra features when writing documentation in markdown.

32
docs/getting-started-installation.md Normal file
View file

@ -0,0 +1,32 @@
---
id: installation
title: Installation
---
Docusaurus was designed from the ground up to be easily installed and used to get your website up an running quickly. To install Docusaurus, follow these steps:
1. Create a `website` folder in the root of your GitHub repo.
1. `cd website`
1. Create a `package.json` file with the following scripts that will be used when developing documentation with Docusaurus:
```json
{
"scripts": {
"start": "docusaurus-start",
"build": "docusaurus-build",
"publish-gh-pages": "docusaurus-publish",
"examples": "docusaurus-examples"
}
}
```
1. Install Docusaurus with `yarn` or `npm`
```
yarn add docusaurus -dev
```
or
```
npm install --save-dev docusaurus
```

69
docs/getting-started-preparation.md Normal file
View file

@ -0,0 +1,69 @@
---
id: site-preparation
title: Site Preparation
---
After [installing Docusaurus](./getting-started-installation.md), you will want to install and run the example site included. This serves dual purposes.
1. Verifying that Docusaurus was installed correctly.
1. Providing you the skeleton to create your site.
## Verifying Installation
1. Generate the files for the example site by running `examples` using `yarn` or `npm`.
```
npm run examples
```
or
```
yarn run examples
```
> If any of the files created by `[yarn | npm] run examples` already exists, Docusaurus will not overwrite them.
1. Run the server.
```
npm run start
```
or
```
yarn run start
```
1. Load the example site at http://localhost:3000. You should see the example site loaded in your web browser.
## Example Site Configuration
Loading the example site will create the following files/folders:
```
website/core/Footer.js
website/pages/...
website/static/img/...
website/siteConfig.js
website/blog-examples-from-docusaurus/...
docs-examples-from-docusaurus/...
```
> The `docs-examples-from-docusaurus` folder will be at the same directory level as `website`, not in it.
The provided example files contain configurations that can be used as starting points for your site:
- The `website/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 `website/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 `website/pages` folder contains example top-level pages for the site.
- The `website/static` folder contains static assets used by the example site.
- The `website/siteConfig.js` file is the main configuration file used by Docusaurus.
You will need to keep the `website/siteConfig.js` and `website/core/Footer.js` files, but may edit them as you wish.
You should keep the `website/pages` and `website/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 `website/pages` and an image to use as your header icon inside `website/static`.
The `website/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 `website/blog` and `docs`, respectively.

52
docs/getting-started-site-creation.md Normal file
View file

@ -0,0 +1,52 @@
---
id: site-creation
title: Creating your site
---
Docusaurus' primary purpose of existence is to make it super simple for you to create documentation for your project and have a site to house those docs.
After [installation](./getting-started-installation.md) and [preparation](./getting-started-preparation.md), much of the work to create a basic site for your docs is already complete.
## Load the Example Site
[Preparation](./getting-started-preparation.md) created a sample site for you to see Docusaurus in action. However, it also provided the infrastructure that will be used as you are developing your own site.
## Site Structure
After loading the example site, you should see a structure in your repo that looks similar to:
```
project-repo/
blog/
2017-05-06-blog-post.md
docs/
en/
doc1.md
website/
blog/
2017-05-06-blog-post.md
```
All of your documentation files should be placed inside the `docs` folder as markdown `.md` files. Any blog posts should be inside the `blog` folder.
> The blog posts must be formatted as yyyy-mm-dd-your-file-name.md
## Create Your Basic Site
To create a fully functional site, you only need to do a few steps:
1. Add your documentation to the `/docs` folder as `.md` files, ensuring you have the proper [header](LINK HERE) in each file.
1. Add zero or more docs to the [`sidebars.json`](LINK HERE) file so that your documentation is rendered in a sidebar, if you choose them to be.
> If you do not add your documentation to the `sidebars.json` file, the docs will be rendered, but they can only be linked to from other documentation and visited with the known URL.
1. Modify the `website/siteConfig.js` file to [configure your site](LINK_HERE), following the comments included in that file to guide you.
1. [Customize](LINK_HERE_TO_CUSTOMIZATION) the `website/core/Footer.js` file that provides the footer for your site.
1. Place assets, such as images, in the `website/static/` folder.
1. Run the site to see the results of your changes.
```
cd website
yarn run start # or - npm run start
# navigate to http://localhost:3000
```

9
docs/getting-started.md
View file

@ -1,8 +1,3 @@
---
id: getting-started
title: Docusaurus
---
## Getting Started
### Project Structure
@ -226,5 +221,5 @@ DEPLOY_USER=deltice GIT_USER=test-site-bot CIRCLE_PROJECT_USERNAME=deltice CIRCL
## 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).
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).

115
docs/guides-navigation.md Normal file
View file

@ -0,0 +1,115 @@
---
id: navigation
title: Navigation and Sidebars
---
## New Hidden Docs
New markdown files within `docs` will show up as pages on the website. Creating a file such as "docs/getting-started.md" will enable the new page `/docs/getting-started.html`.
To change the id (link name) of the file, set the `id` field in the markdown header. At the top of `getting-started.md`:
```
---
id: intro
title: Getting Started
---
My *new content* here..
```
Now, the doc can be accessed from `/docs/intro.html`.
## Adding Docs to a Sidebar
Now we want our new page to show up on the sidebar. We configure the order of the sidebar in `website/sidebars.json`.
Within `sidebars.json`, add the doc ID within an existing sidebar/category:
```
{
"docs": {
"Getting Started": [
"getting-started"
```
Or you can create a new category within the sidebar:
```
{
"docs": {
...
"My New Sidebar Category": [
"getting-started"
],
...
```
## New Hidden Sections
You can also put the doc in a new sidebar. In this case we are creating a `intro` section within `sidebars.json`.
```
{
"intro": {
"My Sidebar Category": [
"getting-started"
],
},
...
```
Keep in mind, until you add the section to the nav bar (below), this new "intro" section of the site will be hidden with no links going to it.
## Adding doc to site nav bar
After creating a new section of the site by adding to `sidebars.json`, you can link to the new doc from the top navigation bar by editing the `headerLinks` field of `siteConfig.js`.
```
headerLinks: [
...
{doc: 'intro', label: 'Getting Started'},
...
],
```
## Custom page links in nav bar
To add custom pages to the navigation bar, entries can be added to the `headerLinks` of `siteConfig.js`. For example, if we have a page within `website/pages/help.js`, we can link to it by adding the following:
```
headerLinks: [
...
{page: 'help', label: 'Help'},
...
],
```
## External links in nav bar
Custom links can be added to the nav bar with the following entry in `siteConfig.js`:
```
headerLinks: [
...
{href: 'https://github.com/facebookexperimental/Docusaurus', label: 'GitHub'},
...
],
```
To open external links in a new tab, provide an `external: true` flag within the header link config.
## Search bar position in nav bar
If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the `headerLinks` config array:
```
headerLinks: [
{doc: 'foo', label: 'Foo'},
{search: true},
{doc: 'bar', label: 'Bar'},
],
```

47
docs/guides-search.md Normal file
View file

@ -0,0 +1,47 @@
---
id: search
title: Enabling Search
---
Docusaurus supports search using [Algolia DocSearch](https://community.algolia.com/docsearch/). Once you have set up your site, [enter your site information](https://community.algolia.com/docsearch/) to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.
### Enabling the Search Bar
Enter your search-only API key and index name into `siteConfig.js` in the `algolia` section to enable search for your site.
```js
const siteConfig = {
...
algolia: {
apiKey: "my-search-only-api-key-1234",
indexName: "my-index-name"
},
...
}
```
### Controlling the Location of the Search Bar
By default, the search bar will be the rightmost element in the top navigation bar.
If you want to change the default location, add the `searchBar` flag in the `headerLinks` field of `siteConfig.js` in your desired location. For example, you may want the search bar in between your internal and external links.
```js
const siteConfig = {
...
headerLinks: [
{...}
{...}
{ search: true }
{...}
{...}
],
...
}
```
### Disabling the Search Bar
To disable the search bar, comment out (recommended) or delete the `algolia` section in the `siteConfig.js` file.
Also, if you have customized the location of the search bar in `headerLinks`, set `search: false`.

22
docs/search.md
View file

@ -1,22 +0,0 @@
---
id: search
title: Documentation Search
---
## Algolia Search Integration
Docusaurus supports search using [Algolia DocSearch](https://community.algolia.com/docsearch/). Once you have set up your site, you can use the link above to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.
Enter your search-only API key and index name into `siteConfig.js` in the `algolia` section to enable search for your site. The search bar will be in the header navigation bar in between internal links and external links. To disable the search bar, delete the `algolia` section in the `siteConfig.js` file.
```js
const siteConfig = {
...
algolia: {
apiKey: "my-search-only-api-key-1234",
indexName: "my-index-name"
},
...
}
```

5
docs/site-config.md
View file

@ -1,6 +1,6 @@
---
id: site-config
title: Customizing siteConfig
title: siteConfig.js
---
A large part of site configuration is done by editing the `siteConfig.js` file.
@ -122,10 +122,9 @@ const siteConfig = {
"0f9f28b9ab9efae89810921a351753b5",
indexName: "github"
}
gaTrackingId: "U-A2352"
gaTrackingId: "U-A2352"
};
module.exports = siteConfig;
```

2
docs/translation.md
View file

@ -1,6 +1,6 @@
---
id: translation
title: Translations with Docusaurus
title: Translations
---
## Overview