From bd3d55a80be10d3dc91a69365730ffbfdd2b7ccb Mon Sep 17 00:00:00 2001 From: Frank Li Date: Tue, 15 Aug 2017 10:57:49 -0700 Subject: [PATCH] Update documentation --- docs/site-config.md | 57 +++++++++++++++++++++++++-------------------- docs/translation.md | 15 +++++++----- docs/versioning.md | 28 +++++++++++++++++++++- 3 files changed, 68 insertions(+), 32 deletions(-) diff --git a/docs/site-config.md b/docs/site-config.md index af352d2086..5246b41235 100644 --- a/docs/site-config.md +++ b/docs/site-config.md @@ -27,22 +27,40 @@ The `siteConfig` object contains the bulk of the configuration settings for your `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. +`headerLinks` - Links that will be used in the header navigation bar. The `label` field of each object will be the link text and will also be translated for each language. +Example Usage: +```js +headerLinks: [ + // Links to document with id doc1 for current language/version + { doc: "doc1", label: "Getting Started" }, + // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language + { page: "help", label: "Help" }, + // Links to href destination + { href: "https://github.com/", label: "GitHub" }, + // Links to blog generated by Docusaurus (${baseUrl}blog) + { blog: true, label: "Blog" }, + // Determines search bar position among links + { search: true }, + // Determines language drop down position among links + { languages: true } +], +``` `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`. +`colors` - 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`. Other fields can be added + - Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to easily configure this color. ### 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. -`externalLinkTarget` - Target attribute for header external links. If this field is omitted, the default target of `"_self"` will be used. - `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`. @@ -59,6 +77,8 @@ The `siteConfig` object contains the bulk of the configuration settings for your `gaTrackingId` - Google Analytics tracking ID to track page views. +Users can also add their own custom fields if they wish to provide some data across different files. + ## Example siteConfig.js with all fields ``` @@ -79,25 +99,13 @@ const siteConfig = { 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" } + headerLinks: [ + { doc: "doc1", label: "Docs" }, + { page: "help", label: "Help" }, + { search: true }, + { blog: true } ], -// headerLinksInternal: [], - headerLinksExternal: [ - { - section: "github", - href: "https://github.com/deltice/test-site", - text: "GitHub" - } - ], -// headerLinksExternal: [], +// headerLinks: [], headerIcon: "img/docusaurus.svg", favicon: "img/favicon.png", colors: { @@ -109,7 +117,6 @@ const siteConfig = { editUrl: "https://github.com/deltice/test-site/edit/master/docs/", - externalLinkTarget: "_blank", users, disableHeaderTitle: true, disableTitleTagline: true, diff --git a/docs/translation.md b/docs/translation.md index 420a6e6d90..9191c63e2a 100644 --- a/docs/translation.md +++ b/docs/translation.md @@ -61,11 +61,12 @@ Add the following script to your package.json file: Running the script will generate a `website/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` and `sidebar_label` strings in document markdown headers - - category names in `sidebars.json` - - tagline in `siteConfig.js` - - header link `label` strings in `siteConfig.js` - - strings wrapped in the `` tag in any `.js` files inside `pages` + +- `title` and `sidebar_label` strings in document markdown headers +- category names in `sidebars.json` +- tagline in `siteConfig.js` +- header link `label` strings in `siteConfig.js` +- strings wrapped in the `` tag in any `.js` files inside `pages` ## How Strings Get Translated @@ -123,7 +124,9 @@ The `crowdin` command uses the `crowdin.yaml` file generated with the `examples` 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` in the `crowdin.yaml` file. The provided `crowdin.yaml` file will copy translated documents into `website/translated_docs/`, and translated versions of the `i18n/en.json` strings file will into `i18n/${language}.json`. +Now, Circle will help you automatically get translations prior to building your website. The provided `crowdin.yaml` file will copy translated documents into `website/translated_docs/`, and translated versions of the `i18n/en.json` strings file will into `i18n/${language}.json`. + +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. The only difference is that you must set `project_identifier` and `api_key` values in the `crowdin.yaml` file since you will not have Circle environment variables set up. ## Translations and Versioning diff --git a/docs/versioning.md b/docs/versioning.md index f04724d873..c7f922f77f 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -38,7 +38,15 @@ Users can create version numbers in whatever format they wish, and a new version ## Storing Files for Each Version -Versioned documents are placed into `website/versioned_docs/version-${version}`, where `${version}` is the version number you supplied the `version` script. The front matter for each versioned doc is altered by appending `"version-${version}-"` to the id and by adding an `original_id` field. Versioned sidebars are copied into `website/versioned_sidebars` and are named as `version-${version}-sidebar.json`. A `website/versions.json` file is created the first time you cut a version and is used by Docusaurus to detect what versions exist. Each time a new version is added, it gets added to the `versions.json` file. If you wish to change the documentation for a past version, you can access the files for that respective version. +Versioned documents are placed into `website/versioned_docs/version-${version}`, where `${version}` is the version number you supplied the `version` script. + +The markdown header for each versioned doc is altered by appending `"version-${version}-"` to the id and by adding an `original_id` field. + +Versioned sidebars are copied into `website/versioned_sidebars` and are named as `version-${version}-sidebar.json`. + +A `website/versions.json` file is created the first time you cut a version and is used by Docusaurus to detect what versions exist. Each time a new version is added, it gets added to the `versions.json` file. + +If you wish to change the documentation for a past version, you can access the files for that respective version. ## Fallback Functionality @@ -46,6 +54,24 @@ Only files in the `docs` folder and sidebar files that differ from those of the For example, a document with the original id `doc1` exists for the latest version, `1.0.0`, and has the same content as the document with the id `doc1` in the `docs` folder. When a new version `2.0.0` is created, the file for `doc1` will not be copied into `versioned_docs/version-2.0.0/`. There will still be a page for `docs/2.0.0/doc1.html`, but it will use the file from version `1.0.0`. +## Renaming Existing Versions + +To rename an existing version number to something else, first make sure the following script is in your `package.json` file: + +```json +... +"scripts": { + "rename-version": "docusaurus-rename-version" +}, +... +``` + +Run the script with command line arguments of first, the current version name, then second, the new version name. e.g., + +```bash +npm run rename-version 1.0.0 1.0.1 +``` + ## Versioning and Translations If you wish to use versioning and translations features, the `crowdin.yaml` file should be set up to upload and download versioned documents to and from Crowdin for translation. Translated, versioned files will go into the folder `translated_docs/${language}/version-${version}/`. For more information, check out the [translations guide](translation.md).