3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-07-23 19:48:54 +02:00
Code Issues Projects Releases Packages Wiki Activity

Add initial documentation

Browse source
This commit is contained in:
Frank Li 2017-07-11 15:17:47 -07:00
parent ef5c4f83a2
commit 429aa636d0
3 changed files with 335 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

194
docs/en/getting-started.md Normal file
View file

@ -0,0 +1,194 @@
---
id: getting-started
title: Docusaurus
layout: docs
category: Docusaurus
permalink: docs/en/doc1.html
next: translation
---
## 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.
### 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
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.
### 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.
For more details on how Docusaurus functions, read here.

26
docs/en/search.md Normal file
View file

@ -0,0 +1,26 @@
---
id: search
title: Documentation Search
layout: docs
category: Docusaurus
permalink: docs/en/search.html
previous: translation
---
## 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"
},
...
}
```

115
docs/en/translation.md Normal file
View file

@ -0,0 +1,115 @@
---
id: translation
title: Translations with Docusaurus
layout: docs
category: Docusaurus
permalink: docs/en/translation.html
previous: getting-started
next: search
---
## Overview
Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users. Top-level pages written with English strings can be easily translated by wrapping any strings you want to translate in a `<translate>` tag. Strings found in the site header and in documentation front matter will also be found by Docusaurus and properly translated. Read on for more details.
## Docusaurus Translation Configurations
To generate example files for translations with Docusuaurus, run the `examples` script with the command line argument `translations`:
```
npm run examples translations
```
This will create the following files in your website folder:
```
pages/en/help-with-translations.js
languages.js
crowdin.yaml
```
The `pages/en/help-with-translations.js` file is the same example help page generated by the `examples` script but now using translations tags that are described below.
The `languages.js` file tells Docusaurus what languages you want to enable for your site.
The `crowdin.yaml` file is used to configure crowdin integration, and should be moved out one level into your project repo.
## How Docusaurus Finds Strings to Translate
Add the following script to your package.json file:
```json
...
"scripts": {
...
"write-translations": "docusaurus-write-translations"
},
...
```
Running the script will generate an `i18n/en.json` file containing all the strings that will be translated from English into other languages.
The script will include text from the following places:
- title strings and category strings in documentation front matter
- tagline in `siteConfig.js`
- internal and external header link text strings in `siteConfig.js`
It will also include any strings in any `.js` files in the `pages` folder that are wrapped in a `<translate>` tag. You can also include an optional description attribute to give more context to a translator about how to translate the string.
In addition to these strings in the `i18n/en.json` file, the whole documentation files themselves will be translated.
## How Docusaurus Translates Strings
Docusaurus itself does not do any translation from one language to another. Instead, it uses Crowdin to manage translations and then downloads appropriately translated files from Crowdin. More information on how to set up Crowdin translations later.
## How Docusaurus Uses String Translations
This section provides some more context for how translation works, but is not necessary information for the user to know.
For things like the strings found in the headers and sidebars of pages, Docusaurus references a translated version of `i18n/en.json` (for example, a `i18n/fr.json` file downloaded from Crowdin).
For documentation text itself, fully translated markdown files will be compiled in the same way English documentation markdown files would be.
For other pages, Docusaurus will automatically transform all `<translate>` tags into function calls that will return appropriately translated strings. For each language that is enabled with `languages.js`, Docusaurus will build translated pages using the files in `pages/en` and the language's respective `.json` file in `i18n`.
## Crowdin Set-Up
Create your translation project on [Crowdin](https://www.crowdin.com/). You can use [Crowdin's guides](https://support.crowdin.com/translation-process-overview/) to learn more about the translations work flow.
To automatically get the translations for your files, update the `circle.yml` file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example `circle.yml` file:
```yaml
machine:
node:
version: 6.10.3
npm:
version: 3.10.10
test:
override:
- "true"
deployment:
website:
branch: master
commands:
# configure git user
- 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
# install Docusaurus and generate file of English strings
- cd website && npm install && npm run write-translations && cd ..
# crowdin install
- sudo apt-get install default-jre
- wget https://artifacts.crowdin.com/repo/deb/crowdin.deb -O crowdin.deb
- sudo dpkg -i crowdin.deb
# translations upload/download
- crowdin --config crowdin.yaml upload sources --auto-update -b master
- crowdin --config crowdin.yaml download -b master
# build and publish website
- cd website && GIT_USER=test-site-bot npm run publish-gh-pages
```
The `crowdin` command uses the `crowdin.yaml` file generated with the `examples` script. It should be placed in your project directory to configure how and what files are uploaded/downloaded.
Note that in the `crowdin.yaml` file, `CROWDIN_PROJECT_ID` and `CROWDIN_API_KEY` are environment variables set-up in Circle for your Crowdin project. They can be found in your Crowdin project settings.
Now, Circle will help you automatically get translations prior to building your website. If you wish to use crowdin on your machine locally, you can install the [Crowdin CLI tool](https://support.crowdin.com/cli-tool/) and run the same commands found in the `circle.yaml` file, making sure you actually set the `project_identifier` and `api_key`.