mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-06 04:42:40 +02:00
Add and update documentation (#23)
* Add and update documentation * Update documentation * Update site config doc
This commit is contained in:
Frank Li
Joel Marcey
parent
4cbada5350
commit
f309be78aa
4 changed files with 222 additions and 19 deletions
49
docs/en/doc-markdown.md
Normal file
49
docs/en/doc-markdown.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
id: doc-markdown
|
||||
title: Documentation Markdown Features
|
||||
layout: docs
|
||||
category: Docusaurus
|
||||
permalink: docs/en/doc-markdown.html
|
||||
previous: site-config
|
||||
next: translation
|
||||
---
|
||||
|
||||
Docusaurus supports some extra features when writing documentation in markdown.
|
||||
|
||||
### Linking other Documents
|
||||
|
||||
You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.
|
||||
|
||||
Example:
|
||||
```
|
||||
[This links to another document](/docs/en/other-document.md)
|
||||
```
|
||||
If the permalink in the header of `other-document.md` is `/docs/en/other-document.html`, this markdown will automatically get converted into a link to `/docs/en/other-document.html` once it gets rendered.
|
||||
|
||||
This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.
|
||||
|
||||
### Generating Table of Contents
|
||||
|
||||
You can make an autogenerated list of links, which can be useful as a table of contents for API docs.
|
||||
|
||||
In your markdown file, insert a line with the text <`AUTOGENERATED_TABLE_OF_CONTENTS>`. Write your documentation using `h3` headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <`AUTOGENERATED_TABLE_OF_CONTENTS>`.
|
||||
|
||||
Example:
|
||||
```
|
||||
### `docusaurus.function(a, b)`
|
||||
|
||||
Text describing my function
|
||||
|
||||
|
||||
### `docdoc(file)`
|
||||
|
||||
Text describing my function
|
||||
```
|
||||
|
||||
will lead to a table of contents of the functions:
|
||||
|
||||
```
|
||||
- `docusaurus.function(a, b)`
|
||||
- `docdoc(file)`
|
||||
```
|
||||
and each function will link to their corresponding sections in the page.
|
||||
|
|
@ -3,8 +3,8 @@ id: getting-started
|
|||
title: Docusaurus
|
||||
layout: docs
|
||||
category: Docusaurus
|
||||
permalink: docs/en/doc1.html
|
||||
next: translation
|
||||
permalink: docs/en/getting-started.html
|
||||
next: site-config
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
|
@ -72,36 +72,62 @@ 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.
|
||||
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 `example-blog` folder contains examples of blog posts written in markdown.
|
||||
The `example-docs` folder contains example documentation files written in markdown.
|
||||
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.
|
||||
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 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.
|
||||
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:
|
||||
|
|
@ -147,7 +173,8 @@ 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:
|
||||
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
|
||||
```
|
||||
|
|
|
|||
127
docs/en/site-config.md
Normal file
127
docs/en/site-config.md
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
---
|
||||
id: site-config
|
||||
title: Customizing siteConfig
|
||||
layout: docs
|
||||
category: Docusaurus
|
||||
permalink: docs/en/site-config.html
|
||||
previous: getting-started
|
||||
next: doc-markdown
|
||||
---
|
||||
|
||||
A large part of site configuration is done by editing the `siteConfig.js` file.
|
||||
|
||||
## User Showcase
|
||||
|
||||
The `users` array is used to store objects for each project/user that you want to show on your site. Currently this field is used by example the `pages/en/index.js` and `pages/en/users.js` files provided. Each user object should have `caption`, `image`, `infoLink`, and `pinned` fields. The `caption` is the text showed when someone hovers over the `image` of that user, and the `infoLink` is where clicking the image will bring someon. The `pinned` field determines whether or not it shows up on the `index` page.
|
||||
|
||||
Currently this `users` array is used only by the `index.js` and `users.js` example files. If you do not wish to have a users page or show users on the `index` page, you may remove this section.
|
||||
|
||||
## siteConfig Fields
|
||||
|
||||
The `siteConfig` object contains the bulk of the configuration settings for your website.
|
||||
|
||||
### Mandatory Fields
|
||||
|
||||
`title` - Title for your website.
|
||||
|
||||
`tagline` - Tagline for your website.
|
||||
|
||||
`url` - url for your site.
|
||||
|
||||
`baseUrl` - baseUrl for your site.
|
||||
|
||||
`projectName` - Project name.
|
||||
|
||||
`headerLinksInternal` - Header links for targets on this site. `'LANGUAGE'` will be replaced by whatever language the page is for, for example, `'en'`.
|
||||
|
||||
`headerLinksExternal` - Header links for targets outside this site.
|
||||
|
||||
`headerIcon` - url for icon used in header navigation bar.
|
||||
|
||||
`favicon` - url for site favicon.
|
||||
|
||||
`colors` - Simple color configurations for the site. `primaryColor` is the color used the header navigation bar and sidebars. `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile). `prismColor` is the color used in the background of syntax highlighting for code in documentation. It is recommended to be the same color as `primaryColor` in `rgba` form with an alpha value of `0.03`.
|
||||
|
||||
### Optional Fields
|
||||
|
||||
`editUrl` - url for editing docs, usage example: `editUrl + 'en/doc1.md'`. If this field is omitted, there will be no "Edit this Doc" button for each document.
|
||||
|
||||
`users` - The `users` array mentioned earlier.
|
||||
|
||||
`disableHeaderTitle` - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to `true`.
|
||||
|
||||
`footerIcon` - url for a footer icon. Currently used in the `core/Footer.js` file provided as an example, but it can be removed from that file.
|
||||
|
||||
`recruitingLink` - url for the `Help Translate` tab of language selection when languages besides English are enabled. This can be included you are using translations but does not have to be.
|
||||
|
||||
`algolia` - Information for Algolia search integration. If this field is excluded, the search bar will not appear in the header.
|
||||
|
||||
`gaTrackingId` - Google Analytics tracking ID to track page views.
|
||||
|
||||
## Example siteConfig.js with all fields
|
||||
|
||||
```
|
||||
const users = [
|
||||
{
|
||||
caption: "User1",
|
||||
image: "/test-site/img/docusaurus.svg",
|
||||
infoLink: "https://www.example.com",
|
||||
pinned: true
|
||||
}
|
||||
];
|
||||
|
||||
const siteConfig = {
|
||||
title: "Docusaurus",
|
||||
tagline: "Generate websites!",
|
||||
url: "https://deltice.github.io",
|
||||
// url: "https://www.example.com",
|
||||
baseUrl: "/test-site/",
|
||||
// baseUrl: "/",
|
||||
projectName: "docusaurus",
|
||||
headerLinksInternal: [
|
||||
{
|
||||
section: "docs",
|
||||
href: "/test-site/docs/LANGUAGE/doc1.html",
|
||||
text: "Docs"
|
||||
},
|
||||
{ section: "api", href: "/test-site/docs/LANGUAGE/doc4.html", text: "API" },
|
||||
{ section: "help", href: "/test-site/LANGUAGE/help.html", text: "Help" },
|
||||
{ section: "blog", href: "/test-site/blog", text: "Blog" }
|
||||
],
|
||||
// headerLinksInternal: [],
|
||||
headerLinksExternal: [
|
||||
{
|
||||
section: "github",
|
||||
href: "https://github.com/deltice/test-site",
|
||||
text: "GitHub"
|
||||
}
|
||||
],
|
||||
// headerLinksExternal: [],
|
||||
headerIcon: "img/docusaurus.svg",
|
||||
favicon: "img/favicon.png",
|
||||
colors: {
|
||||
primaryColor: "#2E8555",
|
||||
secondaryColor: "#205C3B",
|
||||
prismColor:
|
||||
"rgba(46, 133, 85, 0.03)"
|
||||
},
|
||||
|
||||
|
||||
editUrl: "https://github.com/deltice/test-site/edit/master/docs/",
|
||||
users,
|
||||
disableHeaderTitle: true,
|
||||
footerIcon: "img/docusaurus.svg",
|
||||
recruitingLink:
|
||||
"https://crowdin.com/project/docusaurus",
|
||||
algolia: {
|
||||
apiKey:
|
||||
"0f9f28b9ab9efae89810921a351753b5",
|
||||
indexName: "github"
|
||||
}
|
||||
gaTrackingId: "U-A2352"
|
||||
};
|
||||
|
||||
module.exports = siteConfig;
|
||||
|
||||
```
|
||||
|
||||
|
|
@ -4,7 +4,7 @@ title: Translations with Docusaurus
|
|||
layout: docs
|
||||
category: Docusaurus
|
||||
permalink: docs/en/translation.html
|
||||
previous: getting-started
|
||||
previous: doc-markdown
|
||||
next: search
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue