diff --git a/docs/api-pages.md b/docs/api-pages.md index e46ed96c6b..9d5403c220 100644 --- a/docs/api-pages.md +++ b/docs/api-pages.md @@ -92,7 +92,7 @@ Example: /> ``` -More examples of how these components are used can be found in the [generated example files](getting-started-preparation.md) as well as in Docusaurus's own repo for its website set-up. +More examples of how these components are used can be found in the [generated example files](getting-started-preparation.md) as well as in Docusaurus' own repo for its website set-up. ## Translating Strings @@ -108,7 +108,7 @@ You can also provide an optional description attribute to provide context for tr ```jsx - Community + Community ``` @@ -129,6 +129,6 @@ Static assets should be placed into the `website/static` folder. They can be acc You should configure your site's primary, secondary, and code block colors using the `colors` field in `siteConfig` as specified [here](api-site-config.md). You can also configure other colors in the same way as described in the `siteConfig` doc. -You can provide your own custom styles by adding them anywhere in the `website/static` folder. Any `.css` files you provide in the `static` folder will get concatenated to the end of Docusaurus's provided styles, allowing you to add to or override Docusaurus default styles as you wish. +You can provide your own custom styles by adding them anywhere in the `website/static` folder. Any `.css` files you provide in the `static` folder will get concatenated to the end of Docusaurus' provided styles, allowing you to add to or override Docusaurus default styles as you wish. An easy way to figure out what classes you wish to override or add to is to [start your server locally](api-commands.md) and use your browser's inspect element tool. diff --git a/docs/api-site-config.md b/docs/api-site-config.md index 0a2fdd65ea..a8e432b051 100644 --- a/docs/api-site-config.md +++ b/docs/api-site-config.md @@ -73,7 +73,7 @@ headerLinks: [ `cname` - The CNAME for your website. It will go into a `CNAME` file when your site it built. -`customDocsPath` - By default, Docusaurus expects your documentation to be in a directory called `docs`. This directory is at the same level as the `website` directory (i.e., not inside the `website` directory). You can specify a custom path to your documentation with this field. **Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories**. +`customDocsPath` - By default, Docusaurus expects your documentation to be in a directory called `docs`. This directory is at the same level as the `website` directory (i.e., not inside the `website` directory). You can specify a custom path to your documentation with this field. **Note that all of your documentation `*.md` files must still reside in a flat hierarchy. You cannot have your documents in nested directories**. ```js customDocsPath: "docs/site" @@ -140,7 +140,7 @@ h1 { `scripts` - Array of JavaScript sources to load. The script tag will be inserted in the HTML head. -`separateCss` - Folders inside which any `css` files will not be processed and concatenated to Docusaurus's styles. This is to support static `html` pages that may be separate from Docusaurus with completely separate styles. +`separateCss` - Folders inside which any `css` files will not be processed and concatenated to Docusaurus' styles. This is to support static `html` pages that may be separate from Docusaurus with completely separate styles. `stylesheets` - Array of CSS sources to load. The link tag will be inserted in the HTML head. diff --git a/docs/getting-started-site-creation.md b/docs/getting-started-site-creation.md index 2b42f585d5..40cf149d8b 100644 --- a/docs/getting-started-site-creation.md +++ b/docs/getting-started-site-creation.md @@ -30,7 +30,7 @@ root-of-repo 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 +> The blog posts must be formatted as `YYYY-MM-DD-your-file-name.md` ## Create Your Basic Site @@ -51,7 +51,7 @@ To create a fully functional site, you only need to do a few steps: > 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](api-site-config.md), following the comments included in the [docs](api-site-config.md) and the `website/siteConfig.js` to guide you. +3. Modify the `website/siteConfig.js` file to [configure your site](api-site-config.md), following the comments included in the [docs](api-site-config.md) and the `website/siteConfig.js` to guide you. 1. Create any [custom pages](guides-custom-pages.md#customizing-your-site-footer) and/or [customize](guides-custom-pages.md#customizing-your-site-footer) 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. diff --git a/docs/guides-blog.md b/docs/guides-blog.md index 25bee7d1c7..4e6ff711b7 100644 --- a/docs/guides-blog.md +++ b/docs/guides-blog.md @@ -52,7 +52,7 @@ Use the `` marker in your blog post to represent what will be sho ``` --- -title: Truncation Exmaple +title: Truncation Example --- All this will be part of the blog post summary. @@ -72,9 +72,9 @@ Or this. By default, 5 recent blog posts are shown on the sidebar. -You can configure a specifc amount of blog posts to show by adding a `blogSidebarCount` setting to your `siteConfig.js`. +You can configure a specific amount of blog posts to show by adding a `blogSidebarCount` setting to your `siteConfig.js`. -The available options are an integer repreenting the number of posts you wish to show or a string with the value 'ALL'. +The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'. Example: ``` diff --git a/docs/guides-custom-pages.md b/docs/guides-custom-pages.md index dc9907a424..6fd1b0841b 100644 --- a/docs/guides-custom-pages.md +++ b/docs/guides-custom-pages.md @@ -35,11 +35,11 @@ root-of-repo Of course, you are also free to write your own pages. It is strongly suggested that you at least have an index page, but none of the pages provided are mandatory to include in your site. More information on how to use the provided components or include your own can be found [here](api-pages.md). Information on how to link to your different pages in the header navigation bar can be found [here](guides-navigation.md). -> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: "about-slash", label: "About/"}`, +> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: "about-slash", label: "About/"}`, ## Adding Static Pages -Static `.html` files can also be used, but they will not include Docusaurus's header, footer, or styles by default. These can be added to the `static` folder in the same way as other [static assets](api-pages.md#using-static-assets). Alternatively, they can be placed in the `pages` folder and would be served as-is instead of being rendered from React. +Static `.html` files can also be used, but they will not include Docusaurus' header, footer, or styles by default. These can be added to the `static` folder in the same way as other [static assets](api-pages.md#using-static-assets). Alternatively, they can be placed in the `pages` folder and would be served as-is instead of being rendered from React. If you wish to use Docusaurus's stylesheet, you can access it at `${baseUrl}css/main.css`. If you wish to use separate css for these static pages, you can exclude them from being concatenated to Docusaurus's styles by adding them into the `siteConfig.separateCss` field in `siteConfig.js`. diff --git a/docs/guides-navigation.md b/docs/guides-navigation.md index b251fde7d3..7cfdd62811 100644 --- a/docs/guides-navigation.md +++ b/docs/guides-navigation.md @@ -19,7 +19,7 @@ I am referencing a [document](doc1.md). 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. -For example, creating an empty file such as "docs/getting-started.md" will enable the new page URL as `/docs/getting-started.html`. +For example, creating an empty file such as `docs/getting-started.md` will enable the new page URL as `/docs/getting-started.html`. Suppose you add this to your document: @@ -166,6 +166,7 @@ The links in the top navigation bar get `siteNavItemActive` and `siteNavGroupAct > This does not include links of type `href` which are meant for external links only. If you manually set an `href` in your headerLinks to an internal page, document, or blog post, it will not get the `siteNavItemActive` class even if that page is being displayed. `siteNavGroupActive` will be added to these links: + * `doc` links that belong to the same sidebar as the currently displayed document * The blog link when a blog post, or the blog listing page is being displayed diff --git a/docs/guides-translation.md b/docs/guides-translation.md index a5d73db46a..e3847a3002 100644 --- a/docs/guides-translation.md +++ b/docs/guides-translation.md @@ -27,13 +27,13 @@ languages.js ../crowdin.yaml ``` -- The `pages/en/help-with-translations.js` file includes the same starter help page generated by the `examples` script, but now includes translation tags. +- The `pages/en/help-with-translations.js` file includes the same starter help page generated by the `examples` script, but now includes translation tags. > Generally, you will use `help-with-translations.js` as a guide to enable translations in your other pages, but not actually commit the file to your repo (i.e., you can delete it). However, if you want a Help page, and you currently do not have one, you can rename this file to `help.js` and use it as a starting point. - The `languages.js` file tells Docusaurus what languages you want to enable for your site. By default, we expect English to be enabled. -- The `crowdin.yaml` file is used to configure crowdin integration, and is copied up one level into your docusaurus project repo. If your docusaurus project resides in `/project/website`, then `crowdin.yaml` will be copied to `/project/crowdin.yaml`. +- The `crowdin.yaml` file is used to configure Crowdin integration, and is copied up one level into your Docusaurus project repo. If your Docusaurus project resides in `/project/website`, then `crowdin.yaml` will be copied to `/project/crowdin.yaml`. ## Translating Your Existing Docs @@ -47,6 +47,7 @@ Pages allow you to customize layout and specific content of pages like a custom Pages with text that you want translated should be placed in `website/pages/en` folder. Wrap strings you want translated in a `` tag, and add the following `require` statement to the top of the file: + ```jsx ... const translate = require("../../server/translate.js").translate; @@ -58,6 +59,7 @@ const translate = require("../../server/translate.js").translate; ``` You can also include an optional description attribute to give more context to a translator about how to translate the string: + ```jsx

Rose @@ -71,6 +73,7 @@ You can also include an optional description attribute to give more context to a The strings within localized Pages must be extracted and provided to Crowdin. Add the following script to your `website/package.json` file, if it does not exist already: + ```json ... "scripts": { @@ -119,13 +122,13 @@ Create your translation project on [Crowdin](https://crowdin.com/). You can use > Ensure in your Crowdin settings, in the Translations section, that "Duplicate Strings" are set to ["Hide - all duplicates will share the same translation"](https://support.crowdin.com/api/create-project/). This setting will ensure that identical strings between versions share a single translation. -Your project will need a `crowdin.yaml` file generated. If you ran `yarn examples translations` or `npm run examples translations`, this file was created for you on the same level as your `website` diretory. +Your project will need a `crowdin.yaml` file generated. If you ran `yarn examples translations` or `npm run examples translations`, this file was created for you on the same level as your `website` directory. > You will need to install the `crowdin` command line interface. Please follow the [installation directions](https://support.crowdin.com/cli-tool/). -The example below can be automatically generated by the docusaurus cli with the `examples` script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded. +The example below can be automatically generated by the Docusaurus cli with the `examples` script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded. -Below is an example crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Behasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional. +Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Behasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional. ```yaml project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID