facebook · neilsutcliffe · Dec 22, 2017 · Dec 22, 2017 · Dec 22, 2017 · Dec 23, 2017
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -48,30 +48,31 @@ jobs:
           name: Test Static Website Builds
           command: cd website && yarn run build
 
+  # The CIRCLE_ variables are defined during the CircleCI build process
+  # https://circleci.com/docs/1.0/environment-variables/
   deploy-website:
     <<: *defaults
     steps:
-      - add_ssh_keys:
-          fingerprints:
-            - "1e:fe:54:96:06:6e:aa:42:07:bf:8e:1f:24:3b:24:30"
       - checkout
       - restore-cache: *restore-yarn-cache
       - run: *yarn
       - save-cache: *save-yarn-cache
       - run:
           name: Configure GitHub Bot
+          # Do not do this if we don't have the right org (facebook), or if this is just a pull request
           command: |
             if [[ $CIRCLE_PROJECT_USERNAME == "facebook" && -z $CI_PULL_REQUEST && -z $CIRCLE_PR_USERNAME ]]; then
-              git config --global user.email "docusaurus@users.noreply.github.com"
+              git config --global user.email "docusaurus-bot@users.noreply.github.com"
               git config --global user.name "Website Deployment Script"
-              echo "machine github.com login facebook-github-bot" > ~/.netrc
+              echo "machine github.com login docusaurus-bot password $DOCUSAURUS_PUBLISH_TOKEN" > ~/.netrc
             fi
       - run:
           name: Deploy Website
+          # Skip the deploy if we don't have the right org (facebook), or if this is just a pull request
           command: |
             if [[ $CIRCLE_PROJECT_USERNAME == "facebook" && -z $CI_PULL_REQUEST && -z $CIRCLE_PR_USERNAME ]]; then
               echo "Deploying website..."
-              cd website && GIT_USER=facebook-github-bot USE_SSH=true yarn run publish-gh-pages
+              cd website && GIT_USER=docusaurus-bot USE_SSH=false yarn run publish-gh-pages
             else
               echo "Skipping deploy."
             fi

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,54 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [1.0.5] - 2018-01-09
+
+This is a targeted bug fix release, with some documentation updates and Docusaurus repo housekeeping in between. Total commits in this release is 13, including the release itself.
+
+### Breaking Changes
+
+N/A
+
+### Added
+
+N/A
+
+### Fixed/Changed
+
+- Docusaurus builds on Windows ([PR #381](https://github.com/facebook/Docusaurus/pull/381), thanks @qcz).
+- Fixed publishing for user/org GitHub sites (as opposed to project sites) ([PR #384](https://github.com/facebook/Docusaurus/pull/384)).
+- Clarification and updates on the publishing and API documentation ([PR #372](https://github.com/facebook/Docusaurus/pull/372)).
+
+### Removed
+
+N/A
+
+## [1.0.4] - 2017-12-27
+
+This is generally a bug fix release, with some code refactoring. Total commits in this release is 58.
+
+### Breaking Changes
+
+- ***Most users may not run into this problem, but we think it can technically be a breaking change***. PR #322 (original PR #316) and friends changes the way we check for the existence of translations and versioning. Part of that is that we allow for the possibility of an empty language prop, instead of defaulting everything to English. When running 1.0.4, check to make sure your `index.js` works as expected. See [this comment](https://github.com/facebook/Docusaurus/pull/322#issuecomment-352914064) and those below for discussion on this. There is still a bit more work to be done (refactoring and maybe adding a `defaultLang` config option) to make this as clean as possible.
+
+### Added
+
+- `lang` property added on `html` tag, if a language exists and is set (PR #295).
+- Added the `wrapPagesHTML` configuration option (PR #332).
+- Some adming docs on how to debug with VSCode (PR #335).
+- Added docs for the `useEnglishURL` configuration option.
+
+### Fixed/Changed
+
+- Links on landing page in `docusaurus-init` test site do not 404 any longer.
+- Refactoring how we check for translations and versioning (PRs #322/#316 and friends).
+- Refactored the example `index.js` page (PR #293).
+- Link errors, typos and grammatical errors in the docusuarus.io documentation.
+
+### Removed
+
+N/A
+
 ## [1.0.3] - 2017-12-13
 ### Added
 - Docusaurus [released](http://docusaurus.io/blog/2017/12/14/introducing-docusaurus.html) to the public.
@@ -16,4 +64,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   - Blog
   - Documentation
 
-[Unreleased]: https://github.com/facebook/Docusaurus/compare/v1.0.3...HEAD
+[Unreleased]: https://github.com/facebook/Docusaurus/compare/v1.0.5...HEAD
+[1.0.5]: https://github.com/facebook/Docusaurus/compare/v1.0.4...v1.0.5
+[1.0.4]: https://github.com/facebook/Docusaurus/compare/v1.0.3...v1.0.4
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -18,6 +18,10 @@ There are many ways to contribute to Docusaurus, and many of them do not involve
 
 Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at [@docusaurus](https://twitter.com/docusaurus) and let us know you are looking for a bit of help.
 
+### Join our Discord Channel
+
+We have `#docusaurus-dev` on [Discord](https://discord.gg/docusaurus) to discuss all things Docusaurus development.
+
 ### Triaging issues and pull requests
 
 One great way you can contribute to the project without writing any code is to help triage issues and pull requests as they come in.

diff --git a/README.md b/README.md
@@ -28,7 +28,17 @@ Read our [contributing guide](https://github.com/facebook/Docusaurus/blob/master
 
 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/facebook/Docusaurus/labels/good%20first%20issue) that contain bugs which are fairly easy to fix. This is a great place to get started.
 
-### License
+## Contact
+
+We have a few channels for contact:
+
+- [Discord](https://discord.gg/docusaurus) with two text channels:
+  - `#docusaurus-users` for those using Docusaurus.
+  - `#docusaurus-dev` for those wanting to contribute to the Docusaurus core.
+- [@docusaurus](https://twitter.com/docusaurus) on Twitter
+- [GitHub Issues](https://github.com/facebook/docusaurus/issues)
+
+## License
 
 Docusaurus is [MIT licensed](./LICENSE).
 

diff --git a/crowdin.yaml b/crowdin.yaml
@@ -41,8 +41,8 @@ files:
         'tr': 'tr'
         'uk': 'uk'
         'vi': 'vi'
-        'zh-CN': 'zh-Hans'
-        'zh-TW': 'zh-Hant'
+        'zh-CN': 'zh-CN'
+        'zh-TW': 'zh-TW'
   -
     source: '/website/i18n/en.json'
     translation: '/website/i18n/%locale%.json'

diff --git a/docs/api-commands.md b/docs/api-commands.md
@@ -74,11 +74,26 @@ Alias: `publish-gh-pages`
 
 [Builds](api-commands.md#docusaurus-build), then deploys the static website to GitHub Pages. This command is meant to be run during the deployment step in Circle CI, and therefore expects a few environment variables to be defined:
 
+The following is generally set manually by the user in the CircleCI `config.yml` file.
+
  - `GIT_USER`: The git user to be associated with the deploy commit.
+ - `USE_SSH`: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
+
+ e.g.,
+
+ ```bash
+ GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
+ ```
+
+The following are set by the [CircleCI environment](https://circleci.com/docs/1.0/environment-variables/) during the build process.
+
  - `CIRCLE_BRANCH`: The git branch associated with the commit that triggered the CI run.
+ - `CI_PULL_REQUEST`: Expected to be truthy if the current CI run was triggered by a commit in a pull request.
+
+The following should be set by you in `siteConfig.js` as `organizationName` and `projectName`, respectively. If they are not set in your site configuration, they fall back to the [CircleCI environment](https://circleci.com/docs/1.0/environment-variables/).
+
  - `CIRCLE_PROJECT_USERNAME`: The GitHub username or organization name that hosts the git repo, e.g. "facebook".
  - `CIRCLE_PROJECT_REPONAME`: The name of the git repo, e.g. "Docusaurus".
- - `CI_PULL_REQUEST`: Expected to be truthy if the current CI run was triggered by a commit in a pull request.
 
 You can learn more about configuring automatic deployments with CircleCI in the [Publishing guide](getting-started-publishing.md).
 

diff --git a/docs/api-site-config.md b/docs/api-site-config.md
@@ -19,7 +19,7 @@ The `siteConfig` object contains the bulk of the configuration settings for your
 
 `title` - Title for your website.
 
-`tagline` - Tagline for your website.  
+`tagline` - Tagline for your website.
 
 `url` - url for your site.
 
@@ -71,6 +71,32 @@ customDocsPath: "docs/site"
 ```js
 customDocsPath: "website-docs"
 ```
+
+`fonts` - Font-family css configuration for the site. If a font family is specified in `siteConfig.js` as `$myFont`, then adding a `myFont` key to an array in `fonts` will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.
+
+In the below example, we have two sets of font configurations, `myFont` and `myOtherFont`. `Times New Roman` is the preferred font in `myFont`. `-apple-system` is the preferred in `myOtherFont`.
+
+```
+fonts: {
+  myFont: [
+    "Times New Roman",
+    "Serif"
+  ],
+  myOtherFont: [
+    "-apple-system",
+    "system-ui"
+  ]
+},
+```
+
+The above fonts would be represented in your CSS file(s) as variables `$myFont` and `$myOtherFont`.
+
+```
+h1 {
+  font-family: $myFont;
+}
+```
+
 `useEnglishUrl` - If you do not have [translations](guides-translation.md) enabled (e.g., by having a `languages.js` file), but still want a link of the form `/docs/en/doc.html` (with the `en`), set this to `true`.
 
 `organizationName` - GitHub username of the organization or user hosting this project. This is used by the publishing script to determine where your GitHub pages website will be hosted.
@@ -99,9 +125,10 @@ customDocsPath: "website-docs"
 
 `highlight` - [Syntax highlighting](api-doc-markdown.md) options:
 
- - `theme` is the name of the theme used by Highlight.js when highlighting code.
+ - `theme` is the name of the theme used by Highlight.js when highlighting code. You can find the [list of supported themes here](https://github.com/isagalaev/highlight.js/tree/master/src/styles).
  - `version` specifies a particular version of Highlight.js to be used.
  - `hljs` provides an escape valve by passing an instance of Highlight.js to the function specified here, allowing additional languages to be registered for syntax highlighting.
+ - `defaultLang` defines a default language. It will be used if one is not specified at the top of the code block. You can find the [list of supported languages here](https://github.com/isagalaev/highlight.js/tree/master/src/languages).
 
 `markdownPlugins` - An array of plugins to be loaded by Remarkable, the markdown parser and renderer used by Docusaurus. The plugin will receive a reference to the Remarkable instance, allowing custom parsing and rendering rules to be defined.
 

diff --git a/docs/getting-started-installation.md b/docs/getting-started-installation.md
@@ -3,7 +3,7 @@ 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, we have created an easy script that will get all of the infrastructure setup for you:
+Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly. To install Docusaurus, we have created an easy script that will get all of the infrastructure setup for you:
 
 1. Go into the root of your GitHub repo directory where you will be creating the docs.
 1. `yarn global add docusaurus-init` or `npm install --global docusaurus-init`

diff --git a/docs/getting-started-preparation.md b/docs/getting-started-preparation.md
@@ -51,7 +51,7 @@ Running the Docusaurus initialization script, `docusaurus-init`, produces a runn
 1. In your root, rename `docs-examples-from-docusaurus` to `docs`.
 1. `cd website`
 1. Rename `blog-examples-from-docusaurus` to `blog`.
-1. Run the local webserver via `yarn run start` or `npm run start`.
+1. Run the local webserver via `yarn start` or `npm start`.
 1. Load the example site at http://localhost:3000. You should see the example site loaded in your web browser.
 
 ![](/img/getting-started-preparation-verify.png)
diff --git a/docs/getting-started-publishing.md b/docs/getting-started-publishing.md
@@ -42,19 +42,22 @@ One of the required parameters is set as a environment variable:
 
 - `GIT_USER`: The username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your own GitHub username.
 
-There is also an optional parameter that is set as an environment variable. If nothing is set for this variable, then the current branch will be used.
+There are also two optional parameters that are set as environment variables:
 
-- `CURRENT_BRANCH`: The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `master`, but it could be any branch (default or otherwise) except for `gh-pages`.
+- `USE_SSH`: If this is set to `true`, then SSH is used instead of HTTPS for the connection to the GitHub repo. HTTPS is the default if this variable is not set.
+
+- `CURRENT_BRANCH`: The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `master`, but it could be any branch (default or otherwise) except for `gh-pages`. If nothing is set for this variable, then the current branch will be used.
 
 > Docusaurus also supports deploying user or organization sites. Just set your project name to "_username_.github.io" (where _username_ is your username or organization name on GitHub) and the publish script will automatically deploy your site to the root of the `master` branch instead.
 
 Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:
 
 To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.
 
-```
+```bash
 GIT_USER=<GIT_USER> \
   CURRENT_BRANCH=master \
+  USE_SSH=true \
   yarn run publish-gh-pages # or `npm run publish-gh-pages`
 ```
 
@@ -74,7 +77,7 @@ Continuous integration (CI) services are typically used to perform routine tasks
 
 If you're already using Circle CI for your project, all you need to do to enable automatic deployments is to configure Circle to run the `publish-gh-pages` script as part of the deployment step.
 
-1. Ensure the GitHub account that will be set as the `GIT_USER` has `write` access to the repo that contains the documentation.
+1. Ensure the GitHub account that will be set as the `GIT_USER` has `write` access to the repo that contains the documentation, by checking `Settings | Collaborators & teams` in the repo.
 1. Log into GitHub as the `GIT_USER`.
 1. Go to https://github.com/settings/tokens for the `GIT_USER` and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/), granting it full control of private repositories through the `repo` access scope. Store this token in a safe place, making sure to not share it with anyone. This token can be used to authenticate GitHub actions on your behalf in place of your GitHub password.
 1. Open your Circle CI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". The URL looks like https://circleci.com/gh/ORG/REPO/edit#env-vars, where "ORG/REPO" should be replaced with your own GitHub org/repo.
@@ -106,7 +109,9 @@ Make sure to replace `<GIT_USER>` with the actual username of the GitHub account
 
 **DO NOT** place the actual value of `$GITHUB_TOKEN` in `circle.yml`. We already configured that as an environment variable back in Step 3.
 
-> Unlike when you run the `publish-gh-pages` script manually, when the script runs within the Circle environment, the values of `ORGANIZATION_NAME`, `PROJECT_NAME`, and `CURRENT_BRANCH` are already defined as environment variables within CircleCI and will be picked up by the script automatically.
+> If you want to use SSH for your GitHub repo connection, you can set `USE_SSH=true`. So the above command would look something like: `cd website && npm install && GIT_USER=<GIT_USER> USE_SSH=true npm run publish-gh-pages`.
+
+> Unlike when you run the `publish-gh-pages` script manually, when the script runs within the Circle environment, the value of `CURRENT_BRANCH` is already defined as an [environment variable within CircleCI](https://circleci.com/docs/1.0/environment-variables/) and will be picked up by the script automatically.
 
 Now, whenever a new commit lands in `master`, CircleCI will run your suite of tests and, if everything passes, your website will be deployed via the `publish-gh-pages` script.
 

diff --git a/docs/guides-navigation.md b/docs/guides-navigation.md
@@ -3,6 +3,18 @@ id: navigation
 title: Navigation and Sidebars
 ---
 
+## Referencing Site Documents
+
+If you want to reference another document in your `docs` folder (or the location you set via the [optional `customDocsPath`](https://docusaurus.io/docs/en/site-config.html#optional-fields) path site configuration option), then you just use the name of the document you want to reference.
+
+For example, if you are in `doc2.md` and you want to reference `doc1.md`:
+
+```
+I am referencing a [document](doc1.md).
+```
+
+> Docusaurus currently does not support documents in nested folders; only in a flatfile structure. We are looking into adding support for nested folders.
+
 ## How Documents are Linked
 
 New markdown files within `docs` will show up as pages on the website. Links to those documents are created first by using the `id` in the header of each document. If there is no `id` field, then the name of the file will serve as the link name.