diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md index 221263f6adc1..e6326cb0fe1e 100644 --- a/.github/ISSUE_TEMPLATE/bug.md +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -16,9 +16,9 @@ labels: 'bug, needs triage' (Write your steps here:) -1. -1. -1. +1. Step 1... +1. Step 2... +1. Step 3... ## Expected behavior diff --git a/.prettierignore b/.prettierignore index 446331054527..e918d160e80b 100644 --- a/.prettierignore +++ b/.prettierignore @@ -10,3 +10,4 @@ packages/docusaurus-plugin-content-docs/lib/ packages/docusaurus-plugin-content-pages/lib/ packages/docusaurus-plugin-sitemap/lib/ packages/docusaurus-plugin-ideal-image/lib/ +__fixtures__ diff --git a/CHANGELOG-2.x.md b/CHANGELOG-2.x.md index f7bdbac771a7..65e63e1bd580 100644 --- a/CHANGELOG-2.x.md +++ b/CHANGELOG-2.x.md @@ -3,29 +3,34 @@ ## 2.0.0-alpha.39 #### :bug: Bug Fix -* `docusaurus` - * [#2099](https://github.com/facebook/docusaurus/pull/2099) fix(v2): escape import path on windows ([@endiliey](https://github.com/endiliey)) -* `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs` - * [#2095](https://github.com/facebook/docusaurus/pull/2095) fix(v2): metadata error if markdown does not have ending line ([@endiliey](https://github.com/endiliey)) + +- `docusaurus` + - [#2099](https://github.com/facebook/docusaurus/pull/2099) fix(v2): escape import path on windows ([@endiliey](https://github.com/endiliey)) +- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs` + - [#2095](https://github.com/facebook/docusaurus/pull/2095) fix(v2): metadata error if markdown does not have ending line ([@endiliey](https://github.com/endiliey)) #### :house: Internal -* Other - * [#2100](https://github.com/facebook/docusaurus/pull/2100) chore(CI): docusaurus build on Windows with GitHub actions ([@endiliey](https://github.com/endiliey)) -* `docusaurus` - * [#2096](https://github.com/facebook/docusaurus/pull/2096) feat(v2): better & nice looking error overlay ([@endiliey](https://github.com/endiliey)) + +- Other + - [#2100](https://github.com/facebook/docusaurus/pull/2100) chore(CI): docusaurus build on Windows with GitHub actions ([@endiliey](https://github.com/endiliey)) +- `docusaurus` + - [#2096](https://github.com/facebook/docusaurus/pull/2096) feat(v2): better & nice looking error overlay ([@endiliey](https://github.com/endiliey)) #### Committers: 1 + - Endi ([@endiliey](https://github.com/endiliey)) ## 2.0.0-alpha.38 #### :boom: Breaking Change -* `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-theme-classic`, `docusaurus-utils` - * [#2088](https://github.com/facebook/docusaurus/pull/2088) perf(v2): smaller bundlesize by embedding metadata to content ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-theme-classic`, `docusaurus-utils` + - [#2088](https://github.com/facebook/docusaurus/pull/2088) perf(v2): smaller bundlesize by embedding metadata to content ([@endiliey](https://github.com/endiliey)) If you have swizzled any Docs/Blog component that depends on metadata, you'll have to update. If you haven't, no action is needed. For example, if you've swizzled `@theme/DocItem`. You'll have to update + ```diff - const {metadata, content: DocContent} = props; + const {content: DocContent} = props; @@ -33,31 +38,36 @@ For example, if you've swizzled `@theme/DocItem`. You'll have to update ``` #### :bug: Bug Fix -* `docusaurus` - * [#2086](https://github.com/facebook/docusaurus/pull/2086) fix(v2): windows compatibility regression ([@endiliey](https://github.com/endiliey)) -* `docusaurus-plugin-ideal-image` - * [#2074](https://github.com/facebook/docusaurus/pull/2074) fix(v2): fix plugin-ideal-image breaking website (exports not defined) ([@endiliey](https://github.com/endiliey)) + +- `docusaurus` + - [#2086](https://github.com/facebook/docusaurus/pull/2086) fix(v2): windows compatibility regression ([@endiliey](https://github.com/endiliey)) +- `docusaurus-plugin-ideal-image` + - [#2074](https://github.com/facebook/docusaurus/pull/2074) fix(v2): fix plugin-ideal-image breaking website (exports not defined) ([@endiliey](https://github.com/endiliey)) #### :nail_care: Polish -* `docusaurus-mdx-loader` - * [#2085](https://github.com/facebook/docusaurus/pull/2085) misc(v2): update mdx loader plugin README ([@shivangna](https://github.com/shivangna)) + +- `docusaurus-mdx-loader` + - [#2085](https://github.com/facebook/docusaurus/pull/2085) misc(v2): update mdx loader plugin README ([@shivangna](https://github.com/shivangna)) #### :house: Internal -* `docusaurus-1.x` - * [#2087](https://github.com/facebook/docusaurus/pull/2087) fix(v1): add key to versions.map in versions.js ([@FeynmanDNA](https://github.com/FeynmanDNA)) - * [#2083](https://github.com/facebook/docusaurus/pull/2083) refactor(v1): fix props for ProjectTitle ([@FeynmanDNA](https://github.com/FeynmanDNA)) -* `docusaurus` - * [#2081](https://github.com/facebook/docusaurus/pull/2081) refactor(v2): move scripts/stylesheets injection to server side ([@endiliey](https://github.com/endiliey)) - * [#2080](https://github.com/facebook/docusaurus/pull/2080) refactor(v2): minor code refactoring on component creator ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-1.x` + - [#2087](https://github.com/facebook/docusaurus/pull/2087) fix(v1): add key to versions.map in versions.js ([@FeynmanDNA](https://github.com/FeynmanDNA)) + - [#2083](https://github.com/facebook/docusaurus/pull/2083) refactor(v1): fix props for ProjectTitle ([@FeynmanDNA](https://github.com/FeynmanDNA)) +- `docusaurus` + - [#2081](https://github.com/facebook/docusaurus/pull/2081) refactor(v2): move scripts/stylesheets injection to server side ([@endiliey](https://github.com/endiliey)) + - [#2080](https://github.com/facebook/docusaurus/pull/2080) refactor(v2): minor code refactoring on component creator ([@endiliey](https://github.com/endiliey)) #### :running_woman: Performance -* `docusaurus-utils` - * [#2089](https://github.com/facebook/docusaurus/pull/2089) perf(v2): improve dev build time by not overwriting file if possible ([@endiliey](https://github.com/endiliey)) -* `docusaurus-theme-search-algolia` - * [#2079](https://github.com/facebook/docusaurus/pull/2079) perf(v2): algolia search result no longer cause full page refresh ([@endiliey](https://github.com/endiliey)) - * [#2076](https://github.com/facebook/docusaurus/pull/2076) perf(v2): load algolia JS only when user interacts with search ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-utils` + - [#2089](https://github.com/facebook/docusaurus/pull/2089) perf(v2): improve dev build time by not overwriting file if possible ([@endiliey](https://github.com/endiliey)) +- `docusaurus-theme-search-algolia` + - [#2079](https://github.com/facebook/docusaurus/pull/2079) perf(v2): algolia search result no longer cause full page refresh ([@endiliey](https://github.com/endiliey)) + - [#2076](https://github.com/facebook/docusaurus/pull/2076) perf(v2): load algolia JS only when user interacts with search ([@endiliey](https://github.com/endiliey)) #### Committers: 4 + - Endi ([@endiliey](https://github.com/endiliey)) - KYY ([@FeynmanDNA](https://github.com/FeynmanDNA)) - Shivangna Kaistha ([@shivangna](https://github.com/shivangna)) @@ -66,73 +76,81 @@ For example, if you've swizzled `@theme/DocItem`. You'll have to update ## 2.0.0-alpha.37 #### :boom: Breaking Change -* `docusaurus-init`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-theme-classic`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus-utils`, `docusaurus` - * [#2045](https://github.com/facebook/docusaurus/pull/2045) breaking(v2): minimum required nodejs version 8.9-> 8.10 so we can use es2017 ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-init`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-theme-classic`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus-utils`, `docusaurus` + - [#2045](https://github.com/facebook/docusaurus/pull/2045) breaking(v2): minimum required nodejs version 8.9-> 8.10 so we can use es2017 ([@endiliey](https://github.com/endiliey)) #### :rocket: New Feature -* `docusaurus-theme-classic`, `docusaurus` - * [#2069](https://github.com/facebook/docusaurus/pull/2069) feat(v2): support prefers-color-scheme & fix dark mode FOUC on refresh ([@endiliey](https://github.com/endiliey)) -* `docusaurus-plugin-content-blog` - * [#2000](https://github.com/facebook/docusaurus/pull/2000) feat(v2): add meta RSS/Atom feed links to head ([@lex111](https://github.com/lex111)) -* `docusaurus-plugin-content-docs`, `docusaurus-types`, `docusaurus` - * [#2057](https://github.com/facebook/docusaurus/pull/2057) feat(v2): injectHtmlTags API to inject head and/or body html tags ([@endiliey](https://github.com/endiliey)) -* `docusaurus-mdx-loader`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-sitemap`, `docusaurus-theme-classic`, `docusaurus` - * [#2032](https://github.com/facebook/docusaurus/pull/2032) feat(v2): allow non sidebar category to be first item of sidebar ([@endiliey](https://github.com/endiliey)) -* `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-types`, `docusaurus` - * [#1983](https://github.com/facebook/docusaurus/pull/1983) feat(v2): docs versioning ❄️πŸ”₯ ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-theme-classic`, `docusaurus` + - [#2069](https://github.com/facebook/docusaurus/pull/2069) feat(v2): support prefers-color-scheme & fix dark mode FOUC on refresh ([@endiliey](https://github.com/endiliey)) +- `docusaurus-plugin-content-blog` + - [#2000](https://github.com/facebook/docusaurus/pull/2000) feat(v2): add meta RSS/Atom feed links to head ([@lex111](https://github.com/lex111)) +- `docusaurus-plugin-content-docs`, `docusaurus-types`, `docusaurus` + - [#2057](https://github.com/facebook/docusaurus/pull/2057) feat(v2): injectHtmlTags API to inject head and/or body html tags ([@endiliey](https://github.com/endiliey)) +- `docusaurus-mdx-loader`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-sitemap`, `docusaurus-theme-classic`, `docusaurus` + - [#2032](https://github.com/facebook/docusaurus/pull/2032) feat(v2): allow non sidebar category to be first item of sidebar ([@endiliey](https://github.com/endiliey)) +- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-types`, `docusaurus` + - [#1983](https://github.com/facebook/docusaurus/pull/1983) feat(v2): docs versioning ❄️πŸ”₯ ([@endiliey](https://github.com/endiliey)) #### :bug: Bug Fix -* `docusaurus-theme-classic`, `docusaurus` - * [#2069](https://github.com/facebook/docusaurus/pull/2069) feat(v2): support prefers-color-scheme & fix dark mode FOUC on refresh ([@endiliey](https://github.com/endiliey)) -* `docusaurus-mdx-loader` - * [#2067](https://github.com/facebook/docusaurus/pull/2067) fix(v2): toc should not be broken for heading with html inline code ([@endiliey](https://github.com/endiliey)) -* `docusaurus-theme-classic` - * [#2064](https://github.com/facebook/docusaurus/pull/2064) fix(v2): markdown reference to file should not be page not found ([@endiliey](https://github.com/endiliey)) - * [#2061](https://github.com/facebook/docusaurus/pull/2061) fix(v2): fix docs sidebar highlighting if link is partially matched ([@endiliey](https://github.com/endiliey)) -* `docusaurus` - * [#2042](https://github.com/facebook/docusaurus/pull/2042) fix(v2): remove css order warning if css imports are not sorted ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-theme-classic`, `docusaurus` + - [#2069](https://github.com/facebook/docusaurus/pull/2069) feat(v2): support prefers-color-scheme & fix dark mode FOUC on refresh ([@endiliey](https://github.com/endiliey)) +- `docusaurus-mdx-loader` + - [#2067](https://github.com/facebook/docusaurus/pull/2067) fix(v2): toc should not be broken for heading with html inline code ([@endiliey](https://github.com/endiliey)) +- `docusaurus-theme-classic` + - [#2064](https://github.com/facebook/docusaurus/pull/2064) fix(v2): markdown reference to file should not be page not found ([@endiliey](https://github.com/endiliey)) + - [#2061](https://github.com/facebook/docusaurus/pull/2061) fix(v2): fix docs sidebar highlighting if link is partially matched ([@endiliey](https://github.com/endiliey)) +- `docusaurus` + - [#2042](https://github.com/facebook/docusaurus/pull/2042) fix(v2): remove css order warning if css imports are not sorted ([@endiliey](https://github.com/endiliey)) #### :nail_care: Polish -* `docusaurus-theme-classic` - * [#2066](https://github.com/facebook/docusaurus/pull/2066) refactor(v2): add title attribute to anchor link ([@lex111](https://github.com/lex111)) - * [#1990](https://github.com/facebook/docusaurus/pull/1990) refactor(v2): make better a11y for tabs ([@lex111](https://github.com/lex111)) - * [#2034](https://github.com/facebook/docusaurus/pull/2034) feat(v2): style sidebar on overflow ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-theme-classic` + - [#2066](https://github.com/facebook/docusaurus/pull/2066) refactor(v2): add title attribute to anchor link ([@lex111](https://github.com/lex111)) + - [#1990](https://github.com/facebook/docusaurus/pull/1990) refactor(v2): make better a11y for tabs ([@lex111](https://github.com/lex111)) + - [#2034](https://github.com/facebook/docusaurus/pull/2034) feat(v2): style sidebar on overflow ([@endiliey](https://github.com/endiliey)) #### :memo: Documentation -* Other - * [#2068](https://github.com/facebook/docusaurus/pull/2068) docs(v2): quick proofread docs ([@endiliey](https://github.com/endiliey)) - * [#2047](https://github.com/facebook/docusaurus/pull/2047) docs(v2): add manual migration guide for versioning ([@endiliey](https://github.com/endiliey)) - * [#2036](https://github.com/facebook/docusaurus/pull/2036) docs(v2): Reorganize migration guide ([@wgao19](https://github.com/wgao19)) - * [#2052](https://github.com/facebook/docusaurus/pull/2052) fix(v2): make proper spelling of Yarn in tabs ([@lex111](https://github.com/lex111)) - * [#2040](https://github.com/facebook/docusaurus/pull/2040) docs(v2): showcase user vector.dev :) ([@binarylogic](https://github.com/binarylogic)) - * [#2038](https://github.com/facebook/docusaurus/pull/2038) docs(v2): add documentation on versioning ([@endiliey](https://github.com/endiliey)) - * [#2037](https://github.com/facebook/docusaurus/pull/2037) docs(v2): display yarn and npm command on website ([@endiliey](https://github.com/endiliey)) - * [#2051](https://github.com/facebook/docusaurus/pull/2051) docs(v2): more examples on lifecycle apis, cleanup ([@endiliey](https://github.com/endiliey)) + +- Other + - [#2068](https://github.com/facebook/docusaurus/pull/2068) docs(v2): quick proofread docs ([@endiliey](https://github.com/endiliey)) + - [#2047](https://github.com/facebook/docusaurus/pull/2047) docs(v2): add manual migration guide for versioning ([@endiliey](https://github.com/endiliey)) + - [#2036](https://github.com/facebook/docusaurus/pull/2036) docs(v2): Reorganize migration guide ([@wgao19](https://github.com/wgao19)) + - [#2052](https://github.com/facebook/docusaurus/pull/2052) fix(v2): make proper spelling of Yarn in tabs ([@lex111](https://github.com/lex111)) + - [#2040](https://github.com/facebook/docusaurus/pull/2040) docs(v2): showcase user vector.dev :) ([@binarylogic](https://github.com/binarylogic)) + - [#2038](https://github.com/facebook/docusaurus/pull/2038) docs(v2): add documentation on versioning ([@endiliey](https://github.com/endiliey)) + - [#2037](https://github.com/facebook/docusaurus/pull/2037) docs(v2): display yarn and npm command on website ([@endiliey](https://github.com/endiliey)) + - [#2051](https://github.com/facebook/docusaurus/pull/2051) docs(v2): more examples on lifecycle apis, cleanup ([@endiliey](https://github.com/endiliey)) #### :house: Internal -* `docusaurus-plugin-content-blog` - * [#2072](https://github.com/facebook/docusaurus/pull/2072) refactor(v2): stronger typing for blog plugin ([@endiliey](https://github.com/endiliey)) -* `docusaurus` - * [#2060](https://github.com/facebook/docusaurus/pull/2060) fix(v2): clean generated manifest from previous build so we dont use the wrong one ([@endiliey](https://github.com/endiliey)) - * [#2033](https://github.com/facebook/docusaurus/pull/2033) refactor(v2): move unused generated files out from build folder ([@endiliey](https://github.com/endiliey)) -* `docusaurus-types`, `docusaurus` - * [#2043](https://github.com/facebook/docusaurus/pull/2043) refactor(v2): stronger typing for route gen ([@endiliey](https://github.com/endiliey)) -* `docusaurus-mdx-loader`, `docusaurus-plugin-ideal-image`, `docusaurus-types`, `docusaurus` - * [#2044](https://github.com/facebook/docusaurus/pull/2044) chore(v2): bump deps ([@endiliey](https://github.com/endiliey)) -* `docusaurus-init`, `docusaurus-mdx-loader`, `docusaurus-plugin-content-docs`, `docusaurus` - * [#2029](https://github.com/facebook/docusaurus/pull/2029) chore(v2): bump deps and remove unused deps ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-plugin-content-blog` + - [#2072](https://github.com/facebook/docusaurus/pull/2072) refactor(v2): stronger typing for blog plugin ([@endiliey](https://github.com/endiliey)) +- `docusaurus` + - [#2060](https://github.com/facebook/docusaurus/pull/2060) fix(v2): clean generated manifest from previous build so we dont use the wrong one ([@endiliey](https://github.com/endiliey)) + - [#2033](https://github.com/facebook/docusaurus/pull/2033) refactor(v2): move unused generated files out from build folder ([@endiliey](https://github.com/endiliey)) +- `docusaurus-types`, `docusaurus` + - [#2043](https://github.com/facebook/docusaurus/pull/2043) refactor(v2): stronger typing for route gen ([@endiliey](https://github.com/endiliey)) +- `docusaurus-mdx-loader`, `docusaurus-plugin-ideal-image`, `docusaurus-types`, `docusaurus` + - [#2044](https://github.com/facebook/docusaurus/pull/2044) chore(v2): bump deps ([@endiliey](https://github.com/endiliey)) +- `docusaurus-init`, `docusaurus-mdx-loader`, `docusaurus-plugin-content-docs`, `docusaurus` + - [#2029](https://github.com/facebook/docusaurus/pull/2029) chore(v2): bump deps and remove unused deps ([@endiliey](https://github.com/endiliey)) #### :running_woman: Performance -* `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag` - * [#2070](https://github.com/facebook/docusaurus/pull/2070) perf(v2): more performant gtag and analytics plugin ([@endiliey](https://github.com/endiliey)) -* `docusaurus` - * [#2046](https://github.com/facebook/docusaurus/pull/2046) perf(v2): use webpack future version of asset emitting logic to free memory ([@endiliey](https://github.com/endiliey)) - * [#2039](https://github.com/facebook/docusaurus/pull/2039) perf(v2): replace unnecessary json stringify(string) with inline string ([@endiliey](https://github.com/endiliey)) - * [#2035](https://github.com/facebook/docusaurus/pull/2035) perf(v2): use @babel/runtime plugin to reduce codesize ([@endiliey](https://github.com/endiliey)) -* `docusaurus-plugin-content-docs` - * [#2054](https://github.com/facebook/docusaurus/pull/2054) perf(v2): unblock metadata processing when possible ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag` + - [#2070](https://github.com/facebook/docusaurus/pull/2070) perf(v2): more performant gtag and analytics plugin ([@endiliey](https://github.com/endiliey)) +- `docusaurus` + - [#2046](https://github.com/facebook/docusaurus/pull/2046) perf(v2): use webpack future version of asset emitting logic to free memory ([@endiliey](https://github.com/endiliey)) + - [#2039](https://github.com/facebook/docusaurus/pull/2039) perf(v2): replace unnecessary json stringify(string) with inline string ([@endiliey](https://github.com/endiliey)) + - [#2035](https://github.com/facebook/docusaurus/pull/2035) perf(v2): use @babel/runtime plugin to reduce codesize ([@endiliey](https://github.com/endiliey)) +- `docusaurus-plugin-content-docs` + - [#2054](https://github.com/facebook/docusaurus/pull/2054) perf(v2): unblock metadata processing when possible ([@endiliey](https://github.com/endiliey)) #### Committers: 5 + - Alexey Pyltsyn ([@lex111](https://github.com/lex111)) - Binary Logic ([@binarylogic](https://github.com/binarylogic)) - Dongwoo Gim ([@gimdongwoo](https://github.com/gimdongwoo)) @@ -142,38 +160,45 @@ For example, if you've swizzled `@theme/DocItem`. You'll have to update ## 2.0.0-alpha.36 #### :boom: Breaking Change -* `docusaurus-init`, `docusaurus-plugin-content-blog`, `docusaurus-theme-classic` - * [#1989](https://github.com/facebook/docusaurus/pull/1989) misc(v2): change blog front matter to snake_case ([@yangshun](https://github.com/yangshun)) + +- `docusaurus-init`, `docusaurus-plugin-content-blog`, `docusaurus-theme-classic` + - [#1989](https://github.com/facebook/docusaurus/pull/1989) misc(v2): change blog front matter to snake_case ([@yangshun](https://github.com/yangshun)) #### :rocket: New Feature -* `docusaurus-plugin-content-docs`, `docusaurus-theme-classic` - * [#2012](https://github.com/facebook/docusaurus/pull/2012) feat(v2): allow hiding docs table of contents ([@yangshun](https://github.com/yangshun)) + +- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic` + - [#2012](https://github.com/facebook/docusaurus/pull/2012) feat(v2): allow hiding docs table of contents ([@yangshun](https://github.com/yangshun)) #### :bug: Bug Fix -* `docusaurus` - * [#2007](https://github.com/facebook/docusaurus/pull/2007) feat(v2): only create one css file to avoid code-split css loading problem ([@endiliey](https://github.com/endiliey)) -* `docusaurus-theme-classic` - * [#2005](https://github.com/facebook/docusaurus/pull/2005) fix(v2): adjust first-level heading offset ([@lex111](https://github.com/lex111)) + +- `docusaurus` + - [#2007](https://github.com/facebook/docusaurus/pull/2007) feat(v2): only create one css file to avoid code-split css loading problem ([@endiliey](https://github.com/endiliey)) +- `docusaurus-theme-classic` + - [#2005](https://github.com/facebook/docusaurus/pull/2005) fix(v2): adjust first-level heading offset ([@lex111](https://github.com/lex111)) #### :nail_care: Polish -* `docusaurus-theme-classic` - * [#2013](https://github.com/facebook/docusaurus/pull/2013) refactor(v2): split out dark mode toggle so it is easily swizzle-able ([@endiliey](https://github.com/endiliey)) - * [#2017](https://github.com/facebook/docusaurus/pull/2017) feat(v2): style right sidebar scrollbar when overflow ([@endiliey](https://github.com/endiliey)) - * [#2003](https://github.com/facebook/docusaurus/pull/2003) refactor(v2): improve semantic markup of blog ([@lex111](https://github.com/lex111)) + +- `docusaurus-theme-classic` + - [#2013](https://github.com/facebook/docusaurus/pull/2013) refactor(v2): split out dark mode toggle so it is easily swizzle-able ([@endiliey](https://github.com/endiliey)) + - [#2017](https://github.com/facebook/docusaurus/pull/2017) feat(v2): style right sidebar scrollbar when overflow ([@endiliey](https://github.com/endiliey)) + - [#2003](https://github.com/facebook/docusaurus/pull/2003) refactor(v2): improve semantic markup of blog ([@lex111](https://github.com/lex111)) #### :house: Internal -* `docusaurus` - * [#2024](https://github.com/facebook/docusaurus/pull/2024) test(v2): babel exclude transpilation logic to prevent regression ([@endiliey](https://github.com/endiliey)) - * [#2014](https://github.com/facebook/docusaurus/pull/2014) feat(v2): add meta generator docusaurus ([@endiliey](https://github.com/endiliey)) -* `docusaurus-mdx-loader`, `docusaurus-plugin-ideal-image` - * [#2015](https://github.com/facebook/docusaurus/pull/2015) chore(v2): bump & remove unused deps ([@endiliey](https://github.com/endiliey)) -* Other - * [#2009](https://github.com/facebook/docusaurus/pull/2009) misc(v2): branding update ([@yangshun](https://github.com/yangshun)) + +- `docusaurus` + - [#2024](https://github.com/facebook/docusaurus/pull/2024) test(v2): babel exclude transpilation logic to prevent regression ([@endiliey](https://github.com/endiliey)) + - [#2014](https://github.com/facebook/docusaurus/pull/2014) feat(v2): add meta generator docusaurus ([@endiliey](https://github.com/endiliey)) +- `docusaurus-mdx-loader`, `docusaurus-plugin-ideal-image` + - [#2015](https://github.com/facebook/docusaurus/pull/2015) chore(v2): bump & remove unused deps ([@endiliey](https://github.com/endiliey)) +- Other + - [#2009](https://github.com/facebook/docusaurus/pull/2009) misc(v2): branding update ([@yangshun](https://github.com/yangshun)) #### :memo: Documentation -* [#2010](https://github.com/facebook/docusaurus/pull/2010) docs(v2): misc updates ([@yangshun](https://github.com/yangshun)) + +- [#2010](https://github.com/facebook/docusaurus/pull/2010) docs(v2): misc updates ([@yangshun](https://github.com/yangshun)) #### Committers: 3 + - Alexey Pyltsyn ([@lex111](https://github.com/lex111)) - Endi ([@endiliey](https://github.com/endiliey)) - Yangshun Tay ([@yangshun](https://github.com/yangshun)) @@ -181,64 +206,71 @@ For example, if you've swizzled `@theme/DocItem`. You'll have to update ## 2.0.0-alpha.35 #### :rocket: New Feature -* `docusaurus-theme-classic` - * [#1965](https://github.com/facebook/docusaurus/pull/1965) feat(v2): add ability specify link in footer logo ([@lex111](https://github.com/lex111)) + +- `docusaurus-theme-classic` + - [#1965](https://github.com/facebook/docusaurus/pull/1965) feat(v2): add ability specify link in footer logo ([@lex111](https://github.com/lex111)) #### :bug: Bug Fix -* `docusaurus-mdx-loader`, `docusaurus-theme-classic` - * [#1992](https://github.com/facebook/docusaurus/pull/1992) fix(v2): static phrasing content should be rendered correctly in TOC ([@endiliey](https://github.com/endiliey)) -* `docusaurus-theme-classic` - * [#1999](https://github.com/facebook/docusaurus/pull/1999) fix(v2): remove hashbang when click on category ([@lex111](https://github.com/lex111)) - * [#1962](https://github.com/facebook/docusaurus/pull/1962) fix(v2): make not clickable post title on post item page ([@lex111](https://github.com/lex111)) - * [#1980](https://github.com/facebook/docusaurus/pull/1980) fix(v2): remove invalid label attribute of footer links ([@lex111](https://github.com/lex111)) - * [#1978](https://github.com/facebook/docusaurus/pull/1978) fix(v2): use regular div instead of main tag for wrapper layout page ([@lex111](https://github.com/lex111)) - * [#1975](https://github.com/facebook/docusaurus/pull/1975) fix(v2): move header inside article tag in doc page ([@lex111](https://github.com/lex111)) - * [#1974](https://github.com/facebook/docusaurus/pull/1974) fix(v2): remove invalid attributes of nav links ([@lex111](https://github.com/lex111)) - * [#1963](https://github.com/facebook/docusaurus/pull/1963) fix(v2): remove empty containers when no data in blog pages ([@lex111](https://github.com/lex111)) - * [#1966](https://github.com/facebook/docusaurus/pull/1966) fix(v2): remove duplicate meta tags ([@lex111](https://github.com/lex111)) -* `docusaurus-plugin-content-docs` - * [#1994](https://github.com/facebook/docusaurus/pull/1994) fix(v2): throw error if first level item of a sidebar is not category ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-mdx-loader`, `docusaurus-theme-classic` + - [#1992](https://github.com/facebook/docusaurus/pull/1992) fix(v2): static phrasing content should be rendered correctly in TOC ([@endiliey](https://github.com/endiliey)) +- `docusaurus-theme-classic` + - [#1999](https://github.com/facebook/docusaurus/pull/1999) fix(v2): remove hashbang when click on category ([@lex111](https://github.com/lex111)) + - [#1962](https://github.com/facebook/docusaurus/pull/1962) fix(v2): make not clickable post title on post item page ([@lex111](https://github.com/lex111)) + - [#1980](https://github.com/facebook/docusaurus/pull/1980) fix(v2): remove invalid label attribute of footer links ([@lex111](https://github.com/lex111)) + - [#1978](https://github.com/facebook/docusaurus/pull/1978) fix(v2): use regular div instead of main tag for wrapper layout page ([@lex111](https://github.com/lex111)) + - [#1975](https://github.com/facebook/docusaurus/pull/1975) fix(v2): move header inside article tag in doc page ([@lex111](https://github.com/lex111)) + - [#1974](https://github.com/facebook/docusaurus/pull/1974) fix(v2): remove invalid attributes of nav links ([@lex111](https://github.com/lex111)) + - [#1963](https://github.com/facebook/docusaurus/pull/1963) fix(v2): remove empty containers when no data in blog pages ([@lex111](https://github.com/lex111)) + - [#1966](https://github.com/facebook/docusaurus/pull/1966) fix(v2): remove duplicate meta tags ([@lex111](https://github.com/lex111)) +- `docusaurus-plugin-content-docs` + - [#1994](https://github.com/facebook/docusaurus/pull/1994) fix(v2): throw error if first level item of a sidebar is not category ([@endiliey](https://github.com/endiliey)) #### :nail_care: Polish -* `docusaurus-theme-search-algolia` - * [#2001](https://github.com/facebook/docusaurus/pull/2001) fix(v2): improve UI of search ([@lex111](https://github.com/lex111)) -* `docusaurus-theme-classic` - * [#1991](https://github.com/facebook/docusaurus/pull/1991) fix(v2): remove accessible anchors via keyboard ([@lex111](https://github.com/lex111)) - * [#1987](https://github.com/facebook/docusaurus/pull/1987) refactor(v2): replace h1 tag with h2 in blog list pages ([@lex111](https://github.com/lex111)) - * [#1981](https://github.com/facebook/docusaurus/pull/1981) fix(v2): use tag time for showing last update of doc item ([@lex111](https://github.com/lex111)) - * [#1977](https://github.com/facebook/docusaurus/pull/1977) feat(v2): add aria-label to read more links for a11y ([@lex111](https://github.com/lex111)) - * [#1964](https://github.com/facebook/docusaurus/pull/1964) fix(v2): use tag time for showing post item date ([@lex111](https://github.com/lex111)) -* `docusaurus-plugin-content-docs` - * [#1994](https://github.com/facebook/docusaurus/pull/1994) fix(v2): throw error if first level item of a sidebar is not category ([@endiliey](https://github.com/endiliey)) -* Other - * [#1986](https://github.com/facebook/docusaurus/pull/1986) fix(v2): remove obsolete iframe attributes ([@lex111](https://github.com/lex111)) -* `docusaurus-init` - * [#1982](https://github.com/facebook/docusaurus/pull/1982) feat(v2): add FB link to footer ([@lex111](https://github.com/lex111)) -* `docusaurus-plugin-content-blog` - * [#1968](https://github.com/facebook/docusaurus/pull/1968) refactor(v2): simplify blog truncate function ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-theme-search-algolia` + - [#2001](https://github.com/facebook/docusaurus/pull/2001) fix(v2): improve UI of search ([@lex111](https://github.com/lex111)) +- `docusaurus-theme-classic` + - [#1991](https://github.com/facebook/docusaurus/pull/1991) fix(v2): remove accessible anchors via keyboard ([@lex111](https://github.com/lex111)) + - [#1987](https://github.com/facebook/docusaurus/pull/1987) refactor(v2): replace h1 tag with h2 in blog list pages ([@lex111](https://github.com/lex111)) + - [#1981](https://github.com/facebook/docusaurus/pull/1981) fix(v2): use tag time for showing last update of doc item ([@lex111](https://github.com/lex111)) + - [#1977](https://github.com/facebook/docusaurus/pull/1977) feat(v2): add aria-label to read more links for a11y ([@lex111](https://github.com/lex111)) + - [#1964](https://github.com/facebook/docusaurus/pull/1964) fix(v2): use tag time for showing post item date ([@lex111](https://github.com/lex111)) +- `docusaurus-plugin-content-docs` + - [#1994](https://github.com/facebook/docusaurus/pull/1994) fix(v2): throw error if first level item of a sidebar is not category ([@endiliey](https://github.com/endiliey)) +- Other + - [#1986](https://github.com/facebook/docusaurus/pull/1986) fix(v2): remove obsolete iframe attributes ([@lex111](https://github.com/lex111)) +- `docusaurus-init` + - [#1982](https://github.com/facebook/docusaurus/pull/1982) feat(v2): add FB link to footer ([@lex111](https://github.com/lex111)) +- `docusaurus-plugin-content-blog` + - [#1968](https://github.com/facebook/docusaurus/pull/1968) refactor(v2): simplify blog truncate function ([@endiliey](https://github.com/endiliey)) #### :memo: Documentation -* Other - * [#1988](https://github.com/facebook/docusaurus/pull/1988) docs(v2): fix syntax highlighting for YML code blocks ([@lex111](https://github.com/lex111)) - * [#1976](https://github.com/facebook/docusaurus/pull/1976) docs(v2): Add section to blog document about feed location ([@vinnytheviking](https://github.com/vinnytheviking)) - * [#1970](https://github.com/facebook/docusaurus/pull/1970) docs(v2): update configureWebpack utility functions ([@jamiedavenport](https://github.com/jamiedavenport)) -* `docusaurus-1.x` - * [#1961](https://github.com/facebook/docusaurus/pull/1961) docs(v1): remove exclusive language ([@ericcarboni](https://github.com/ericcarboni)) + +- Other + - [#1988](https://github.com/facebook/docusaurus/pull/1988) docs(v2): fix syntax highlighting for YML code blocks ([@lex111](https://github.com/lex111)) + - [#1976](https://github.com/facebook/docusaurus/pull/1976) docs(v2): Add section to blog document about feed location ([@vinnytheviking](https://github.com/vinnytheviking)) + - [#1970](https://github.com/facebook/docusaurus/pull/1970) docs(v2): update configureWebpack utility functions ([@jamiedavenport](https://github.com/jamiedavenport)) +- `docusaurus-1.x` + - [#1961](https://github.com/facebook/docusaurus/pull/1961) docs(v1): remove exclusive language ([@ericcarboni](https://github.com/ericcarboni)) #### :house: Internal -* Other - * [#2002](https://github.com/facebook/docusaurus/pull/2002) fix(v2): fix browser window menu icon on smaller screen ([@lex111](https://github.com/lex111)) - * [#1986](https://github.com/facebook/docusaurus/pull/1986) fix(v2): remove obsolete iframe attributes ([@lex111](https://github.com/lex111)) -* `docusaurus-init` - * [#1982](https://github.com/facebook/docusaurus/pull/1982) feat(v2): add FB link to footer ([@lex111](https://github.com/lex111)) -* `docusaurus-1.x`, `docusaurus-init-1.x`, `docusaurus-init`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-ideal-image`, `docusaurus-types`, `docusaurus` - * [#1985](https://github.com/facebook/docusaurus/pull/1985) chore(v2): update dependencies ([@endiliey](https://github.com/endiliey)) + +- Other + - [#2002](https://github.com/facebook/docusaurus/pull/2002) fix(v2): fix browser window menu icon on smaller screen ([@lex111](https://github.com/lex111)) + - [#1986](https://github.com/facebook/docusaurus/pull/1986) fix(v2): remove obsolete iframe attributes ([@lex111](https://github.com/lex111)) +- `docusaurus-init` + - [#1982](https://github.com/facebook/docusaurus/pull/1982) feat(v2): add FB link to footer ([@lex111](https://github.com/lex111)) +- `docusaurus-1.x`, `docusaurus-init-1.x`, `docusaurus-init`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-ideal-image`, `docusaurus-types`, `docusaurus` + - [#1985](https://github.com/facebook/docusaurus/pull/1985) chore(v2): update dependencies ([@endiliey](https://github.com/endiliey)) #### :running_woman: Performance -* `docusaurus` - * [#1979](https://github.com/facebook/docusaurus/pull/1979) perf(v2): reduce main bundle size by using es5 if possible ([@endiliey](https://github.com/endiliey)) + +- `docusaurus` + - [#1979](https://github.com/facebook/docusaurus/pull/1979) perf(v2): reduce main bundle size by using es5 if possible ([@endiliey](https://github.com/endiliey)) #### Committers: 6 + - Alexey Pyltsyn ([@lex111](https://github.com/lex111)) - Endi ([@endiliey](https://github.com/endiliey)) - Eric Carboni ([@ericcarboni](https://github.com/ericcarboni)) @@ -249,36 +281,44 @@ For example, if you've swizzled `@theme/DocItem`. You'll have to update ## 2.0.0-alpha.34 #### :rocket: New Feature -* `docusaurus-theme-classic` - * [#1956](https://github.com/facebook/docusaurus/pull/1956) feat(v2): add ability hide dark mode toggle ([@lex111](https://github.com/lex111)) + +- `docusaurus-theme-classic` + - [#1956](https://github.com/facebook/docusaurus/pull/1956) feat(v2): add ability hide dark mode toggle ([@lex111](https://github.com/lex111)) #### :boom: Breaking Change -* `docusaurus-plugin-content-docs` - * [#1958](https://github.com/facebook/docusaurus/pull/1958) breaking(v2): editUrl should point to website instead of docsDir ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-plugin-content-docs` + - [#1958](https://github.com/facebook/docusaurus/pull/1958) breaking(v2): editUrl should point to website instead of docsDir ([@endiliey](https://github.com/endiliey)) #### :bug: Bug Fix -* `docusaurus-theme-classic` - * [#1959](https://github.com/facebook/docusaurus/pull/1959) fix(v2): useTOC hooks should not be called in each nested children ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-theme-classic` + - [#1959](https://github.com/facebook/docusaurus/pull/1959) fix(v2): useTOC hooks should not be called in each nested children ([@endiliey](https://github.com/endiliey)) #### :nail_care: Polish -* `docusaurus-plugin-content-docs`, `docusaurus` - * [#1957](https://github.com/facebook/docusaurus/pull/1957) refactor(v2): avoid synchronous/ blocking operation when possible ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-plugin-content-docs`, `docusaurus` + - [#1957](https://github.com/facebook/docusaurus/pull/1957) refactor(v2): avoid synchronous/ blocking operation when possible ([@endiliey](https://github.com/endiliey)) #### :memo: Documentation -* [#1953](https://github.com/facebook/docusaurus/pull/1953) fix(v2): update Infima website URL ([@yangshun](https://github.com/yangshun)) + +- [#1953](https://github.com/facebook/docusaurus/pull/1953) fix(v2): update Infima website URL ([@yangshun](https://github.com/yangshun)) #### :house: Internal -* `docusaurus-1.x`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-search-algolia`, `docusaurus-types`, `docusaurus-utils`, `docusaurus` - * [#1955](https://github.com/facebook/docusaurus/pull/1955) chore: bump dev dependencies ([@endiliey](https://github.com/endiliey)) -* Other - * [#1952](https://github.com/facebook/docusaurus/pull/1952) chore(v2): add lerna-changelog ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-1.x`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-search-algolia`, `docusaurus-types`, `docusaurus-utils`, `docusaurus` + - [#1955](https://github.com/facebook/docusaurus/pull/1955) chore: bump dev dependencies ([@endiliey](https://github.com/endiliey)) +- Other + - [#1952](https://github.com/facebook/docusaurus/pull/1952) chore(v2): add lerna-changelog ([@endiliey](https://github.com/endiliey)) #### :running_woman: Performance -* `docusaurus-plugin-content-docs`, `docusaurus-utils`, `docusaurus` - * [#1951](https://github.com/facebook/docusaurus/pull/1951) perf(v2): skip runtime fileHash cache in prod & get timestamp asynchronously ([@endiliey](https://github.com/endiliey)) - * [#1950](https://github.com/facebook/docusaurus/pull/1950) perf(v2): more efficient hot reload & consistent filegen ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-plugin-content-docs`, `docusaurus-utils`, `docusaurus` + - [#1951](https://github.com/facebook/docusaurus/pull/1951) perf(v2): skip runtime fileHash cache in prod & get timestamp asynchronously ([@endiliey](https://github.com/endiliey)) + - [#1950](https://github.com/facebook/docusaurus/pull/1950) perf(v2): more efficient hot reload & consistent filegen ([@endiliey](https://github.com/endiliey)) #### Committers: 3 + - Alexey Pyltsyn ([@lex111](https://github.com/lex111)) - Endi ([@endiliey](https://github.com/endiliey)) - Yangshun Tay ([@yangshun](https://github.com/yangshun)) @@ -286,9 +326,10 @@ For example, if you've swizzled `@theme/DocItem`. You'll have to update ## 2.0.0-alpha.33 ### Features + - Table of contents is now highlighted depending on current active headings. (thanks to awesome @SantiagoGdaR) [#1896](https://github.com/facebook/docusaurus/pull/1896) - Official blog plugin can now generate feed for blog posts. (thanks to awesome @moozzyk) [#1916](https://github.com/facebook/docusaurus/pull/1916) -- **BREAKING** `prismTheme` is renamed to `theme` as part new `prism` object in `themeConfig` field in your `docusaurus.config.js`. Eg: +- **BREAKING** `prismTheme` is renamed to `theme` as part new `prism` object in `themeConfig` field in your `docusaurus.config.js`. Eg: ```diff themeConfig: { - prismTheme: require('prism-react-renderer/themes/dracula'), @@ -297,10 +338,10 @@ For example, if you've swizzled `@theme/DocItem`. You'll have to update + }, }, ``` -- Added new `prism` option `defaultLanguage` that is used if the language is not specified in code blocks. -[#1910](https://github.com/facebook/docusaurus/pull/1910) +- Added new `prism` option `defaultLanguage` that is used if the language is not specified in code blocks. [#1910](https://github.com/facebook/docusaurus/pull/1910) ### Fixes + - Fix babel/env not picking the correct browserslist configuration during development. When running `docusaurus start`, `process.env.NODE_ENV` is now consistently set to `development`. - Ensure routes config generation to be more consistent in ordering. Nested routes should be placed last in routes.js. This will allow user to create `src/pages/docs.js` to create custom docs page for `/docs` or even `src/pages/docs/super.js` to create page for `/docs/super/`; - Fix watcher does not trigger reload on windows. @@ -308,6 +349,7 @@ For example, if you've swizzled `@theme/DocItem`. You'll have to update - Add minor padding to docs container so that hash-link won't be cut off. ### Others + - Misc dependency upgrades. - Stability improvement (more tests) & refactoring on docs plugin to prevent regression. @@ -316,6 +358,7 @@ For example, if you've swizzled `@theme/DocItem`. You'll have to update ### Features - Add `` component for client side redirect. Example Usage: + ```js import React from 'react'; import {Redirect} from '@docusaurus/router'; diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fb52b376aae..a3b715a9d969 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,47 +7,55 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a ## [1.14.3] - 2019-12-01 #### :bug: Bug Fix -* `docusaurus-1.x` - * [#2063](https://github.com/facebook/docusaurus/pull/2063) fix: transpile static js to IE 10 ([@JLHwung](https://github.com/JLHwung)) + +- `docusaurus-1.x` + - [#2063](https://github.com/facebook/docusaurus/pull/2063) fix: transpile static js to IE 10 ([@JLHwung](https://github.com/JLHwung)) #### :house: Internal -* `docusaurus-1.x` - * [#2029](https://github.com/facebook/docusaurus/pull/2029) chore: bump deps and remove unused deps ([@endiliey](https://github.com/endiliey)) + +- `docusaurus-1.x` + - [#2029](https://github.com/facebook/docusaurus/pull/2029) chore: bump deps and remove unused deps ([@endiliey](https://github.com/endiliey)) #### Committers: 2 + - Endi ([@endiliey](https://github.com/endiliey)) - HuΓ‘ng JΓΉnliΓ ng ([@JLHwung](https://github.com/JLHwung)) ## [1.14.2] - 2019-11-22 #### :bug: Bug Fix -* `docusaurus-1.x` - * [#2028](https://github.com/facebook/docusaurus/pull/2028) fix(v1): apply negative margin to docs heading only ([@yangshun](https://github.com/yangshun)) + +- `docusaurus-1.x` + - [#2028](https://github.com/facebook/docusaurus/pull/2028) fix(v1): apply negative margin to docs heading only ([@yangshun](https://github.com/yangshun)) #### :memo: Documentation -* [#2026](https://github.com/facebook/docusaurus/pull/2026) docs(v1): showcase user Channelize.io ([@gauravberiwal](https://github.com/gauravberiwal)) + +- [#2026](https://github.com/facebook/docusaurus/pull/2026) docs(v1): showcase user Channelize.io ([@gauravberiwal](https://github.com/gauravberiwal)) ## [1.14.1] - 2019-11-21 #### :bug: Bug Fix -* [#2022](https://github.com/facebook/docusaurus/pull/2022) fix(v1): markdown content and toc should render the same ([@endiliey](https://github.com/endiliey)) -* [#2020](https://github.com/facebook/docusaurus/pull/2020) fix(v1): docusaurus-start should work even if path contain 'pages' word ([@endiliey](https://github.com/endiliey)) -* [#2019](https://github.com/facebook/docusaurus/pull/2019) fix(v1): consistent slug & hash-link generation ([@endiliey](https://github.com/endiliey)) -* [#1869](https://github.com/facebook/docusaurus/pull/1869) fix(v1): fix page title render issue when referred by search result ([@parvezakkas](https://github.com/parvezakkas)) -* [#1895](https://github.com/facebook/docusaurus/pull/1895) fix(v1): mobile safari search input misalignment in header ([@sarneeh](https://github.com/sarneeh)) -* [#1871](https://github.com/facebook/docusaurus/pull/1871) misc(v1): use primary color for hovered items in table of contents ([@blitz137](https://github.com/blitz137)) + +- [#2022](https://github.com/facebook/docusaurus/pull/2022) fix(v1): markdown content and toc should render the same ([@endiliey](https://github.com/endiliey)) +- [#2020](https://github.com/facebook/docusaurus/pull/2020) fix(v1): docusaurus-start should work even if path contain 'pages' word ([@endiliey](https://github.com/endiliey)) +- [#2019](https://github.com/facebook/docusaurus/pull/2019) fix(v1): consistent slug & hash-link generation ([@endiliey](https://github.com/endiliey)) +- [#1869](https://github.com/facebook/docusaurus/pull/1869) fix(v1): fix page title render issue when referred by search result ([@parvezakkas](https://github.com/parvezakkas)) +- [#1895](https://github.com/facebook/docusaurus/pull/1895) fix(v1): mobile safari search input misalignment in header ([@sarneeh](https://github.com/sarneeh)) +- [#1871](https://github.com/facebook/docusaurus/pull/1871) misc(v1): use primary color for hovered items in table of contents ([@blitz137](https://github.com/blitz137)) #### :house: Internal -* [#1920](https://github.com/facebook/docusaurus/pull/1920) misc(v1): use Node.js lts version for docker ([@gengjiawen](https://github.com/gengjiawen)) + +- [#1920](https://github.com/facebook/docusaurus/pull/1920) misc(v1): use Node.js lts version for docker ([@gengjiawen](https://github.com/gengjiawen)) #### :memo: Documentation -* [#1998](https://github.com/facebook/docusaurus/pull/1998) docs(v1): showcase user collective ([@kenning](https://github.com/kenning)) -* [#1961](https://github.com/facebook/docusaurus/pull/1961) docs(v1): remove exclusive language ([@ericcarboni](https://github.com/ericcarboni)) -* [#1873](https://github.com/facebook/docusaurus/pull/1873) docs: showcase user Amphora ([@xtellurian](https://github.com/xtellurian)) -* [#1918](https://github.com/facebook/docusaurus/pull/1918) docs(v1): showcase user Reactive Interaction Gateway ([@mmacai](https://github.com/mmacai)) -* [#1911](https://github.com/facebook/docusaurus/pull/1911) docs: updating configcat user link ([@mr-sige](https://github.com/mr-sige)) -* [#1902](https://github.com/facebook/docusaurus/pull/1902) misc: update URLs to non-HTML versions ([@ikrydev](https://github.com/ikrydev)) -* [#1901](https://github.com/facebook/docusaurus/pull/1901) docs(v1): remove broken link for user Vasern ([@ikrydev](https://github.com/ikrydev)) + +- [#1998](https://github.com/facebook/docusaurus/pull/1998) docs(v1): showcase user collective ([@kenning](https://github.com/kenning)) +- [#1961](https://github.com/facebook/docusaurus/pull/1961) docs(v1): remove exclusive language ([@ericcarboni](https://github.com/ericcarboni)) +- [#1873](https://github.com/facebook/docusaurus/pull/1873) docs: showcase user Amphora ([@xtellurian](https://github.com/xtellurian)) +- [#1918](https://github.com/facebook/docusaurus/pull/1918) docs(v1): showcase user Reactive Interaction Gateway ([@mmacai](https://github.com/mmacai)) +- [#1911](https://github.com/facebook/docusaurus/pull/1911) docs: updating configcat user link ([@mr-sige](https://github.com/mr-sige)) +- [#1902](https://github.com/facebook/docusaurus/pull/1902) misc: update URLs to non-HTML versions ([@ikrydev](https://github.com/ikrydev)) +- [#1901](https://github.com/facebook/docusaurus/pull/1901) docs(v1): remove broken link for user Vasern ([@ikrydev](https://github.com/ikrydev)) ## [1.14.0] - 2019-10-20 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 16cc0abdfb79..441789b77818 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,8 +4,8 @@ The [Open Source Guides](https://opensource.guide/) website has a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. Contributors and people new to open source alike will find the following guides especially useful: -* [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) -* [Building Welcoming Communities](https://opensource.guide/building-community/) +- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) +- [Building Welcoming Communities](https://opensource.guide/building-community/) ## [Code of Conduct](https://code.fb.com/codeofconduct) diff --git a/README.md b/README.md index 9c7d1c8b234a..efdddb141805 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ Read our [contributing guide](https://github.com/facebook/docusaurus/blob/master ### Beginner Friendly Bugs -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 might contain smaller issues to tackle first. This is a great place to get started. +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 might contain smaller issues to tackle first. This is a great place to get started. ## Contact diff --git a/admin/extending-remarkable.md b/admin/extending-remarkable.md index 2149a9896f4f..6332a3937283 100644 --- a/admin/extending-remarkable.md +++ b/admin/extending-remarkable.md @@ -65,18 +65,35 @@ md.renderer.rules.heading_close = function(tokens, idx /*, options, env */) { That's pretty straightforward: whenever these tokens are found, we render a `` or `` HTML tag, where N is the `hLevel` for this heading. That would result in `

Hi there

` being output. But what we want is something closer to this: ```html -

Hi there #

+

+ Hi there + # +

``` In that case, we need to override our heading rules like so: ```js md.renderer.rules.heading_open = function(tokens, idx /*, options, env */) { - return '' + ''; + return ( + '' + + '' + ); }; md.renderer.rules.heading_close = function(tokens, idx /*, options, env */) { - return ' #' + '\n'; + return ( + ' #' + + '\n' + ); }; ``` @@ -89,11 +106,25 @@ We now need to tell Remarkable to use our extension. We can wrap our rules in a ```js function anchors(md) { md.renderer.rules.heading_open = function(tokens, idx /*, options, env */) { - return '' + ''; + return ( + '' + + '' + ); }; md.renderer.rules.heading_close = function(tokens, idx /*, options, env */) { - return ' #' + '\n'; + return ( + ' #' + + '\n' + ); }; } ``` diff --git a/admin/prerelease.md b/admin/prerelease.md index 4e84e349a33b..a2d8d584befb 100644 --- a/admin/prerelease.md +++ b/admin/prerelease.md @@ -24,4 +24,4 @@ $ git fetch upstream && git checkout master && git merge upstream/master 3. Run `bash scripts/prerelease.sh`. 4. Create your pull request on GitHub. -pull request \ No newline at end of file +pull request diff --git a/docs/api-commands.md b/docs/api-commands.md index 42ae1ed8fb17..850902b03d0b 100644 --- a/docs/api-commands.md +++ b/docs/api-commands.md @@ -5,8 +5,8 @@ title: CLI Commands Docusaurus provides a set of scripts to help you generate, serve, and deploy your website. These scripts can be invoked with the `run` command when using Yarn or npm. Some common commands are: -* [`yarn run start`](api-commands.md#docusaurus-start-port-number): build and serve the website from a local server -* [`yarn run examples`](api-commands.md#docusaurus-examples): create example configuration files +- [`yarn run start`](api-commands.md#docusaurus-start-port-number): build and serve the website from a local server +- [`yarn run examples`](api-commands.md#docusaurus-examples): create example configuration files ## Running from the command line @@ -56,10 +56,10 @@ Docusaurus provides some default mappings to allow you to run commands following Alias: `build`. -| Options | Default | Description | -| -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | +| Options | Default | Description | +| --- | --- | --- | | `--skip-image-compression` | `false` | Skip compression of image assets. You usually won't want to skip this unless your images have already been optimized. | -| `--skip-next-release` | `false` | Skip the next release documents when versioning is enabled. This will not build HTML files for documents in `/docs` directory.| +| `--skip-next-release` | `false` | Skip the next release documents when versioning is enabled. This will not build HTML files for documents in `/docs` directory. | Generates the static website, applying translations if necessary. Useful for building the website prior to deployment. @@ -71,9 +71,9 @@ See also [`docusaurus-start`](api-commands.md#docusaurus-start). Alias: `examples` -| Arguments | Default | Description | -| ----------- | ------- | ---------------------------------------------------------------------------------------------------- | -| `` | - | Specify a feature `translations` or `versions` to generate the extra example files for that feature. | +| Arguments | Default | Description | +| --- | --- | --- | +| `` | - | Specify a feature `translations` or `versions` to generate the extra example files for that feature. | **Example** @@ -93,8 +93,8 @@ Alias: `publish-gh-pages` The following environment variables are 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. +- `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. **Example** @@ -104,13 +104,13 @@ GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages The following environment variables are [set by CircleCI](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. +- `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". +- `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". You can learn more about configuring automatic deployments with CircleCI in the [Publishing guide](getting-started-publishing.md). @@ -143,11 +143,11 @@ Alias: `start`. This command will build the static website, apply translations if necessary, and then start a local server. -| Options | Default | Description | -| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `--port ` | `3000` | The website will be served from port 3000 by default, but if the port is taken up, Docusaurus will attempt to find an available one. | -|`--host `|`localhost`|Specify a host to use. E.g., if you want your server to be accessible externally, you can use --host 0.0.0.0.| -| `--watch` | - | Whether to watch the files and live reload the page when files are changed. Defaults to true. Disable this by using `--no-watch`. | +| Options | Default | Description | +| --- | --- | --- | +| `--port ` | `3000` | The website will be served from port 3000 by default, but if the port is taken up, Docusaurus will attempt to find an available one. | +| `--host ` | `localhost` | Specify a host to use. E.g., if you want your server to be accessible externally, you can use --host 0.0.0.0. | +| `--watch` | - | Whether to watch the files and live reload the page when files are changed. Defaults to true. Disable this by using `--no-watch`. | You can specify the browser application to be opened by setting the `BROWSER` environment variable before the command, e.g.: diff --git a/docs/api-doc-markdown.md b/docs/api-doc-markdown.md index f1408a455dd3..e92e4a812824 100644 --- a/docs/api-doc-markdown.md +++ b/docs/api-doc-markdown.md @@ -25,6 +25,7 @@ id: doc1 title: My Document sidebar_label: Document --- + ``` Versioned documents have their ids altered to include the version number when they get copied. The new `id` is `version-${version}-${id}` where `${version}` is the version number of that document and `${id}` is the original `id`. Additionally, versioned documents get an added `original_id` field with the original document id. @@ -38,6 +39,7 @@ title: My Document sidebar_label: Document original_id: doc1 --- + ``` `custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from optional fields of `siteConfig.js`. See [siteConfig.js](api-site-config.md) docs for more information. @@ -50,6 +52,7 @@ id: doc-markdown title: Markdown Features custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md --- + ``` ### Blog Posts @@ -73,6 +76,7 @@ author: Frank Li authorURL: http://twitter.com/franchementli authorFBID: 100002976521003 --- + ``` ## Extra Features @@ -130,7 +134,6 @@ will lead to a table of contents of the functions: and each function will link to their corresponding sections in the page. - ### Language-specific Code Tabs Display code in multiple programming languages using code tabs. First, mark the start and end of a code tabs group, by using `` and `` respectively in your markdown. Then start each tab with ``. @@ -144,26 +147,30 @@ produces this: + ```js console.log('Hello, world!'); ``` + ```py print('Hello, world!') ``` + ```C #include int main() { - printf("Hello World!"); - return 0; + printf("Hello World!"); + return 0; } ``` + ```Pascal program HelloWorld; begin diff --git a/docs/api-pages.md b/docs/api-pages.md index 5ac76a3384fd..f636c29b7652 100644 --- a/docs/api-pages.md +++ b/docs/api-pages.md @@ -71,8 +71,8 @@ module.exports = MyPage; This will be translated to a description metadata tag on the generated HTML. ```html - - + + ``` ## Page Require Paths @@ -107,11 +107,11 @@ A React container component using Docusaurus styles. Has optional padding and ba **Props** -| Prop | Type | Default | Description | -| ------------ | ---------------------------------------------------------- | ------- | ----------------------------------- | -| `padding` | Array of `'all'`, `'bottom'`, `'left'`, `'right'`, `'top'` | `[]` | Positions of the padding. | -| `background` | One of `'dark'`, `'highlight'`, `'light'` | `null` | Background styling of the element. | -| `className` | String | - | Custom class to add to the element. | +| Prop | Type | Default | Description | +| --- | --- | --- | --- | +| `padding` | Array of `'all'`, `'bottom'`, `'left'`, `'right'`, `'top'` | `[]` | Positions of the padding. | +| `background` | One of `'dark'`, `'highlight'`, `'light'` | `null` | Background styling of the element. | +| `className` | String | - | Custom class to add to the element. | **Example** @@ -130,23 +130,23 @@ A React component to organize text and images. **Props** -| Prop | Type | Default | Description | -| ----------- | ----------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------- | -| `align` | One of `'left'`, `'center'`, `'right'` | `'left'` | Text alignment of content. | -| `layout` | One of `'twoColumn'`, `'threeColumn'`, `'fourColumn'` | `'twoColumn'` | Number of column sections in the `GridBlock`. | -| `className` | String | - | Custom class to add to the element. | -| `contents` | Array of content objects | `[]` | Contents of each section of the GridBlock. Refer to the next table for the fields available on a content object. | +| Prop | Type | Default | Description | +| --- | --- | --- | --- | +| `align` | One of `'left'`, `'center'`, `'right'` | `'left'` | Text alignment of content. | +| `layout` | One of `'twoColumn'`, `'threeColumn'`, `'fourColumn'` | `'twoColumn'` | Number of column sections in the `GridBlock`. | +| `className` | String | - | Custom class to add to the element. | +| `contents` | Array of content objects | `[]` | Contents of each section of the GridBlock. Refer to the next table for the fields available on a content object. | **Content Object** -| Key | Type | Default | Description | -| ------------ | ----------------------------------------------- | -------- | ----------------------------------------------------------------- | -| `title` | String | - | The display title of this section, which is parsed using Markdown | -| `content` | String | - | The text of this section, which is parsed using Markdown | -| `image` | String | - | The path of the display image | -| `imageAlt` | String | - | The text that will be shown in case the image is not available | -| `imageAlign` | One of `'top'`, `'left'`, `'bottom'`, `'right'` | `'left'` | Image alignment relative to the text | -| `imageLink` | String | - | Link destination from clicking the image | +| Key | Type | Default | Description | +| --- | --- | --- | --- | +| `title` | String | - | The display title of this section, which is parsed using Markdown | +| `content` | String | - | The text of this section, which is parsed using Markdown | +| `image` | String | - | The path of the display image | +| `imageAlt` | String | - | The text that will be shown in case the image is not available | +| `imageAlign` | One of `'top'`, `'left'`, `'bottom'`, `'right'` | `'left'` | Image alignment relative to the text | +| `imageLink` | String | - | Link destination from clicking the image | **Example** diff --git a/docs/api-site-config.md b/docs/api-site-config.md index e3288a47ecee..a07be6b3943e 100644 --- a/docs/api-site-config.md +++ b/docs/api-site-config.md @@ -130,8 +130,7 @@ The default version for the site to be shown. If this is not set, the latest ver #### `docsUrl` [string] -The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. -If unset, it is defaulted to `docs`. +The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. If unset, it is defaulted to `docs`. #### `disableHeaderTitle` [boolean] diff --git a/docs/getting-started-docker.md b/docs/getting-started-docker.md index a0f914b1a456..3b0dd59d6bf0 100644 --- a/docs/getting-started-docker.md +++ b/docs/getting-started-docker.md @@ -13,13 +13,13 @@ To run the local web server: 1. **Build the docker image** -- Enter the folder where you have Docusaurus installed. Run `docker build -t docusaurus-doc .` - Once the build phase finishes, you can verify the image exists by running `docker images`. + Once the build phase finishes, you can verify the image exists by running `docker images`. - > We now include a `Dockerfile` when you install Docusaurus. + > We now include a `Dockerfile` when you install Docusaurus. 2. **Run the Docusaurus container** -- To start docker run `docker run --rm -p 3000:3000 docusaurus-doc` - This will start a docker container with the image `docusaurus-doc`. To see more detailed container info run `docker ps` . + This will start a docker container with the image `docusaurus-doc`. To see more detailed container info run `docker ps` . ## Use docker-compose @@ -36,8 +36,9 @@ Using Compose is a three-step process: 3. Run `docker-compose up` and Compose starts and runs your entire app. We include a basic `docker-compose.yml` in your project: -``` yml -version: "3" + +```yml +version: '3' services: docusaurus: @@ -55,7 +56,6 @@ services: - ./website/sidebars.json:/app/website/sidebars.json - ./website/siteConfig.js:/app/website/siteConfig.js working_dir: /app/website - ``` To run a local web server with `docker-compose` run `docker-compose up`. diff --git a/docs/getting-started-installation.md b/docs/getting-started-installation.md index fef732b4e350..63c3eadc423d 100644 --- a/docs/getting-started-installation.md +++ b/docs/getting-started-installation.md @@ -16,9 +16,7 @@ We have created a helpful script that will get all of the infrastructure set up 1. Create a project, if none exists, and change your directory to this project's root. - You will be creating the docs in this directory. The root directory may - contain other files. The Docusaurus installation script will create two new - directories: `docs` and `website`. + You will be creating the docs in this directory. The root directory may contain other files. The Docusaurus installation script will create two new directories: `docs` and `website`. > Commonly, either an existing or newly created GitHub project will be the location for your Docusaurus site, but that is not mandatory to use Docusaurus. @@ -61,15 +59,11 @@ root-directory ## Running the example website -After running the Docusaurus initialization script, `docusaurus-init` as -described in the [Installation](#installing-docusaurus) section, you will have a -runnable, example website to use as your site's base. To run: +After running the Docusaurus initialization script, `docusaurus-init` as described in the [Installation](#installing-docusaurus) section, you will have a runnable, example website to use as your site's base. To run: 1. `cd website` -1. From within the `website` directory, run the local web server using - `yarn start` or `npm start`. -1. Load the example site at http://localhost:3000 if it did not already open - automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which. +1. From within the `website` directory, run the local web server using `yarn start` or `npm start`. +1. Load the example site at http://localhost:3000 if it did not already open automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which. You should see the example site loaded in your web browser. There's also a LiveReload server running and any changes made to the docs and files in the `website` directory will cause the page to refresh. A randomly generated primary and secondary theme color will be picked for you. diff --git a/docs/getting-started-publishing.md b/docs/getting-started-publishing.md index e14d83933195..25997d47c7dc 100644 --- a/docs/getting-started-publishing.md +++ b/docs/getting-started-publishing.md @@ -25,10 +25,10 @@ At this point, you can grab all of the files inside the `website/build` director ### Hosting on a Service: -* [ZEIT Now](#using-zeit-now) -* [GitHub Pages](#using-github-pages) -* [Netlify](#hosting-on-netlify) -* [Render](#hosting-on-render) +- [ZEIT Now](#using-zeit-now) +- [GitHub Pages](#using-github-pages) +- [Netlify](#hosting-on-netlify) +- [Render](#hosting-on-render) ### Using ZEIT Now @@ -60,17 +60,16 @@ Docusaurus was designed to work really well with one of the most popular hosting > Even if your repository is private, anything published to a `gh-pages` branch will be [public](https://help.github.com/articles/user-organization-and-project-pages/). -__Note:__ When you deploy as user/organization page, the publish script will deploy these sites to the root of the __`master`__ branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in __another branch of the _username_.github.io repo__ (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code). +**Note:** When you deploy as user/organization page, the publish script will deploy these sites to the root of the **`master`** branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in **another branch of the _username_.github.io repo** (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code). 2. You will need to modify the file `website/siteConfig.js` and add the required parameters. -| Name | Description | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. | -| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". | -| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" | -| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | - +| Name | Description | +| --- | --- | +| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. | +| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". | +| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" | +| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | ```js const siteConfig = { @@ -85,19 +84,20 @@ const siteConfig = { In case you want to deploy as a user or organization site, specify the project name as `.github.io` or `.github.io`. E.g. If your GitHub username is "user42" then _user42.github.io_, or in the case of an organization name of "org123", it will be _org123.github.io_. -__Note:__ Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images. +**Note:** Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images. > While we recommend setting the `projectName` and `organizationName` in `siteConfig.js`, you can also use environment variables `ORGANIZATION_NAME` and `PROJECT_NAME`. 3. Now you have to specify the git user as an environment variable, and run the script [`publish-gh-pages`](./api-commands.md#docusaurus-publish) -| Name | Description | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| Name | Description | +| --- | --- | | `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. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. | To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. **Bash** + ```bash GIT_USER= \ CURRENT_BRANCH=master \ @@ -106,15 +106,16 @@ GIT_USER= \ ``` **Windows** + ```batch cmd /C "set GIT_USER= && set CURRENT_BRANCH=master && set USE_SSH=true && yarn run publish-gh-pages" ``` There are also two optional parameters that are set as environment variables: -| Name | Description | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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. | +| Name | Description | +| --- | --- | +| `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. | If you run into issues related to SSH keys, visit [GitHub's authentication documentation](https://help.github.com/articles/connecting-to-github-with-ssh/). @@ -195,14 +196,16 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications). You can work around this by: -- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. -e.g. + +- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. e.g. + ```bash CUSTOM_COMMIT_MESSAGE="[skip ci]" \ yarn run publish-gh-pages # or `npm run publish-gh-pages` ``` - Alternatively, you can work around this by creating a basic CircleCI config with the following contents: + ```yaml # CircleCI 2.0 Config File # This config file will prevent tests from being run on the gh-pages branch. @@ -258,8 +261,8 @@ Steps to configure your Docusaurus-powered site on Netlify. 1. Select the branch to deploy. Default is `master` 1. Configure your build steps: - * For your build command enter: `cd website; npm install; npm run build;` - * For publish directory: `website/build/` (use the `projectName` from your `siteConfig`) + - For your build command enter: `cd website; npm install; npm run build;` + - For publish directory: `website/build/` (use the `projectName` from your `siteConfig`) 1. Click **Deploy site** @@ -273,22 +276,22 @@ Render offers free [static site](https://render.com/docs/static-sites) hosting w 2. Select the branch to deploy. The default is `master`. -2. Enter the following values during creation. +3. Enter the following values during creation. - | Field | Value | - | ------- | ----- | - | **Environment** | `Static Site` | - | **Build Command** | `cd website; yarn install; yarn build` | - | **Publish Directory** | `website/build/` | + | Field | Value | + | --------------------- | -------------------------------------- | + | **Environment** | `Static Site` | + | **Build Command** | `cd website; yarn install; yarn build` | + | **Publish Directory** | `website/build/` | - `projectName` is the value you defined in your `siteConfig.js`. + `projectName` is the value you defined in your `siteConfig.js`. - ```javascript{7} - const siteConfig = { - // ... - projectName: 'your-project-name', - // ... - ``` + ```javascript{7} + const siteConfig = { + // ... + projectName: 'your-project-name', + // ... + ``` That's it! Your app will be live on your Render URL as soon as the build finishes. diff --git a/docs/getting-started-site-creation.md b/docs/getting-started-site-creation.md index 9c60aee26e29..82d3f70cdaad 100644 --- a/docs/getting-started-site-creation.md +++ b/docs/getting-started-site-creation.md @@ -42,7 +42,6 @@ To create a fully functional site, you only need to do a few steps: id: intro title: Getting Started --- - My new content here.. ``` @@ -71,18 +70,22 @@ If you prefer to have your landing page be straight to your documentation, you c 1. Add a [custom static `index.html` page](guides-custom-pages.md#adding-static-pages) in the `website/static` directory with the following contents: ```html - + - - + + Your Site Title Here - If you are not redirected automatically, follow this link. + If you are not redirected automatically, follow this + link. ``` diff --git a/docs/guides-search.md b/docs/guides-search.md index 170e61e8237b..c0b1c3365b2e 100644 --- a/docs/guides-search.md +++ b/docs/guides-search.md @@ -63,7 +63,7 @@ const siteConfig = { ## Customizing the placeholder -If you want to change the placeholder (which defaults to *Search*), add the `placeholder` field in your config. For example, you may want the search bar to display *Ask me something*: +If you want to change the placeholder (which defaults to _Search_), add the `placeholder` field in your config. For example, you may want the search bar to display _Ask me something_: ```js const siteConfig = { diff --git a/docs/guides-translation.md b/docs/guides-translation.md index cc02b80e64dc..f6a6729d9c71 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 `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 @@ -87,11 +87,11 @@ Running the script will generate a `website/i18n/en.json` file containing all th 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` ### Custom Translation Strings @@ -111,7 +111,7 @@ If you want to add additional custom translation strings or override any of the } } }, - "pages-strings" : { + "pages-strings": { "id3": "string3", "id4": "string4" } @@ -128,8 +128,8 @@ Here is an example: "localized-strings": { "translation": "Translations and Localization" }, - "pages-strings" : { - "Help Translate|recruit community translators for your project": "Help Us Translate" + "pages-strings": { + "Help Translate|recruit community translators for your project": "Help Us Translate" } } ``` @@ -177,12 +177,11 @@ Below is an example Crowdin configuration for the respective languages: German, ```yaml project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID api_key_env: CROWDIN_DOCUSAURUS_API_KEY -base_path: "./" +base_path: './' preserve_hierarchy: true files: - - - source: '/docs/**/*.md' + - source: '/docs/**/*.md' translation: '/website/translated_docs/%locale%/**/%original_file_name%' languages_mapping: &anchor locale: diff --git a/docs/tutorial-create-new-site.md b/docs/tutorial-create-new-site.md index 50d16656e4cd..5f448bdcbe81 100644 --- a/docs/tutorial-create-new-site.md +++ b/docs/tutorial-create-new-site.md @@ -64,7 +64,6 @@ The following contents will be created in your current directory. Some example d └── yarn.lock ``` - 3. Run `cd website` to go into the `website` directory. 4. Run `npm start` or `yarn start`. diff --git a/docs/tutorial-publish-site.md b/docs/tutorial-publish-site.md index a23931daa4c3..baa7c2172af6 100644 --- a/docs/tutorial-publish-site.md +++ b/docs/tutorial-publish-site.md @@ -32,7 +32,7 @@ GIT_USER=USERNAME CURRENT_BRANCH=master USE_SSH=true npm run publish-gh-pages # GIT_USER=USERNAME CURRENT_BRANCH=master npm run publish-gh-pages # HTTPS ``` -The HTML files (and other file types) are pushed to the `gh-pages` branch of your repository: https://github.com/USERNAME/docusaurus-tutorial. +The HTML files (and other file types) are pushed to the `gh-pages` branch of your repository: https://github.com/USERNAME/docusaurus-tutorial. 5. Go to https://USERNAME.github.io/docusaurus-tutorial/ and view your site in action! diff --git a/docs/tutorial-setup.md b/docs/tutorial-setup.md index d0f2023ac525..5bbcc225f004 100644 --- a/docs/tutorial-setup.md +++ b/docs/tutorial-setup.md @@ -56,7 +56,7 @@ We highly recommend that you install Yarn, an alternative package manager that h GitHub create repo -5. In Terminal or Git Bash, `cd` to a directory where the local clone will be a subdirectory. +5. In Terminal or Git Bash, `cd` to a directory where the local clone will be a subdirectory. ```sh cd /Users/NAME/doc_projects # macOS example diff --git a/package.json b/package.json index 30ee4b472091..2ad9c365210d 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "postinstall": "yarn tsc", "prettier": "prettier --config .prettierrc --write \"**/*.{js,ts}\"", "prettier:diff": "prettier --config .prettierrc --list-different \"**/*.{js,ts}\"", + "prettier-docs": "prettier --config .prettierrc --write \"**/*.md\"", "lint": "eslint --cache \"**/*.js\"", "lerna": "lerna", "test": "jest", @@ -72,6 +73,9 @@ "*.{ts,tsx}": [ "yarn prettier", "git add" + ], + "*.md": [ + "yarn prettier-docs" ] }, "husky": { diff --git a/packages/docusaurus-1.x/README.md b/packages/docusaurus-1.x/README.md index ba41fa3020ef..45f9621c1858 100644 --- a/packages/docusaurus-1.x/README.md +++ b/packages/docusaurus-1.x/README.md @@ -43,7 +43,7 @@ Read our [contributing guide](https://github.com/facebook/docusaurus/blob/master ### Beginner Friendly Bugs -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 might contain smaller issues to tackle first. This is a great place to get started. +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 might contain smaller issues to tackle first. This is a great place to get started. ## Contact diff --git a/packages/docusaurus-1.x/examples/basics/README.md b/packages/docusaurus-1.x/examples/basics/README.md index 7391779abaaf..10e097ee4c1b 100644 --- a/packages/docusaurus-1.x/examples/basics/README.md +++ b/packages/docusaurus-1.x/examples/basics/README.md @@ -2,11 +2,11 @@ This website was created with [Docusaurus](https://docusaurus.io/). # What's In This Document -* [Get Started in 5 Minutes](#get-started-in-5-minutes) -* [Directory Structure](#directory-structure) -* [Editing Content](#editing-content) -* [Adding Content](#adding-content) -* [Full Documentation](#full-documentation) +- [Get Started in 5 Minutes](#get-started-in-5-minutes) +- [Directory Structure](#directory-structure) +- [Editing Content](#editing-content) +- [Adding Content](#adding-content) +- [Full Documentation](#full-documentation) # Get Started in 5 Minutes @@ -16,6 +16,7 @@ This website was created with [Docusaurus](https://docusaurus.io/). # Install dependencies $ yarn ``` + 2. Run your dev server: ```sh @@ -72,6 +73,7 @@ For more information about docs, click [here](https://docusaurus.io/docs/en/navi Edit blog posts by navigating to `website/blog` and editing the corresponding post: `website/blog/post-to-be-edited.md` + ```markdown --- id: post-needs-edit @@ -121,6 +123,7 @@ For more information about adding new docs, click [here](https://docusaurus.io/d 1. Make sure there is a header link to your blog in `website/siteConfig.js`: `website/siteConfig.js` + ```javascript headerLinks: [ ... @@ -151,6 +154,7 @@ For more information about blog posts, click [here](https://docusaurus.io/docs/e 1. Add links to docs, custom pages or external links by editing the headerLinks field of `website/siteConfig.js`: `website/siteConfig.js` + ```javascript { headerLinks: [ @@ -175,6 +179,7 @@ For more information about the navigation bar, click [here](https://docusaurus.i 1. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element: `website/siteConfig.js` + ```javascript { headerLinks: [ diff --git a/packages/docusaurus-1.x/examples/basics/blog/2017-09-25-testing-rss.md b/packages/docusaurus-1.x/examples/basics/blog/2017-09-25-testing-rss.md index b7ff8129ceb7..13a42f7609ef 100644 --- a/packages/docusaurus-1.x/examples/basics/blog/2017-09-25-testing-rss.md +++ b/packages/docusaurus-1.x/examples/basics/blog/2017-09-25-testing-rss.md @@ -4,8 +4,11 @@ author: Eric Nakagawa authorURL: http://twitter.com/ericnakagawa authorFBID: 661277173 --- + 1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890 This should be truncated. + + This line should never render in XML. diff --git a/packages/docusaurus-1.x/examples/basics/docs/doc3.md b/packages/docusaurus-1.x/examples/basics/docs/doc3.md index bcb9054fc75c..2cc6183cfff3 100644 --- a/packages/docusaurus-1.x/examples/basics/docs/doc3.md +++ b/packages/docusaurus-1.x/examples/basics/docs/doc3.md @@ -2,6 +2,7 @@ id: doc3 title: This is document number 3 --- + Lorem ipsum dolor sit amet, consectetur adipiscing elit. In ac euismod odio, eu consequat dui. Nullam molestie consectetur risus id imperdiet. Proin sodales ornare turpis, non mollis massa ultricies id. Nam at nibh scelerisque, feugiat ante non, dapibus tortor. Vivamus volutpat diam quis tellus elementum bibendum. Praesent semper gravida velit quis aliquam. Etiam in cursus neque. Nam lectus ligula, malesuada et mauris a, bibendum faucibus mi. Phasellus ut interdum felis. Phasellus in odio pulvinar, porttitor urna eget, fringilla lectus. Aliquam sollicitudin est eros. Mauris consectetur quam vitae mauris interdum hendrerit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis et egestas libero, imperdiet faucibus ipsum. Sed posuere eget urna vel feugiat. Vivamus a arcu sagittis, fermentum urna dapibus, congue lectus. Fusce vulputate porttitor nisl, ac cursus elit volutpat vitae. Nullam vitae ipsum egestas, convallis quam non, porta nibh. Morbi gravida erat nec neque bibendum, eu pellentesque velit posuere. Fusce aliquam erat eu massa eleifend tristique. diff --git a/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/getTOC.md b/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/getTOC.md index f56735c17147..6556ee0df113 100644 --- a/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/getTOC.md +++ b/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/getTOC.md @@ -1,20 +1,35 @@ ## foo + ### foo + ### foo 1 + ## foo 1 + ## foo 2 + ### foo + #### 4th level headings + All 4th level headings should not be shown by default ## bar + ### bar + #### bar -4th level heading should be ignored by default, but is should be always taken -into account, when generating slugs + +4th level heading should be ignored by default, but is should be always taken into account, when generating slugs + ### `bar` + #### `bar` + ## bar + ### bar + #### bar + ## bar diff --git a/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/insertTOC.md b/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/insertTOC.md index d459867a8f22..06b51a1acf53 100644 --- a/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/insertTOC.md +++ b/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/insertTOC.md @@ -25,4 +25,4 @@ Alias: `bag` ### `pokemon-rename` -Alias: `rename` \ No newline at end of file +Alias: `rename` diff --git a/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/split-tab_doc1.md b/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/split-tab_doc1.md index 1e89fe34f56d..15740bb75501 100644 --- a/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/split-tab_doc1.md +++ b/packages/docusaurus-1.x/lib/core/__tests__/__fixtures__/split-tab_doc1.md @@ -1,24 +1,29 @@ + ```js console.log('Hello, world!'); ``` + + ```py print('Hello, world!') ``` + ```C #include int main() { - printf("Hello World!"); - return 0; + printf("Hello World!"); + return 0; } ``` + ```Pascal program HelloWorld; begin diff --git a/packages/docusaurus-1.x/lib/core/__tests__/__snapshots__/toc.test.js.snap b/packages/docusaurus-1.x/lib/core/__tests__/__snapshots__/toc.test.js.snap index c6517e7e92f6..ecc69419321b 100644 --- a/packages/docusaurus-1.x/lib/core/__tests__/__snapshots__/toc.test.js.snap +++ b/packages/docusaurus-1.x/lib/core/__tests__/__snapshots__/toc.test.js.snap @@ -188,24 +188,39 @@ Array [ exports[`insertTOC AUTOGENERATED_TABLE_OF_CONTENTS does not exist 1`] = ` "## foo + ### foo + ### foo 1 + ## foo 1 + ## foo 2 + ### foo + #### 4th level headings + All 4th level headings should not be shown by default ## bar + ### bar + #### bar -4th level heading should be ignored by default, but is should be always taken -into account, when generating slugs + +4th level heading should be ignored by default, but is should be always taken into account, when generating slugs + ### \`bar\` + #### \`bar\` + ## bar + ### bar + #### bar + ## bar " `; @@ -237,5 +252,6 @@ Alias: \`bag\` ### \`pokemon-rename\` -Alias: \`rename\`" +Alias: \`rename\` +" `; diff --git a/packages/docusaurus-1.x/lib/core/__tests__/split-tab.test.js b/packages/docusaurus-1.x/lib/core/__tests__/split-tab.test.js index 9d35617f4d66..8b34eb72ef38 100644 --- a/packages/docusaurus-1.x/lib/core/__tests__/split-tab.test.js +++ b/packages/docusaurus-1.x/lib/core/__tests__/split-tab.test.js @@ -39,33 +39,33 @@ describe('when code tabs are used correctly', () => { it('renders tabs correctly', () => { const node = page.getDOMNode(); const firstTab = node.querySelector('[data-tab$="-content-2"]').textContent; - expect('JavaScript').toEqual(firstTab); + expect(firstTab).toEqual('JavaScript'); const secondTab = node.querySelector('[data-tab$="-content-3"]') .textContent; - expect('Python').toEqual(secondTab); + expect(secondTab).toEqual('Python'); const thirdTab = node.querySelector('[data-tab$="-content-4"]').textContent; - expect('C').toEqual(thirdTab); + expect(thirdTab).toEqual('C'); const fourthTab = node.querySelector('[data-tab$="-content-5"]') .textContent; - expect('Pascal').toEqual(fourthTab); + expect(fourthTab).toEqual('Pascal'); }); it('renders content correctly', () => { const node = page.getDOMNode(); const firstContent = node.querySelector('[id$="-content-2"] code') .textContent; - expect("console.log('Hello, world!');").toEqual(firstContent); + expect(firstContent).toEqual("console.log('Hello, world!');"); const secondContent = node.querySelector('[id$="-content-3"] code') .textContent; - expect("print('Hello, world!')").toEqual(secondContent); + expect(secondContent).toEqual("print('Hello, world!')"); const thirdContent = node.querySelector('[id$="-content-4"] code') .textContent; - expect( - '#include int main() { printf("Hello World!"); return 0;}', - ).toEqual(thirdContent); + expect(thirdContent).toEqual( + '#include int main() { printf("Hello World!"); return 0;}', + ); const fourthContent = node.querySelector('[id$="-content-5"] code') .textContent; - expect("program HelloWorld;begin WriteLn('Hello, world!');end.").toEqual( - fourthContent, + expect(fourthContent).toEqual( + "program HelloWorld;begin WriteLn('Hello, world!');end.", ); }); }); @@ -92,33 +92,33 @@ describe('when code tab is used in a list', () => { it('renders tabs correctly', () => { const node = page.getDOMNode(); const firstTab = node.querySelector('[data-tab$="-content-2"]').textContent; - expect('JavaScript').toEqual(firstTab); + expect(firstTab).toEqual('JavaScript'); const secondTab = node.querySelector('[data-tab$="-content-3"]') .textContent; - expect('Python').toEqual(secondTab); + expect(secondTab).toEqual('Python'); const thirdTab = node.querySelector('[data-tab$="-content-4"]').textContent; - expect('C').toEqual(thirdTab); + expect(thirdTab).toEqual('C'); const fourthTab = node.querySelector('[data-tab$="-content-5"]') .textContent; - expect('Pascal').toEqual(fourthTab); + expect(fourthTab).toEqual('Pascal'); }); it('renders content correctly', () => { const node = page.getDOMNode(); const firstContent = node.querySelector('[id$="-content-2"] code') .textContent; - expect("console.log('Hello, world!');").toEqual(firstContent); + expect(firstContent).toEqual("console.log('Hello, world!');"); const secondContent = node.querySelector('[id$="-content-3"] code') .textContent; - expect("print('Hello, world!')").toEqual(secondContent); + expect(secondContent).toEqual("print('Hello, world!')"); const thirdContent = node.querySelector('[id$="-content-4"] code') .textContent; - expect( + expect(thirdContent).toEqual( '#include int main() { printf("Hello World!"); return 0;}', - ).toEqual(thirdContent); + ); const fourthContent = node.querySelector('[id$="-content-5"] code') .textContent; - expect("program HelloWorld;begin WriteLn('Hello, world!');end.").toEqual( - fourthContent, + expect(fourthContent).toEqual( + "program HelloWorld;begin WriteLn('Hello, world!');end.", ); }); }); diff --git a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/2018-08-17-docusaurus.md b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/2018-08-17-docusaurus.md index c63f1a771d3f..23497f250b4f 100644 --- a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/2018-08-17-docusaurus.md +++ b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/2018-08-17-docusaurus.md @@ -8,4 +8,4 @@ authorTwitter: endiliey ![Docusaurus](/img/slash-introducing.png) -We are very happy to introduce [Docusaurus](https://github.com/facebook/docusaurus) to help you manage one or many open source websites. \ No newline at end of file +We are very happy to introduce [Docusaurus](https://github.com/facebook/docusaurus) to help you manage one or many open source websites. diff --git a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/doc1.md b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/doc1.md index 544689cab74f..41b4fe27da5a 100644 --- a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/doc1.md +++ b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/doc1.md @@ -8,14 +8,15 @@ Docusaurus is the best :) ![image1](assets/image1.png) ```js -console.log("Docusaurus"); +console.log('Docusaurus'); ``` ![image2](assets/image2.jpg) + ![image3](assets/image3.gif) Don't replace the one below -```md +```md ![image4](assets/image4.bmp) -``` \ No newline at end of file +``` diff --git a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/doc2.md b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/doc2.md index 8219f750852f..b11f2119cd7f 100644 --- a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/doc2.md +++ b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/doc2.md @@ -18,12 +18,13 @@ title: Document 2 - [doc2](./doc2.md) ## Do not replace this + ```md ![image1](assets/image1.png) ``` ```js const doc1 = foo(); -console.log("[image2](assets/image2.jpg)"); +console.log('[image2](assets/image2.jpg)'); const testStr = `![image3](assets/image3.gif)`; -``` \ No newline at end of file +``` diff --git a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/reflinks.md b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/reflinks.md index 1d0e8911f34f..a6a7fc2fc0bc 100644 --- a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/reflinks.md +++ b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/reflinks.md @@ -18,13 +18,14 @@ title: Reference Links - [doc2][doc2] ## Do not replace this + ```md ![image1][image1] ``` ```js const doc1 = foo(); -console.log("[image2][image2]"); +console.log('[image2][image2]'); const testStr = `![image3][image3]`; ``` diff --git a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/subdir/doc3.md b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/subdir/doc3.md index f9ef02972444..271e9fc79dd3 100644 --- a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/subdir/doc3.md +++ b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/subdir/doc3.md @@ -6,4 +6,5 @@ title: Document 3 Test subdirectory file ### Replace this + - [doc3](subdir/doc3.md) diff --git a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/test.md b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/test.md index ead5cf2cac72..85bb46e9475b 100644 --- a/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/test.md +++ b/packages/docusaurus-1.x/lib/server/__tests__/__fixtures__/test.md @@ -4,23 +4,8 @@ title: This is not a css This is a markdown, not a css -.homeWrapperInner .homeCodeSnippet > div:nth-child(1) { - display: none; -} +.homeWrapperInner .homeCodeSnippet > div:nth-child(1) { display: none; } -@media (max-width: 480px) { - .projectTitle { - font-size: 30px; - } +@media (max-width: 480px) { .projectTitle { font-size: 30px; } - .homeCodeSnippet .hljs { - font-size: 13px; - padding: 0; - } - .homeWrapperInner .homeCodeSnippet > div:nth-child(1) { - display: block; - } - .homeWrapperInner .homeCodeSnippet > div:nth-child(2) { - display: none; - } -} \ No newline at end of file +.homeCodeSnippet .hljs { font-size: 13px; padding: 0; } .homeWrapperInner .homeCodeSnippet > div:nth-child(1) { display: block; } .homeWrapperInner .homeCodeSnippet > div:nth-child(2) { display: none; } } diff --git a/packages/docusaurus-1.x/lib/server/__tests__/__snapshots__/blog.test.js.snap b/packages/docusaurus-1.x/lib/server/__tests__/__snapshots__/blog.test.js.snap index e57ff362211f..88efe4729c3d 100644 --- a/packages/docusaurus-1.x/lib/server/__tests__/__snapshots__/blog.test.js.snap +++ b/packages/docusaurus-1.x/lib/server/__tests__/__snapshots__/blog.test.js.snap @@ -9,7 +9,8 @@ Object { "content": " ![Docusaurus](/img/slash-introducing.png) -We are very happy to introduce [Docusaurus](https://github.com/facebook/docusaurus) to help you manage one or many open source websites.", +We are very happy to introduce [Docusaurus](https://github.com/facebook/docusaurus) to help you manage one or many open source websites. +", "id": "Docusaurus", "path": "2018/08/17/docusaurus.html", "title": "Docusaurus", @@ -33,15 +34,17 @@ exports[`replaceAssetsLink does not transform document without valid assets link - [doc2](./doc2.md) ## Do not replace this + \`\`\`md ![image1](assets/image1.png) \`\`\` \`\`\`js const doc1 = foo(); -console.log(\\"[image2](assets/image2.jpg)\\"); +console.log('[image2](assets/image2.jpg)'); const testStr = \`![image3](assets/image3.gif)\`; -\`\`\`" +\`\`\` +" `; exports[`replaceAssetsLink transform document with valid assets link 1`] = ` @@ -51,15 +54,17 @@ Docusaurus is the best :) ![image1](/blog/assets/image1.png) \`\`\`js -console.log(\\"Docusaurus\\"); +console.log('Docusaurus'); \`\`\` ![image2](/blog/assets/image2.jpg) + ![image3](/blog/assets/image3.gif) Don't replace the one below -\`\`\`md +\`\`\`md ![image4](assets/image4.bmp) -\`\`\`" +\`\`\` +" `; diff --git a/packages/docusaurus-1.x/lib/server/__tests__/__snapshots__/docs.test.js.snap b/packages/docusaurus-1.x/lib/server/__tests__/__snapshots__/docs.test.js.snap index bd7f6f9e6485..31e7369587a9 100644 --- a/packages/docusaurus-1.x/lib/server/__tests__/__snapshots__/docs.test.js.snap +++ b/packages/docusaurus-1.x/lib/server/__tests__/__snapshots__/docs.test.js.snap @@ -5,6 +5,7 @@ exports[`mdToHtmlify transform link even in subdirectory 1`] = ` Test subdirectory file ### Replace this + - [doc3](/docs/subdir/doc3) " `; @@ -16,17 +17,19 @@ Docusaurus is the best :) ![image1](assets/image1.png) \`\`\`js -console.log(\\"Docusaurus\\"); +console.log('Docusaurus'); \`\`\` ![image2](assets/image2.jpg) + ![image3](assets/image3.gif) Don't replace the one below -\`\`\`md +\`\`\`md ![image4](assets/image4.bmp) -\`\`\`" +\`\`\` +" `; exports[`mdToHtmlify transform to correct link 1`] = ` @@ -46,15 +49,17 @@ exports[`mdToHtmlify transform to correct link 1`] = ` - [doc2](/docs/en/next/doc2) ## Do not replace this + \`\`\`md ![image1](assets/image1.png) \`\`\` \`\`\`js const doc1 = foo(); -console.log(\\"[image2](assets/image2.jpg)\\"); +console.log('[image2](assets/image2.jpg)'); const testStr = \`![image3](assets/image3.gif)\`; -\`\`\`" +\`\`\` +" `; exports[`mdToHtmlify transforms reference links 1`] = ` @@ -74,13 +79,14 @@ exports[`mdToHtmlify transforms reference links 1`] = ` - [doc2][doc2] ## Do not replace this + \`\`\`md ![image1][image1] \`\`\` \`\`\`js const doc1 = foo(); -console.log(\\"[image2][image2]\\"); +console.log('[image2][image2]'); const testStr = \`![image3][image3]\`; \`\`\` @@ -110,15 +116,17 @@ exports[`replaceAssetsLink does not transform document without valid assets link - [doc2](./doc2.md) ## Do not replace this + \`\`\`md ![image1](assets/image1.png) \`\`\` \`\`\`js const doc1 = foo(); -console.log(\\"[image2](assets/image2.jpg)\\"); +console.log('[image2](assets/image2.jpg)'); const testStr = \`![image3](assets/image3.gif)\`; -\`\`\`" +\`\`\` +" `; exports[`replaceAssetsLink transform document with valid assets link 1`] = ` @@ -128,15 +136,17 @@ Docusaurus is the best :) ![image1](/docs/assets/image1.png) \`\`\`js -console.log(\\"Docusaurus\\"); +console.log('Docusaurus'); \`\`\` ![image2](/docs/assets/image2.jpg) + ![image3](/docs/assets/image3.gif) Don't replace the one below -\`\`\`md +\`\`\`md ![image4](assets/image4.bmp) -\`\`\`" +\`\`\` +" `; diff --git a/packages/docusaurus-init/templates/classic/docs/doc2.md b/packages/docusaurus-init/templates/classic/docs/doc2.md index 15ba0cd8cf4a..2462b7f8107f 100644 --- a/packages/docusaurus-init/templates/classic/docs/doc2.md +++ b/packages/docusaurus-init/templates/classic/docs/doc2.md @@ -3,5 +3,4 @@ id: doc2 title: Document Number 2 --- -This is a link to [another document.](doc3.md) -This is a link to an [external page.](http://www.example.com) +This is a link to [another document.](doc3.md) This is a link to an [external page.](http://www.example.com) diff --git a/packages/docusaurus-init/templates/classic/docs/doc3.md b/packages/docusaurus-init/templates/classic/docs/doc3.md index 730f232f2a1e..2c40cc680f5b 100644 --- a/packages/docusaurus-init/templates/classic/docs/doc3.md +++ b/packages/docusaurus-init/templates/classic/docs/doc3.md @@ -2,6 +2,7 @@ id: doc3 title: This is Document Number 3 --- + Lorem ipsum dolor sit amet, consectetur adipiscing elit. In ac euismod odio, eu consequat dui. Nullam molestie consectetur risus id imperdiet. Proin sodales ornare turpis, non mollis massa ultricies id. Nam at nibh scelerisque, feugiat ante non, dapibus tortor. Vivamus volutpat diam quis tellus elementum bibendum. Praesent semper gravida velit quis aliquam. Etiam in cursus neque. Nam lectus ligula, malesuada et mauris a, bibendum faucibus mi. Phasellus ut interdum felis. Phasellus in odio pulvinar, porttitor urna eget, fringilla lectus. Aliquam sollicitudin est eros. Mauris consectetur quam vitae mauris interdum hendrerit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis et egestas libero, imperdiet faucibus ipsum. Sed posuere eget urna vel feugiat. Vivamus a arcu sagittis, fermentum urna dapibus, congue lectus. Fusce vulputate porttitor nisl, ac cursus elit volutpat vitae. Nullam vitae ipsum egestas, convallis quam non, porta nibh. Morbi gravida erat nec neque bibendum, eu pellentesque velit posuere. Fusce aliquam erat eu massa eleifend tristique. diff --git a/packages/docusaurus-init/templates/classic/docs/mdx.md b/packages/docusaurus-init/templates/classic/docs/mdx.md index dd222e2c1659..1462851227ab 100644 --- a/packages/docusaurus-init/templates/classic/docs/mdx.md +++ b/packages/docusaurus-init/templates/classic/docs/mdx.md @@ -5,17 +5,12 @@ title: Powered by MDX You can write JSX and use React components within your Markdown thanks to [MDX](https://mdxjs.com/). -export const Highlight = ({children, color}) => ( - ( - {children} - -); + }}> {children} ); Docusaurus green and Facebook blue are my favorite colors. diff --git a/packages/docusaurus-mdx-loader/README.md b/packages/docusaurus-mdx-loader/README.md index ddca9dc255e9..97784c01bae5 100644 --- a/packages/docusaurus-mdx-loader/README.md +++ b/packages/docusaurus-mdx-loader/README.md @@ -9,8 +9,8 @@ yarn add @docusaurus/mdx-loader ``` ## Usage -```js +```js // ... module: { rules: [ @@ -20,21 +20,23 @@ module: { use: [ 'babel-loader', { - loader: '@docusaurus/mdx-loader', - options: { - // .. See options - } - } - ] - } - ] + loader: '@docusaurus/mdx-loader', + options: { + // .. See options + }, + }, + ], + }, + ]; } ``` ## Options ### `rehypePlugins` + Array of rehype plugins to manipulate the MDXHAST ### `remarkPlugins` + Array of remark plugins to manipulate the MDXAST diff --git a/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/empty-headings.md b/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/empty-headings.md index 43a7ef313ff3..8f1bb180aeec 100644 --- a/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/empty-headings.md +++ b/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/empty-headings.md @@ -1,5 +1,5 @@ # Ignore this -## +## -## ![](an-image.svg) \ No newline at end of file +## ![](an-image.svg) diff --git a/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/inline-code.md b/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/inline-code.md index b5a89c3b2f47..6198b3a2eb08 100644 --- a/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/inline-code.md +++ b/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/inline-code.md @@ -6,4 +6,4 @@ ## `
Test
` -## `
Test
` \ No newline at end of file +## `
Test
` diff --git a/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/insert-below-imports.md b/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/insert-below-imports.md index f62866be5550..e08d696deef2 100644 --- a/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/insert-below-imports.md +++ b/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/insert-below-imports.md @@ -8,4 +8,4 @@ import somethingElse from 'something-else'; ### Again -Content. \ No newline at end of file +Content. diff --git a/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/non-text-content.md b/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/non-text-content.md index eb622ecfb47f..2ea62a2bbaf6 100644 --- a/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/non-text-content.md +++ b/packages/docusaurus-mdx-loader/src/remark/rightToc/__tests__/fixtures/non-text-content.md @@ -1,4 +1,4 @@ -## *Emphasis* +## _Emphasis_ ### **Importance** diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/2018-12-14-Happy-First-Birthday-Slash.md b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/2018-12-14-Happy-First-Birthday-Slash.md index a5151a223e5f..c04bd7b802a0 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/2018-12-14-Happy-First-Birthday-Slash.md +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/2018-12-14-Happy-First-Birthday-Slash.md @@ -2,4 +2,4 @@ title: Happy 1st Birthday Slash! --- -pattern name \ No newline at end of file +pattern name diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/date-matter.md b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/date-matter.md index 52ffa7c01c8a..a48c55c3c42c 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/date-matter.md +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/date-matter.md @@ -2,4 +2,4 @@ date: 2019-01-01 --- -date inside front matter \ No newline at end of file +date inside front matter diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/no date.md b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/no date.md index b579256ebfb0..e56e22ba8036 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/no date.md +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/no date.md @@ -1 +1 @@ -no date \ No newline at end of file +no date diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/bar.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/bar.md index f378f1380cd5..f7ac8782a992 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/bar.md +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/bar.md @@ -10,24 +10,27 @@ description: This is custom description Click the `clear` link to start with a clean slate, or get the `permalink` to share or save your results. -*** +--- # h1 Heading + ## h2 Heading + ### h3 Heading + #### h4 Heading + ##### h5 Heading -###### h6 Heading +###### h6 Heading ## Horizontal Rules -___ - -*** +--- -*** +--- +--- ## Typographic replacements @@ -45,14 +48,13 @@ Remarkable -- awesome 'Smartypants, single quotes' - ## Emphasis **This is bold text** -__This is bold text__ +**This is bold text** -*This is italic text* +_This is italic text_ _This is italic text_ diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md index e3be91b5d689..bc29b950dc07 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md @@ -11,18 +11,16 @@ Like links, Images also have a footnote style syntax With a reference later in the document defining the URL location: -[id]: https://octodex.github.com/images/dojocat.jpg "The Dojocat" +[id]: https://octodex.github.com/images/dojocat.jpg 'The Dojocat' ## Links [link text](http://dev.nodeca.com) -[link with title](http://nodeca.github.io/pica/demo/ "title text!") +[link with title](http://nodeca.github.io/pica/demo/ 'title text!') Autoconverted link https://github.com/nodeca/pica (enable linkify to see) - - ## Footnotes Footnote 1 link[^first]. @@ -35,21 +33,19 @@ Duplicated footnote reference[^second]. [^first]: Footnote **can have markup** - and multiple paragraphs. + and multiple paragraphs. [^second]: Footnote text. - ## Definition lists Term 1 -: Definition 1 -with lazy continuation. +: Definition 1 with lazy continuation. -Term 2 with *inline markup* +Term 2 with _inline markup_ -: Definition 2 +: Definition 2 { some code, part of Definition 2 } @@ -57,13 +53,9 @@ Term 2 with *inline markup* _Compact style:_ -Term 1 - ~ Definition 1 - -Term 2 - ~ Definition 2a - ~ Definition 2b +Term 1 ~ Definition 1 +Term 2 ~ Definition 2a ~ Definition 2b ## Abbreviations @@ -71,4 +63,4 @@ This is HTML abbreviation example. It converts "HTML", but keep intact partial entries like "xxxHTMLyyy" and so on. -*[HTML]: Hyper Text Markup Language +\*[HTML]: Hyper Text Markup Language diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md index c4aa17696c84..1b898368688c 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md @@ -7,11 +7,9 @@ Hi, Endilie here :) ## Relative links -Replace this -[foo](foo/bar.md) +Replace this [foo](foo/bar.md) -Can't replace this -[file](file.md) +Can't replace this [file](file.md) Do not replace below @@ -22,21 +20,22 @@ Do not replace below ## Blockquotes > Blockquotes can also be nested... ->> ...by using additional greater-than signs right next to each other... +> +> > ...by using additional greater-than signs right next to each other... +> > > > > ...or with spaces between arrows. - ## Lists Unordered -+ Create a list by starting a line with `+`, `-`, or `*` -+ Sub-lists are made by indenting 2 spaces: +- Create a list by starting a line with `+`, `-`, or `*` +- Sub-lists are made by indenting 2 spaces: - Marker character change forces new list start: - * Ac tristique libero volutpat at - + Facilisis in pretium nisl aliquet + - Ac tristique libero volutpat at + * Facilisis in pretium nisl aliquet - Nulla volutpat aliquam velit -+ Very easy! +- Very easy! Ordered @@ -44,9 +43,8 @@ Ordered 2. Consectetur adipiscing elit 3. Integer molestie lorem at massa - -1. You can use sequential numbers... -1. ...or keep all the numbers as `1.` +1) You can use sequential numbers... +1) ...or keep all the numbers as `1.` Start numbering with offset: diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/lorem.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/lorem.md index 8e0e2fc39a7a..83ee30a6fb1f 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/lorem.md +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/lorem.md @@ -3,4 +3,4 @@ custom_edit_url: https://github.com/customUrl/docs/lorem.md unrelated_frontmatter: won't be part of metadata --- -Lorem ipsum. \ No newline at end of file +Lorem ipsum. diff --git a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc1.md b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc1.md index f1ec64b8de4b..92ecd85f9f3f 100644 --- a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc1.md +++ b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc1.md @@ -3,9 +3,11 @@ ![image1](assets/image1.png) # Don't replace inside fenced codeblock + ```md ![doc4](doc4.md) ``` ### Non-existing Docs + - [hahaha](hahaha.md) diff --git a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc2.md b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc2.md index 50407eb43553..4c1e57697850 100644 --- a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc2.md +++ b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc2.md @@ -7,4 +7,4 @@ ## Repeating Docs - [doc1](doc1.md) -- [doc2](./doc2.md) \ No newline at end of file +- [doc2](./doc2.md) diff --git a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc4.md b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc4.md index 4b9155e03878..9cf111212a52 100644 --- a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc4.md +++ b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc4.md @@ -9,6 +9,7 @@ - [doc2][doc2] ## Do not replace this + ```md ![image1][image1] ``` diff --git a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/subdir/doc3.md b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/subdir/doc3.md index 6da3139921b5..031c4c6d205d 100644 --- a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/subdir/doc3.md +++ b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/subdir/doc3.md @@ -1,2 +1,3 @@ ### Relative linking + - [doc1](../doc2.md) diff --git a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/doc2.md b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/doc2.md index a84f858148fb..3dc22abb3e3b 100644 --- a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/doc2.md +++ b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/doc2.md @@ -3,4 +3,5 @@ - [doc1](subdir/doc1.md) ### With hash -- [doc2](doc2.md#existing-docs) \ No newline at end of file + +- [doc2](doc2.md#existing-docs) diff --git a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/subdir/doc1.md b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/subdir/doc1.md index 6da3139921b5..031c4c6d205d 100644 --- a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/subdir/doc1.md +++ b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/subdir/doc1.md @@ -1,2 +1,3 @@ ### Relative linking + - [doc1](../doc2.md) diff --git a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__snapshots__/linkify.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__snapshots__/linkify.test.ts.snap index d163bb7ec76e..d90e6c46a733 100644 --- a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__snapshots__/linkify.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__snapshots__/linkify.test.ts.snap @@ -6,17 +6,20 @@ exports[`transform nothing 1`] = ` ![image1](assets/image1.png) # Don't replace inside fenced codeblock + \`\`\`md ![doc4](doc4.md) \`\`\` ### Non-existing Docs + - [hahaha](hahaha.md) " `; exports[`transform relative links 1`] = ` "### Relative linking + - [doc1](/docs/doc2) " `; @@ -31,7 +34,8 @@ exports[`transform to correct links 1`] = ` ## Repeating Docs - [doc1](/docs/doc1) -- [doc2](/docs/doc2)" +- [doc2](/docs/doc2) +" `; exports[`transforms absolute links in versioned docs 1`] = ` @@ -40,7 +44,9 @@ exports[`transforms absolute links in versioned docs 1`] = ` - [doc1](/docs/1.0.0/subdir/doc1) ### With hash -- [doc2](/docs/1.0.0/doc2#existing-docs)" + +- [doc2](/docs/1.0.0/doc2#existing-docs) +" `; exports[`transforms reference links 1`] = ` @@ -55,6 +61,7 @@ exports[`transforms reference links 1`] = ` - [doc2][doc2] ## Do not replace this + \`\`\`md ![image1][image1] \`\`\` @@ -67,6 +74,7 @@ exports[`transforms reference links 1`] = ` exports[`transforms relative links in versioned docs 1`] = ` "### Relative linking + - [doc1](/docs/1.0.0/doc2) " `; diff --git a/packages/docusaurus-plugin-ideal-image/README.md b/packages/docusaurus-plugin-ideal-image/README.md index ac73b0122a8b..2601947f943f 100644 --- a/packages/docusaurus-plugin-ideal-image/README.md +++ b/packages/docusaurus-plugin-ideal-image/README.md @@ -36,11 +36,11 @@ import thumbnail from './path/to/img.png'; ### Options | Option | Type | Default | Description | -|--------|------|---------|-------------| +| --- | --- | --- | --- | | `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. | -| `sizes` | `array` | *original size* | Specify all widths you want to use; if a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). You may also declare a default `sizes` array in the loader options in your `webpack.config.js`. | -| `size` | `integer` | *original size* | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) | -| `min` | `integer` | | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. | -| `max` | `integer` | | See `min` above | -| `steps` | `integer` |`4` | Configure the number of images generated between `min` and `max` (inclusive) | -| `quality` | `integer` | `85` | JPEG compression quality | \ No newline at end of file +| `sizes` | `array` | _original size_ | Specify all widths you want to use; if a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). You may also declare a default `sizes` array in the loader options in your `webpack.config.js`. | +| `size` | `integer` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) | +| `min` | `integer` | | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. | +| `max` | `integer` | | See `min` above | +| `steps` | `integer` | `4` | Configure the number of images generated between `min` and `max` (inclusive) | +| `quality` | `integer` | `85` | JPEG compression quality | diff --git a/packages/docusaurus-theme-live-codeblock/README.md b/packages/docusaurus-theme-live-codeblock/README.md index 48a3d1d67f96..be260f599263 100644 --- a/packages/docusaurus-theme-live-codeblock/README.md +++ b/packages/docusaurus-theme-live-codeblock/README.md @@ -3,6 +3,7 @@ You can create live code editors with a code block `live` meta string. Install + ```bash npm i @docusaurus/theme-live-codeblock # or yarn add @docusaurus/theme-live-codeblock ``` @@ -18,7 +19,6 @@ module.exports = { } ``` - Example: ```jsx live @@ -42,4 +42,4 @@ Example: ); } - ``` \ No newline at end of file + ``` diff --git a/packages/docusaurus/README.MD b/packages/docusaurus/README.MD index 4be5203b0334..1c92d5171d99 100644 --- a/packages/docusaurus/README.MD +++ b/packages/docusaurus/README.MD @@ -1 +1 @@ -# Docusaurus v2 \ No newline at end of file +# Docusaurus v2 diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/docs/foo/bar.md b/packages/docusaurus/src/server/__tests__/__fixtures__/docs/foo/bar.md index ac25e4969a31..e22c5a392452 100644 --- a/packages/docusaurus/src/server/__tests__/__fixtures__/docs/foo/bar.md +++ b/packages/docusaurus/src/server/__tests__/__fixtures__/docs/foo/bar.md @@ -9,24 +9,27 @@ title: Bar Click the `clear` link to start with a clean slate, or get the `permalink` to share or save your results. -*** +--- # h1 Heading + ## h2 Heading + ### h3 Heading + #### h4 Heading + ##### h5 Heading -###### h6 Heading +###### h6 Heading ## Horizontal Rules -___ - -*** +--- -*** +--- +--- ## Typographic replacements @@ -44,14 +47,13 @@ Remarkable -- awesome 'Smartypants, single quotes' - ## Emphasis **This is bold text** -__This is bold text__ +**This is bold text** -*This is italic text* +_This is italic text_ _This is italic text_ diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/docs/foo/baz.md b/packages/docusaurus/src/server/__tests__/__fixtures__/docs/foo/baz.md index e3be91b5d689..bc29b950dc07 100644 --- a/packages/docusaurus/src/server/__tests__/__fixtures__/docs/foo/baz.md +++ b/packages/docusaurus/src/server/__tests__/__fixtures__/docs/foo/baz.md @@ -11,18 +11,16 @@ Like links, Images also have a footnote style syntax With a reference later in the document defining the URL location: -[id]: https://octodex.github.com/images/dojocat.jpg "The Dojocat" +[id]: https://octodex.github.com/images/dojocat.jpg 'The Dojocat' ## Links [link text](http://dev.nodeca.com) -[link with title](http://nodeca.github.io/pica/demo/ "title text!") +[link with title](http://nodeca.github.io/pica/demo/ 'title text!') Autoconverted link https://github.com/nodeca/pica (enable linkify to see) - - ## Footnotes Footnote 1 link[^first]. @@ -35,21 +33,19 @@ Duplicated footnote reference[^second]. [^first]: Footnote **can have markup** - and multiple paragraphs. + and multiple paragraphs. [^second]: Footnote text. - ## Definition lists Term 1 -: Definition 1 -with lazy continuation. +: Definition 1 with lazy continuation. -Term 2 with *inline markup* +Term 2 with _inline markup_ -: Definition 2 +: Definition 2 { some code, part of Definition 2 } @@ -57,13 +53,9 @@ Term 2 with *inline markup* _Compact style:_ -Term 1 - ~ Definition 1 - -Term 2 - ~ Definition 2a - ~ Definition 2b +Term 1 ~ Definition 1 +Term 2 ~ Definition 2a ~ Definition 2b ## Abbreviations @@ -71,4 +63,4 @@ This is HTML abbreviation example. It converts "HTML", but keep intact partial entries like "xxxHTMLyyy" and so on. -*[HTML]: Hyper Text Markup Language +\*[HTML]: Hyper Text Markup Language diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/docs/hello.md b/packages/docusaurus/src/server/__tests__/__fixtures__/docs/hello.md index c4aa17696c84..1b898368688c 100644 --- a/packages/docusaurus/src/server/__tests__/__fixtures__/docs/hello.md +++ b/packages/docusaurus/src/server/__tests__/__fixtures__/docs/hello.md @@ -7,11 +7,9 @@ Hi, Endilie here :) ## Relative links -Replace this -[foo](foo/bar.md) +Replace this [foo](foo/bar.md) -Can't replace this -[file](file.md) +Can't replace this [file](file.md) Do not replace below @@ -22,21 +20,22 @@ Do not replace below ## Blockquotes > Blockquotes can also be nested... ->> ...by using additional greater-than signs right next to each other... +> +> > ...by using additional greater-than signs right next to each other... +> > > > > ...or with spaces between arrows. - ## Lists Unordered -+ Create a list by starting a line with `+`, `-`, or `*` -+ Sub-lists are made by indenting 2 spaces: +- Create a list by starting a line with `+`, `-`, or `*` +- Sub-lists are made by indenting 2 spaces: - Marker character change forces new list start: - * Ac tristique libero volutpat at - + Facilisis in pretium nisl aliquet + - Ac tristique libero volutpat at + * Facilisis in pretium nisl aliquet - Nulla volutpat aliquam velit -+ Very easy! +- Very easy! Ordered @@ -44,9 +43,8 @@ Ordered 2. Consectetur adipiscing elit 3. Integer molestie lorem at massa - -1. You can use sequential numbers... -1. ...or keep all the numbers as `1.` +1) You can use sequential numbers... +1) ...or keep all the numbers as `1.` Start numbering with offset: diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/docs/permalink.md b/packages/docusaurus/src/server/__tests__/__fixtures__/docs/permalink.md index 6e31233dba20..0ff69e7678c4 100644 --- a/packages/docusaurus/src/server/__tests__/__fixtures__/docs/permalink.md +++ b/packages/docusaurus/src/server/__tests__/__fixtures__/docs/permalink.md @@ -4,4 +4,4 @@ title: Permalink permalink: :baseUrl:docsUrl/endiliey/:id --- -This has a different permalink \ No newline at end of file +This has a different permalink diff --git a/website-1.x/README.md b/website-1.x/README.md index 2a9723c4c7ec..1a041c0988c5 100644 --- a/website-1.x/README.md +++ b/website-1.x/README.md @@ -1 +1 @@ -## Docusaurus 1 Website \ No newline at end of file +## Docusaurus 1 Website diff --git a/website-1.x/versioned_docs/version-1.10.x/api-commands.md b/website-1.x/versioned_docs/version-1.10.x/api-commands.md index 64b20514333c..212ad2562d6a 100644 --- a/website-1.x/versioned_docs/version-1.10.x/api-commands.md +++ b/website-1.x/versioned_docs/version-1.10.x/api-commands.md @@ -6,8 +6,8 @@ original_id: commands Docusaurus provides a set of scripts to help you generate, serve, and deploy your website. These scripts can be invoked with the `run` command when using Yarn or npm. Some common commands are: -* [`yarn run start`](api-commands.md#docusaurus-start-port-number): build and serve the website from a local server -* [`yarn run examples`](api-commands.md#docusaurus-examples): create example configuration files +- [`yarn run start`](api-commands.md#docusaurus-start-port-number): build and serve the website from a local server +- [`yarn run examples`](api-commands.md#docusaurus-examples): create example configuration files ## Running from the command line @@ -57,10 +57,10 @@ Docusaurus provides some default mappings to allow you to run commands following Alias: `build`. -| Options | Default | Description | -| -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | +| Options | Default | Description | +| --- | --- | --- | | `--skip-image-compression` | `false` | Skip compression of image assets. You usually won't want to skip this unless your images have already been optimized. | -| `--skip-next-release` | `false` | Skip the next release documents when versioning is enabled. This will not build HTML files for documents in `/docs` directory.| +| `--skip-next-release` | `false` | Skip the next release documents when versioning is enabled. This will not build HTML files for documents in `/docs` directory. | Generates the static website, applying translations if necessary. Useful for building the website prior to deployment. @@ -72,9 +72,9 @@ See also [`docusaurus-start`](api-commands.md#docusaurus-start). Alias: `examples` -| Arguments | Default | Description | -| ----------- | ------- | ---------------------------------------------------------------------------------------------------- | -| `` | - | Specify a feature `translations` or `versions` to generate the extra example files for that feature. | +| Arguments | Default | Description | +| --- | --- | --- | +| `` | - | Specify a feature `translations` or `versions` to generate the extra example files for that feature. | **Example** @@ -94,8 +94,8 @@ Alias: `publish-gh-pages` The following environment variables are 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. +- `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. **Example** @@ -105,13 +105,13 @@ GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages The following environment variables are [set by CircleCI](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. +- `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". +- `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". You can learn more about configuring automatic deployments with CircleCI in the [Publishing guide](getting-started-publishing.md). @@ -144,11 +144,11 @@ Alias: `start`. This command will build the static website, apply translations if necessary, and then start a local server. -| Options | Default | Description | -| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `--port ` | `3000` | The website will be served from port 3000 by default, but if the port is taken up, Docusaurus will attempt to find an available one. | -|`--host `|`localhost`|Specify a host to use. E.g., if you want your server to be accessible externally, you can use --host 0.0.0.0.| -| `--watch` | - | Whether to watch the files and live reload the page when files are changed. Defaults to true. Disable this by using `--no-watch`. | +| Options | Default | Description | +| --- | --- | --- | +| `--port ` | `3000` | The website will be served from port 3000 by default, but if the port is taken up, Docusaurus will attempt to find an available one. | +| `--host ` | `localhost` | Specify a host to use. E.g., if you want your server to be accessible externally, you can use --host 0.0.0.0. | +| `--watch` | - | Whether to watch the files and live reload the page when files are changed. Defaults to true. Disable this by using `--no-watch`. | You can specify the browser application to be opened by setting the `BROWSER` environment variable before the command, e.g.: diff --git a/website-1.x/versioned_docs/version-1.10.x/api-doc-markdown.md b/website-1.x/versioned_docs/version-1.10.x/api-doc-markdown.md index 5e30e2757600..b6eed82b8e5a 100644 --- a/website-1.x/versioned_docs/version-1.10.x/api-doc-markdown.md +++ b/website-1.x/versioned_docs/version-1.10.x/api-doc-markdown.md @@ -28,6 +28,7 @@ id: doc1 title: My Document sidebar_label: Document --- + ``` Versioned documents have their ids altered to include the version number when they get copied. The new `id` is `version-${version}-${id}` where `${version}` is the version number of that document and `${id}` is the original `id`. Additionally, versioned documents get an added `original_id` field with the original document id. @@ -41,6 +42,7 @@ title: My Document sidebar_label: Document original_id: doc1 --- + ``` `custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from optional fields of `siteConfig.js`. See [siteConfig.js](api-site-config.md) docs for more information. @@ -53,6 +55,7 @@ id: doc-markdown title: Markdown Features custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md --- + ``` ### Blog Posts @@ -76,6 +79,7 @@ author: Frank Li authorURL: http://twitter.com/franchementli authorFBID: 100002976521003 --- + ``` ## Extra Features @@ -133,7 +137,6 @@ will lead to a table of contents of the functions: and each function will link to their corresponding sections in the page. - ### Language-specific Code Tabs Display code in multiple programming languages using code tabs. First, mark the start and end of a code tabs group, by using `` and `` respectively in your markdown. Then start each tab with ``. @@ -146,15 +149,19 @@ produces this: + ```js console.log('Hello, world!'); ``` + + ```py print('Hello, world!') ``` + ```C #include @@ -165,6 +172,7 @@ int main() { ``` + ```Pascal program HelloWorld; begin diff --git a/website-1.x/versioned_docs/version-1.10.x/api-pages.md b/website-1.x/versioned_docs/version-1.10.x/api-pages.md index a56f5ee88378..b238e25993e6 100644 --- a/website-1.x/versioned_docs/version-1.10.x/api-pages.md +++ b/website-1.x/versioned_docs/version-1.10.x/api-pages.md @@ -72,8 +72,8 @@ module.exports = MyPage; This will be translated to a description metadata tag on the generated HTML. ```html - - + + ``` ## Page Require Paths @@ -108,11 +108,11 @@ A React container component using Docusaurus styles. Has optional padding and ba **Props** -| Prop | Type | Default | Description | -| ------------ | ---------------------------------------------------------- | ------- | ----------------------------------- | -| `padding` | Array of `'all'`, `'bottom'`, `'left'`, `'right'`, `'top'` | `[]` | Positions of the padding. | -| `background` | One of `'dark'`, `'highlight'`, `'light'` | `null` | Background styling of the element. | -| `className` | String | - | Custom class to add to the element. | +| Prop | Type | Default | Description | +| --- | --- | --- | --- | +| `padding` | Array of `'all'`, `'bottom'`, `'left'`, `'right'`, `'top'` | `[]` | Positions of the padding. | +| `background` | One of `'dark'`, `'highlight'`, `'light'` | `null` | Background styling of the element. | +| `className` | String | - | Custom class to add to the element. | **Example** @@ -131,23 +131,23 @@ A React component to organize text and images. **Props** -| Prop | Type | Default | Description | -| ----------- | ----------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------- | -| `align` | One of `'left'`, `'center'`, `'right'` | `'left'` | Text alignment of content. | -| `layout` | One of `'twoColumn'`, `'threeColumn'`, `'fourColumn'` | `'twoColumn'` | Number of column sections in the `GridBlock`. | -| `className` | String | - | Custom class to add to the element. | -| `contents` | Array of content objects | `[]` | Contents of each section of the GridBlock. Refer to the next table for the fields available on a content object. | +| Prop | Type | Default | Description | +| --- | --- | --- | --- | +| `align` | One of `'left'`, `'center'`, `'right'` | `'left'` | Text alignment of content. | +| `layout` | One of `'twoColumn'`, `'threeColumn'`, `'fourColumn'` | `'twoColumn'` | Number of column sections in the `GridBlock`. | +| `className` | String | - | Custom class to add to the element. | +| `contents` | Array of content objects | `[]` | Contents of each section of the GridBlock. Refer to the next table for the fields available on a content object. | **Content Object** -| Key | Type | Default | Description | -| ------------ | ----------------------------------------------- | -------- | ----------------------------------------------------------------- | -| `title` | String | - | The display title of this section, which is parsed using Markdown | -| `content` | String | - | The text of this section, which is parsed using Markdown | -| `image` | String | - | The path of the display image | -| `imageAlt` | String | - | The text that will be shown in case the image is not available | -| `imageAlign` | One of `'top'`, `'left'`, `'bottom'`, `'right'` | `'left'` | Image alignment relative to the text | -| `imageLink` | String | - | Link destination from clicking the image | +| Key | Type | Default | Description | +| --- | --- | --- | --- | +| `title` | String | - | The display title of this section, which is parsed using Markdown | +| `content` | String | - | The text of this section, which is parsed using Markdown | +| `image` | String | - | The path of the display image | +| `imageAlt` | String | - | The text that will be shown in case the image is not available | +| `imageAlign` | One of `'top'`, `'left'`, `'bottom'`, `'right'` | `'left'` | Image alignment relative to the text | +| `imageLink` | String | - | Link destination from clicking the image | **Example** diff --git a/website-1.x/versioned_docs/version-1.10.x/api-site-config.md b/website-1.x/versioned_docs/version-1.10.x/api-site-config.md index 029ca0420c1e..8e0b32cb1a95 100644 --- a/website-1.x/versioned_docs/version-1.10.x/api-site-config.md +++ b/website-1.x/versioned_docs/version-1.10.x/api-site-config.md @@ -129,8 +129,7 @@ The default version for the site to be shown. If this is not set, the latest ver #### `docsUrl` [string] -The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. -If unset, it is defaulted to `docs`. +The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. If unset, it is defaulted to `docs`. #### `disableHeaderTitle` [boolean] diff --git a/website-1.x/versioned_docs/version-1.10.x/getting-started-preparation.md b/website-1.x/versioned_docs/version-1.10.x/getting-started-preparation.md index 95b47ebb5cb7..0a53c477260d 100644 --- a/website-1.x/versioned_docs/version-1.10.x/getting-started-preparation.md +++ b/website-1.x/versioned_docs/version-1.10.x/getting-started-preparation.md @@ -56,4 +56,3 @@ You will need to keep the `website/siteConfig.js` and `website/core/Footer.js` f However, you should keep the `website/pages` and `website/static` directories. You 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 `website/pages` and an image to use as your header icon inside `website/static`. If your directory does not yet have a `.gitignore`, we generate it with the necessary ignored files listed. As a general rule, you should ignore all `node_modules`, build files, system files (`.DS_Store`), logs, etc. [Here](https://github.com/github/gitignore/blob/master/Node.gitignore) is a more comprehensive list of what is normally ignored for Node.js projects. - diff --git a/website-1.x/versioned_docs/version-1.10.x/getting-started-publishing.md b/website-1.x/versioned_docs/version-1.10.x/getting-started-publishing.md index 4e7c371747db..cc57dc4cd688 100644 --- a/website-1.x/versioned_docs/version-1.10.x/getting-started-publishing.md +++ b/website-1.x/versioned_docs/version-1.10.x/getting-started-publishing.md @@ -26,9 +26,9 @@ At this point, you can grab all of the files inside the `website/build` director ### Hosting on a Service: -* [ZEIT Now](#using-zeit-now) -* [GitHub Pages](#using-github-pages) -* [Netlify](#hosting-on-netlify) +- [ZEIT Now](#using-zeit-now) +- [GitHub Pages](#using-github-pages) +- [Netlify](#hosting-on-netlify) ### Using ZEIT Now @@ -60,17 +60,16 @@ Docusaurus was designed to work really well with one of the most popular hosting > Even if your repository is private, anything published to a `gh-pages` branch will be [public](https://help.github.com/articles/user-organization-and-project-pages/). -__Note:__ When you deploy as user/organization page, the publish script will deploy these sites to the root of the __`master`__ branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in __another branch of the _username_.github.io repo__ (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code). +**Note:** When you deploy as user/organization page, the publish script will deploy these sites to the root of the **`master`** branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in **another branch of the _username_.github.io repo** (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code). 2. You will need to modify the file `website/siteConfig.js` and add the required parameters. -| Name | Description | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. | -| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". | -| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" | -| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | - +| Name | Description | +| --- | --- | +| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. | +| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". | +| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" | +| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | ```js const siteConfig = { @@ -85,14 +84,14 @@ const siteConfig = { In case you want to deploy as a user or organization site, specify the project name as `.github.io` or `.github.io`. E.g. If your GitHub username is "user42" then _user42.github.io_, or in the case of an organization name of "org123", it will be _org123.github.io_. -__Note:__ Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images. +**Note:** Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images. > While we recommend setting the `projectName` and `organizationName` in `siteConfig.js`, you can also use environment variables `ORGANIZATION_NAME` and `PROJECT_NAME`. 3. Now you have to specify the git user as an environment variable, and run the script [`publish-gh-pages`](./api-commands.md#docusaurus-publish) -| Name | Description | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| Name | Description | +| --- | --- | | `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. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. | To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. @@ -106,9 +105,9 @@ GIT_USER= \ There are also two optional parameters that are set as environment variables: -| Name | Description | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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. | +| Name | Description | +| --- | --- | +| `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. | If you run into issues related to SSH keys, visit [GitHub's authentication documentation](https://help.github.com/articles/connecting-to-github-with-ssh/). @@ -189,14 +188,16 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications). You can work around this by: -- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. -e.g. + +- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. e.g. + ```bash CUSTOM_COMMIT_MESSAGE="[skip ci]" \ yarn run publish-gh-pages # or `npm run publish-gh-pages` ``` - Alternatively, you can work around this by creating a basic CircleCI config with the following contents: + ```yaml # CircleCI 2.0 Config File # This config file will prevent tests from being run on the gh-pages branch. @@ -252,8 +253,8 @@ Steps to configure your Docusaurus-powered site on Netlify. 1. Select the branch to deploy. Default is `master` 1. Configure your build steps: - * For your build command enter: `cd website; npm install; npm run build;` - * For publish directory: `website/build/` (use the `projectName` from your `siteConfig`) + - For your build command enter: `cd website; npm install; npm run build;` + - For publish directory: `website/build/` (use the `projectName` from your `siteConfig`) 1. Click **Deploy site** diff --git a/website-1.x/versioned_docs/version-1.10.x/getting-started-site-creation.md b/website-1.x/versioned_docs/version-1.10.x/getting-started-site-creation.md index 49c9363bb746..4c1c6d84d1c6 100644 --- a/website-1.x/versioned_docs/version-1.10.x/getting-started-site-creation.md +++ b/website-1.x/versioned_docs/version-1.10.x/getting-started-site-creation.md @@ -43,7 +43,6 @@ To create a fully functional site, you only need to do a few steps: id: intro title: Getting Started --- - My new content here.. ``` @@ -72,18 +71,22 @@ If you prefer to have your landing page be straight to your documentation, you c 1. Add a [custom static `index.html` page](guides-custom-pages.md#adding-static-pages) in the `website/static` directory with the following contents: ```html - + - - + + Your Site Title Here - If you are not redirected automatically, follow this link. + If you are not redirected automatically, follow this + link. ``` diff --git a/website-1.x/versioned_docs/version-1.10.x/guides-search.md b/website-1.x/versioned_docs/version-1.10.x/guides-search.md index 1c800e473253..ed97ca668462 100644 --- a/website-1.x/versioned_docs/version-1.10.x/guides-search.md +++ b/website-1.x/versioned_docs/version-1.10.x/guides-search.md @@ -64,7 +64,7 @@ const siteConfig = { ## Customizing the placeholder -If you want to change the placeholder (which defaults to *Search*), add the `placeholder` field in your config. For example, you may want the search bar to display *Ask me something*: +If you want to change the placeholder (which defaults to _Search_), add the `placeholder` field in your config. For example, you may want the search bar to display _Ask me something_: ```js const siteConfig = { diff --git a/website-1.x/versioned_docs/version-1.10.x/guides-translation.md b/website-1.x/versioned_docs/version-1.10.x/guides-translation.md index d93b8d9ef2a4..308f6c07e940 100644 --- a/website-1.x/versioned_docs/version-1.10.x/guides-translation.md +++ b/website-1.x/versioned_docs/version-1.10.x/guides-translation.md @@ -28,13 +28,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 `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 @@ -88,11 +88,11 @@ Running the script will generate a `website/i18n/en.json` file containing all th 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` ### Custom Translation Strings @@ -112,7 +112,7 @@ If you want to add additional custom translation strings or override any of the } } }, - "pages-strings" : { + "pages-strings": { "id3": "string3", "id4": "string4" } @@ -129,8 +129,8 @@ Here is an example: "localized-strings": { "translation": "Translations and Localization" }, - "pages-strings" : { - "Help Translate|recruit community translators for your project": "Help Us Translate" + "pages-strings": { + "Help Translate|recruit community translators for your project": "Help Us Translate" } } ``` @@ -178,12 +178,11 @@ Below is an example Crowdin configuration for the respective languages: German, ```yaml project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID api_key_env: CROWDIN_DOCUSAURUS_API_KEY -base_path: "./" +base_path: './' preserve_hierarchy: true files: - - - source: '/docs/**/*.md' + - source: '/docs/**/*.md' translation: '/website/translated_docs/%locale%/**/%original_file_name%' languages_mapping: &anchor locale: diff --git a/website-1.x/versioned_docs/version-1.11.x/api-site-config.md b/website-1.x/versioned_docs/version-1.11.x/api-site-config.md index df8f123a0d83..8ea38802a84a 100644 --- a/website-1.x/versioned_docs/version-1.11.x/api-site-config.md +++ b/website-1.x/versioned_docs/version-1.11.x/api-site-config.md @@ -129,8 +129,7 @@ The default version for the site to be shown. If this is not set, the latest ver #### `docsUrl` [string] -The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. -If unset, it is defaulted to `docs`. +The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. If unset, it is defaulted to `docs`. #### `disableHeaderTitle` [boolean] diff --git a/website-1.x/versioned_docs/version-1.11.x/guides-blog.md b/website-1.x/versioned_docs/version-1.11.x/guides-blog.md index 59b4f48a7858..1d5681777b40 100644 --- a/website-1.x/versioned_docs/version-1.11.x/guides-blog.md +++ b/website-1.x/versioned_docs/version-1.11.x/guides-blog.md @@ -31,7 +31,6 @@ authorURL: https://twitter.com/foobarbaz authorFBID: 503283835 title: Introducing Docusaurus --- - Lorem Ipsum... ``` @@ -39,11 +38,11 @@ Lorem Ipsum... The only required field is `title`; however, we provide options to add author information to your blog post as well. -* `author` - The text label of the author byline. -* `authorURL` - The URL associated with the author. This could be a Twitter, GitHub, Facebook account, etc. -* `authorFBID` - The Facebook profile ID that is used to fetch the profile picture. -* `authorImageURL` - The URL to the author's image. (Note: If you use both `authorFBID` and `authorImageURL`, `authorFBID` will take precedence. Don't include `authorFBID` if you want `authorImageURL` to appear.) -* `title` - The blog post title. +- `author` - The text label of the author byline. +- `authorURL` - The URL associated with the author. This could be a Twitter, GitHub, Facebook account, etc. +- `authorFBID` - The Facebook profile ID that is used to fetch the profile picture. +- `authorImageURL` - The URL to the author's image. (Note: If you use both `authorFBID` and `authorImageURL`, `authorFBID` will take precedence. Don't include `authorFBID` if you want `authorImageURL` to appear.) +- `title` - The blog post title. ## Summary Truncation @@ -53,7 +52,6 @@ Use the `` marker in your blog post to represent what will be sho --- title: Truncation Example --- - All this will be part of the blog post summary. Even this. @@ -121,18 +119,19 @@ To do this: You can use this template: ```html - + - - + + Title of Your Blog - If you are not redirected automatically, follow this link. + If you are not redirected automatically, follow this + link. ``` diff --git a/website-1.x/versioned_docs/version-1.12.0/api-doc-markdown.md b/website-1.x/versioned_docs/version-1.12.0/api-doc-markdown.md index ca3fbf479dd8..085191cc4ce4 100644 --- a/website-1.x/versioned_docs/version-1.12.0/api-doc-markdown.md +++ b/website-1.x/versioned_docs/version-1.12.0/api-doc-markdown.md @@ -28,6 +28,7 @@ id: doc1 title: My Document sidebar_label: Document --- + ``` Versioned documents have their ids altered to include the version number when they get copied. The new `id` is `version-${version}-${id}` where `${version}` is the version number of that document and `${id}` is the original `id`. Additionally, versioned documents get an added `original_id` field with the original document id. @@ -41,6 +42,7 @@ title: My Document sidebar_label: Document original_id: doc1 --- + ``` `custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from optional fields of `siteConfig.js`. See [siteConfig.js](api-site-config.md) docs for more information. @@ -53,6 +55,7 @@ id: doc-markdown title: Markdown Features custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md --- + ``` ### Blog Posts @@ -76,6 +79,7 @@ author: Frank Li authorURL: http://twitter.com/franchementli authorFBID: 100002976521003 --- + ``` ## Extra Features @@ -133,7 +137,6 @@ will lead to a table of contents of the functions: and each function will link to their corresponding sections in the page. - ### Language-specific Code Tabs Display code in multiple programming languages using code tabs. First, mark the start and end of a code tabs group, by using `` and `` respectively in your markdown. Then start each tab with ``. @@ -147,16 +150,19 @@ produces this: + ```js console.log('Hello, world!'); ``` + ```py print('Hello, world!') ``` + ```C #include @@ -167,6 +173,7 @@ int main() { ``` + ```Pascal program HelloWorld; begin diff --git a/website-1.x/versioned_docs/version-1.12.0/getting-started-publishing.md b/website-1.x/versioned_docs/version-1.12.0/getting-started-publishing.md index 8ee18e44287f..6240afa44ff4 100644 --- a/website-1.x/versioned_docs/version-1.12.0/getting-started-publishing.md +++ b/website-1.x/versioned_docs/version-1.12.0/getting-started-publishing.md @@ -26,10 +26,10 @@ At this point, you can grab all of the files inside the `website/build` director ### Hosting on a Service: -* [ZEIT Now](#using-zeit-now) -* [GitHub Pages](#using-github-pages) -* [Netlify](#hosting-on-netlify) -* [Render](#hosting-on-render) +- [ZEIT Now](#using-zeit-now) +- [GitHub Pages](#using-github-pages) +- [Netlify](#hosting-on-netlify) +- [Render](#hosting-on-render) ### Using ZEIT Now @@ -61,17 +61,16 @@ Docusaurus was designed to work really well with one of the most popular hosting > Even if your repository is private, anything published to a `gh-pages` branch will be [public](https://help.github.com/articles/user-organization-and-project-pages/). -__Note:__ When you deploy as user/organization page, the publish script will deploy these sites to the root of the __`master`__ branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in __another branch of the _username_.github.io repo__ (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code). +**Note:** When you deploy as user/organization page, the publish script will deploy these sites to the root of the **`master`** branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in **another branch of the _username_.github.io repo** (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code). 2. You will need to modify the file `website/siteConfig.js` and add the required parameters. -| Name | Description | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. | -| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". | -| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" | -| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | - +| Name | Description | +| --- | --- | +| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. | +| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". | +| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" | +| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | ```js const siteConfig = { @@ -86,14 +85,14 @@ const siteConfig = { In case you want to deploy as a user or organization site, specify the project name as `.github.io` or `.github.io`. E.g. If your GitHub username is "user42" then _user42.github.io_, or in the case of an organization name of "org123", it will be _org123.github.io_. -__Note:__ Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images. +**Note:** Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images. > While we recommend setting the `projectName` and `organizationName` in `siteConfig.js`, you can also use environment variables `ORGANIZATION_NAME` and `PROJECT_NAME`. 3. Now you have to specify the git user as an environment variable, and run the script [`publish-gh-pages`](./api-commands.md#docusaurus-publish) -| Name | Description | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| Name | Description | +| --- | --- | | `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. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. | To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. @@ -107,9 +106,9 @@ GIT_USER= \ There are also two optional parameters that are set as environment variables: -| Name | Description | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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. | +| Name | Description | +| --- | --- | +| `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. | If you run into issues related to SSH keys, visit [GitHub's authentication documentation](https://help.github.com/articles/connecting-to-github-with-ssh/). @@ -190,14 +189,16 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications). You can work around this by: -- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. -e.g. + +- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. e.g. + ```bash CUSTOM_COMMIT_MESSAGE="[skip ci]" \ yarn run publish-gh-pages # or `npm run publish-gh-pages` ``` - Alternatively, you can work around this by creating a basic CircleCI config with the following contents: + ```yaml # CircleCI 2.0 Config File # This config file will prevent tests from being run on the gh-pages branch. @@ -253,8 +254,8 @@ Steps to configure your Docusaurus-powered site on Netlify. 1. Select the branch to deploy. Default is `master` 1. Configure your build steps: - * For your build command enter: `cd website; npm install; npm run build;` - * For publish directory: `website/build/` (use the `projectName` from your `siteConfig`) + - For your build command enter: `cd website; npm install; npm run build;` + - For publish directory: `website/build/` (use the `projectName` from your `siteConfig`) 1. Click **Deploy site** @@ -268,22 +269,22 @@ Render offers free [static site](https://render.com/docs/static-sites) hosting w 2. Select the branch to deploy. The default is `master`. -2. Enter the following values during creation. +3. Enter the following values during creation. - | Field | Value | - | ------- | ----- | - | **Environment** | `Static Site` | - | **Build Command** | `cd website; yarn install; yarn build` | - | **Publish Directory** | `website/build/` | + | Field | Value | + | --------------------- | -------------------------------------- | + | **Environment** | `Static Site` | + | **Build Command** | `cd website; yarn install; yarn build` | + | **Publish Directory** | `website/build/` | - `projectName` is the value you defined in your `siteConfig.js`. + `projectName` is the value you defined in your `siteConfig.js`. - ```javascript{7} - const siteConfig = { - // ... - projectName: 'your-project-name', - // ... - ``` + ```javascript{7} + const siteConfig = { + // ... + projectName: 'your-project-name', + // ... + ``` That's it! Your app will be live on your Render URL as soon as the build finishes. diff --git a/website-1.x/versioned_docs/version-1.13.0/api-site-config.md b/website-1.x/versioned_docs/version-1.13.0/api-site-config.md index 536b60a4e163..b62894744921 100644 --- a/website-1.x/versioned_docs/version-1.13.0/api-site-config.md +++ b/website-1.x/versioned_docs/version-1.13.0/api-site-config.md @@ -129,8 +129,7 @@ The default version for the site to be shown. If this is not set, the latest ver #### `docsUrl` [string] -The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. -If unset, it is defaulted to `docs`. +The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. If unset, it is defaulted to `docs`. #### `disableHeaderTitle` [boolean] diff --git a/website-1.x/versioned_docs/version-1.13.0/tutorial-create-new-site.md b/website-1.x/versioned_docs/version-1.13.0/tutorial-create-new-site.md index 6cc2e8cbdb5d..1d0471bee957 100644 --- a/website-1.x/versioned_docs/version-1.13.0/tutorial-create-new-site.md +++ b/website-1.x/versioned_docs/version-1.13.0/tutorial-create-new-site.md @@ -65,7 +65,6 @@ The following contents will be created in your current directory. Some example d └── yarn.lock ``` - 3. Run `cd website` to go into the `website` directory. 4. Run `npm start` or `yarn start`. diff --git a/website-1.x/versioned_docs/version-1.13.0/tutorial-publish-site.md b/website-1.x/versioned_docs/version-1.13.0/tutorial-publish-site.md index ac85e42d5abd..00a650ee9b96 100644 --- a/website-1.x/versioned_docs/version-1.13.0/tutorial-publish-site.md +++ b/website-1.x/versioned_docs/version-1.13.0/tutorial-publish-site.md @@ -33,7 +33,7 @@ GIT_USER=USERNAME CURRENT_BRANCH=master USE_SSH=true npm run publish-gh-pages # GIT_USER=USERNAME CURRENT_BRANCH=master npm run publish-gh-pages # HTTPS ``` -The HTML files (and other file types) are pushed to the `gh-pages` branch of your repository: https://github.com/USERNAME/docusaurus-tutorial. +The HTML files (and other file types) are pushed to the `gh-pages` branch of your repository: https://github.com/USERNAME/docusaurus-tutorial. 5. Go to https://USERNAME.github.io/docusaurus-tutorial/ and view your site in action! diff --git a/website-1.x/versioned_docs/version-1.13.0/tutorial-setup.md b/website-1.x/versioned_docs/version-1.13.0/tutorial-setup.md index eef8958478cf..772518462d78 100644 --- a/website-1.x/versioned_docs/version-1.13.0/tutorial-setup.md +++ b/website-1.x/versioned_docs/version-1.13.0/tutorial-setup.md @@ -57,7 +57,7 @@ We highly recommend that you install Yarn, an alternative package manager that h GitHub create repo -5. In Terminal or Git Bash, `cd` to a directory where the local clone will be a subdirectory. +5. In Terminal or Git Bash, `cd` to a directory where the local clone will be a subdirectory. ```sh cd /Users/NAME/doc_projects # macOS example diff --git a/website-1.x/versioned_docs/version-1.14.3/api-doc-markdown.md b/website-1.x/versioned_docs/version-1.14.3/api-doc-markdown.md index 1f2d92b1492f..49d7f683c9db 100644 --- a/website-1.x/versioned_docs/version-1.14.3/api-doc-markdown.md +++ b/website-1.x/versioned_docs/version-1.14.3/api-doc-markdown.md @@ -26,6 +26,7 @@ id: doc1 title: My Document sidebar_label: Document --- + ``` Versioned documents have their ids altered to include the version number when they get copied. The new `id` is `version-${version}-${id}` where `${version}` is the version number of that document and `${id}` is the original `id`. Additionally, versioned documents get an added `original_id` field with the original document id. @@ -39,6 +40,7 @@ title: My Document sidebar_label: Document original_id: doc1 --- + ``` `custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from optional fields of `siteConfig.js`. See [siteConfig.js](api-site-config.md) docs for more information. @@ -51,6 +53,7 @@ id: doc-markdown title: Markdown Features custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md --- + ``` ### Blog Posts @@ -74,6 +77,7 @@ author: Frank Li authorURL: http://twitter.com/franchementli authorFBID: 100002976521003 --- + ``` ## Extra Features @@ -131,7 +135,6 @@ will lead to a table of contents of the functions: and each function will link to their corresponding sections in the page. - ### Language-specific Code Tabs Display code in multiple programming languages using code tabs. First, mark the start and end of a code tabs group, by using `` and `` respectively in your markdown. Then start each tab with ``. @@ -145,16 +148,19 @@ produces this: + ```js console.log('Hello, world!'); ``` + ```py print('Hello, world!') ``` + ```C #include @@ -165,6 +171,7 @@ int main() { ``` + ```Pascal program HelloWorld; begin diff --git a/website-1.x/versioned_docs/version-1.14.3/api-site-config.md b/website-1.x/versioned_docs/version-1.14.3/api-site-config.md index 301025bfb879..a26b61882319 100644 --- a/website-1.x/versioned_docs/version-1.14.3/api-site-config.md +++ b/website-1.x/versioned_docs/version-1.14.3/api-site-config.md @@ -131,8 +131,7 @@ The default version for the site to be shown. If this is not set, the latest ver #### `docsUrl` [string] -The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. -If unset, it is defaulted to `docs`. +The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. If unset, it is defaulted to `docs`. #### `disableHeaderTitle` [boolean] diff --git a/website-1.x/versioned_docs/version-1.14.3/getting-started-installation.md b/website-1.x/versioned_docs/version-1.14.3/getting-started-installation.md index 838562ea182f..e450836d3e6b 100644 --- a/website-1.x/versioned_docs/version-1.14.3/getting-started-installation.md +++ b/website-1.x/versioned_docs/version-1.14.3/getting-started-installation.md @@ -17,9 +17,7 @@ We have created a helpful script that will get all of the infrastructure set up 1. Create a project, if none exists, and change your directory to this project's root. - You will be creating the docs in this directory. The root directory may - contain other files. The Docusaurus installation script will create two new - directories: `docs` and `website`. + You will be creating the docs in this directory. The root directory may contain other files. The Docusaurus installation script will create two new directories: `docs` and `website`. > Commonly, either an existing or newly created GitHub project will be the location for your Docusaurus site, but that is not mandatory to use Docusaurus. @@ -62,15 +60,11 @@ root-directory ## Running the example website -After running the Docusaurus initialization script, `docusaurus-init` as -described in the [Installation](#installing-docusaurus) section, you will have a -runnable, example website to use as your site's base. To run: +After running the Docusaurus initialization script, `docusaurus-init` as described in the [Installation](#installing-docusaurus) section, you will have a runnable, example website to use as your site's base. To run: 1. `cd website` -1. From within the `website` directory, run the local web server using - `yarn start` or `npm start`. -1. Load the example site at http://localhost:3000 if it did not already open - automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which. +1. From within the `website` directory, run the local web server using `yarn start` or `npm start`. +1. Load the example site at http://localhost:3000 if it did not already open automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which. You should see the example site loaded in your web browser. There's also a LiveReload server running and any changes made to the docs and files in the `website` directory will cause the page to refresh. A randomly generated primary and secondary theme color will be picked for you. diff --git a/website-1.x/versioned_docs/version-1.14.3/getting-started-publishing.md b/website-1.x/versioned_docs/version-1.14.3/getting-started-publishing.md index 9ffeeeef1f2c..dc038c8a29c1 100644 --- a/website-1.x/versioned_docs/version-1.14.3/getting-started-publishing.md +++ b/website-1.x/versioned_docs/version-1.14.3/getting-started-publishing.md @@ -26,10 +26,10 @@ At this point, you can grab all of the files inside the `website/build` director ### Hosting on a Service: -* [ZEIT Now](#using-zeit-now) -* [GitHub Pages](#using-github-pages) -* [Netlify](#hosting-on-netlify) -* [Render](#hosting-on-render) +- [ZEIT Now](#using-zeit-now) +- [GitHub Pages](#using-github-pages) +- [Netlify](#hosting-on-netlify) +- [Render](#hosting-on-render) ### Using ZEIT Now @@ -61,17 +61,16 @@ Docusaurus was designed to work really well with one of the most popular hosting > Even if your repository is private, anything published to a `gh-pages` branch will be [public](https://help.github.com/articles/user-organization-and-project-pages/). -__Note:__ When you deploy as user/organization page, the publish script will deploy these sites to the root of the __`master`__ branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in __another branch of the _username_.github.io repo__ (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code). +**Note:** When you deploy as user/organization page, the publish script will deploy these sites to the root of the **`master`** branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in **another branch of the _username_.github.io repo** (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code). 2. You will need to modify the file `website/siteConfig.js` and add the required parameters. -| Name | Description | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. | -| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". | -| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" | -| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | - +| Name | Description | +| --- | --- | +| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. | +| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". | +| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" | +| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | ```js const siteConfig = { @@ -86,19 +85,20 @@ const siteConfig = { In case you want to deploy as a user or organization site, specify the project name as `.github.io` or `.github.io`. E.g. If your GitHub username is "user42" then _user42.github.io_, or in the case of an organization name of "org123", it will be _org123.github.io_. -__Note:__ Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images. +**Note:** Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images. > While we recommend setting the `projectName` and `organizationName` in `siteConfig.js`, you can also use environment variables `ORGANIZATION_NAME` and `PROJECT_NAME`. 3. Now you have to specify the git user as an environment variable, and run the script [`publish-gh-pages`](./api-commands.md#docusaurus-publish) -| Name | Description | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| Name | Description | +| --- | --- | | `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. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. | To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. **Bash** + ```bash GIT_USER= \ CURRENT_BRANCH=master \ @@ -107,15 +107,16 @@ GIT_USER= \ ``` **Windows** + ```batch cmd /C "set GIT_USER= && set CURRENT_BRANCH=master && set USE_SSH=true && yarn run publish-gh-pages" ``` There are also two optional parameters that are set as environment variables: -| Name | Description | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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. | +| Name | Description | +| --- | --- | +| `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. | If you run into issues related to SSH keys, visit [GitHub's authentication documentation](https://help.github.com/articles/connecting-to-github-with-ssh/). @@ -196,14 +197,16 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications). You can work around this by: -- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. -e.g. + +- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. e.g. + ```bash CUSTOM_COMMIT_MESSAGE="[skip ci]" \ yarn run publish-gh-pages # or `npm run publish-gh-pages` ``` - Alternatively, you can work around this by creating a basic CircleCI config with the following contents: + ```yaml # CircleCI 2.0 Config File # This config file will prevent tests from being run on the gh-pages branch. @@ -259,8 +262,8 @@ Steps to configure your Docusaurus-powered site on Netlify. 1. Select the branch to deploy. Default is `master` 1. Configure your build steps: - * For your build command enter: `cd website; npm install; npm run build;` - * For publish directory: `website/build/` (use the `projectName` from your `siteConfig`) + - For your build command enter: `cd website; npm install; npm run build;` + - For publish directory: `website/build/` (use the `projectName` from your `siteConfig`) 1. Click **Deploy site** @@ -274,22 +277,22 @@ Render offers free [static site](https://render.com/docs/static-sites) hosting w 2. Select the branch to deploy. The default is `master`. -2. Enter the following values during creation. +3. Enter the following values during creation. - | Field | Value | - | ------- | ----- | - | **Environment** | `Static Site` | - | **Build Command** | `cd website; yarn install; yarn build` | - | **Publish Directory** | `website/build/` | + | Field | Value | + | --------------------- | -------------------------------------- | + | **Environment** | `Static Site` | + | **Build Command** | `cd website; yarn install; yarn build` | + | **Publish Directory** | `website/build/` | - `projectName` is the value you defined in your `siteConfig.js`. + `projectName` is the value you defined in your `siteConfig.js`. - ```javascript{7} - const siteConfig = { - // ... - projectName: 'your-project-name', - // ... - ``` + ```javascript{7} + const siteConfig = { + // ... + projectName: 'your-project-name', + // ... + ``` That's it! Your app will be live on your Render URL as soon as the build finishes. diff --git a/website-1.x/versioned_docs/version-1.14.3/guides-translation.md b/website-1.x/versioned_docs/version-1.14.3/guides-translation.md index b06e1bc1e155..f4f9ac73931e 100644 --- a/website-1.x/versioned_docs/version-1.14.3/guides-translation.md +++ b/website-1.x/versioned_docs/version-1.14.3/guides-translation.md @@ -28,13 +28,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 `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 @@ -88,11 +88,11 @@ Running the script will generate a `website/i18n/en.json` file containing all th 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` ### Custom Translation Strings @@ -112,7 +112,7 @@ If you want to add additional custom translation strings or override any of the } } }, - "pages-strings" : { + "pages-strings": { "id3": "string3", "id4": "string4" } @@ -129,8 +129,8 @@ Here is an example: "localized-strings": { "translation": "Translations and Localization" }, - "pages-strings" : { - "Help Translate|recruit community translators for your project": "Help Us Translate" + "pages-strings": { + "Help Translate|recruit community translators for your project": "Help Us Translate" } } ``` @@ -178,12 +178,11 @@ Below is an example Crowdin configuration for the respective languages: German, ```yaml project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID api_key_env: CROWDIN_DOCUSAURUS_API_KEY -base_path: "./" +base_path: './' preserve_hierarchy: true files: - - - source: '/docs/**/*.md' + - source: '/docs/**/*.md' translation: '/website/translated_docs/%locale%/**/%original_file_name%' languages_mapping: &anchor locale: diff --git a/website-1.x/versioned_docs/version-1.9.x/api-commands.md b/website-1.x/versioned_docs/version-1.9.x/api-commands.md index 6a761c756014..8c7de60986a4 100644 --- a/website-1.x/versioned_docs/version-1.9.x/api-commands.md +++ b/website-1.x/versioned_docs/version-1.9.x/api-commands.md @@ -6,8 +6,8 @@ original_id: commands Docusaurus provides a set of scripts to help you generate, serve, and deploy your website. These scripts can be invoked with the `run` command when using Yarn or npm. Some common commands are: -* [`yarn run start`](api-commands.md#docusaurus-start-port-number): build and serve the website from a local server -* [`yarn run examples`](api-commands.md#docusaurus-examples): create example configuration files +- [`yarn run start`](api-commands.md#docusaurus-start-port-number): build and serve the website from a local server +- [`yarn run examples`](api-commands.md#docusaurus-examples): create example configuration files ## Running from the command line @@ -57,10 +57,10 @@ Docusaurus provides some default mappings to allow you to run commands following Alias: `build`. -| Options | Default | Description | -| -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | +| Options | Default | Description | +| --- | --- | --- | | `--skip-image-compression` | `false` | Skip compression of image assets. You usually won't want to skip this unless your images have already been optimized. | -| `--skip-next-release` | `false` | Skip the next release documents when versioning is enabled. This will not build HTML files for documents in `/docs` directory.| +| `--skip-next-release` | `false` | Skip the next release documents when versioning is enabled. This will not build HTML files for documents in `/docs` directory. | Generates the static website, applying translations if necessary. Useful for building the website prior to deployment. @@ -72,9 +72,9 @@ See also [`docusaurus-start`](api-commands.md#docusaurus-start). Alias: `examples` -| Arguments | Default | Description | -| ----------- | ------- | ---------------------------------------------------------------------------------------------------- | -| `` | - | Specify a feature `translations` or `versions` to generate the extra example files for that feature. | +| Arguments | Default | Description | +| --- | --- | --- | +| `` | - | Specify a feature `translations` or `versions` to generate the extra example files for that feature. | **Example** @@ -94,8 +94,8 @@ Alias: `publish-gh-pages` The following environment variables are 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. +- `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. **Example** @@ -105,13 +105,13 @@ GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages The following environment variables are [set by CircleCI](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. +- `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". +- `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". You can learn more about configuring automatic deployments with CircleCI in the [Publishing guide](getting-started-publishing.md). @@ -144,10 +144,10 @@ Alias: `start`. This command will build the static website, apply translations if necessary, and then start a local server. -| Options | Default | Description | -| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `--port ` | `3000` | The website will be served from port 3000 by default, but if the port is taken up, Docusaurus will attempt to find an available one. | -| `--watch` | - | Whether to watch the files and live reload the page when files are changed. Defaults to true. Disable this by using `--no-watch`. | +| Options | Default | Description | +| --- | --- | --- | +| `--port ` | `3000` | The website will be served from port 3000 by default, but if the port is taken up, Docusaurus will attempt to find an available one. | +| `--watch` | - | Whether to watch the files and live reload the page when files are changed. Defaults to true. Disable this by using `--no-watch`. | You can specify the browser application to be opened by setting the `BROWSER` environment variable before the command, e.g.: diff --git a/website-1.x/versioned_docs/version-1.9.x/api-doc-markdown.md b/website-1.x/versioned_docs/version-1.9.x/api-doc-markdown.md index fdc7605c2fa4..fb9c8983b294 100644 --- a/website-1.x/versioned_docs/version-1.9.x/api-doc-markdown.md +++ b/website-1.x/versioned_docs/version-1.9.x/api-doc-markdown.md @@ -28,6 +28,7 @@ id: doc1 title: My Document sidebar_label: Document --- + ``` Versioned documents have their ids altered to include the version number when they get copied. The new `id` is `version-${version}-${id}` where `${version}` is the version number of that document and `${id}` is the original `id`. Additionally, versioned documents get an added `original_id` field with the original document id. @@ -41,6 +42,7 @@ title: My Document sidebar_label: Document original_id: doc1 --- + ``` `custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from optional fields of `siteConfig.js`. See [siteConfig.js](api-site-config.md) docs for more information. @@ -53,6 +55,7 @@ id: doc-markdown title: Markdown Features custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md --- + ``` ### Blog Posts @@ -76,6 +79,7 @@ author: Frank Li authorURL: http://twitter.com/franchementli authorFBID: 100002976521003 --- + ``` ## Extra Features @@ -133,7 +137,6 @@ will lead to a table of contents of the functions: and each function will link to their corresponding sections in the page. - ### Language-specific Code Tabs Display code in multiple programming languages using code tabs. First, mark the start and end of a code tabs group, by using `` and `` respectively in your markdown. Then start each tab with ``. @@ -146,15 +149,19 @@ produces this: + ```js console.log('Hello, world!'); ``` + + ```py print('Hello, world!') ``` + ```C #include @@ -165,6 +172,7 @@ int main() { ``` + ```Pascal program HelloWorld; begin diff --git a/website-1.x/versioned_docs/version-1.9.x/api-pages.md b/website-1.x/versioned_docs/version-1.9.x/api-pages.md index b9c8c3459e8d..e6981ca9a340 100644 --- a/website-1.x/versioned_docs/version-1.9.x/api-pages.md +++ b/website-1.x/versioned_docs/version-1.9.x/api-pages.md @@ -72,8 +72,8 @@ module.exports = MyPage; This will be translated to a description metadata tag on the generated HTML. ```html - - + + ``` ## Page Require Paths @@ -108,11 +108,11 @@ A React container component using Docusaurus styles. Has optional padding and ba **Props** -| Prop | Type | Default | Description | -| ------------ | ---------------------------------------------------------- | ------- | ----------------------------------- | -| `padding` | Array of `'all'`, `'bottom'`, `'left'`, `'right'`, `'top'` | `[]` | Positions of the padding. | -| `background` | One of `'dark'`, `'highlight'`, `'light'` | `null` | Background styling of the element. | -| `className` | String | - | Custom class to add to the element. | +| Prop | Type | Default | Description | +| --- | --- | --- | --- | +| `padding` | Array of `'all'`, `'bottom'`, `'left'`, `'right'`, `'top'` | `[]` | Positions of the padding. | +| `background` | One of `'dark'`, `'highlight'`, `'light'` | `null` | Background styling of the element. | +| `className` | String | - | Custom class to add to the element. | **Example** @@ -131,23 +131,23 @@ A React component to organize text and images. **Props** -| Prop | Type | Default | Description | -| ----------- | ----------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------- | -| `align` | One of `'left'`, `'center'`, `'right'` | `'left'` | Text alignment of content. | -| `layout` | One of `'twoColumn'`, `'threeColumn'`, `'fourColumn'` | `'twoColumn'` | Number of column sections in the `GridBlock`. | -| `className` | String | - | Custom class to add to the element. | -| `contents` | Array of content objects | `[]` | Contents of each section of the GridBlock. Refer to the next table for the fields available on a content object. | +| Prop | Type | Default | Description | +| --- | --- | --- | --- | +| `align` | One of `'left'`, `'center'`, `'right'` | `'left'` | Text alignment of content. | +| `layout` | One of `'twoColumn'`, `'threeColumn'`, `'fourColumn'` | `'twoColumn'` | Number of column sections in the `GridBlock`. | +| `className` | String | - | Custom class to add to the element. | +| `contents` | Array of content objects | `[]` | Contents of each section of the GridBlock. Refer to the next table for the fields available on a content object. | **Content Object** -| Key | Type | Default | Description | -| ------------ | ----------------------------------------------- | -------- | ----------------------------------------------------------------- | -| `title` | String | - | The display title of this section, which is parsed using Markdown | -| `content` | String | - | The text of this section, which is parsed using Markdown | -| `image` | String | - | The path of the display image | -| `imageAlt` | String | - | The text that will be shown in case the image is not available | -| `imageAlign` | One of `'top'`, `'left'`, `'bottom'`, `'right'` | `'left'` | Image alignment relative to the text | -| `imageLink` | String | - | Link destination from clicking the image | +| Key | Type | Default | Description | +| --- | --- | --- | --- | +| `title` | String | - | The display title of this section, which is parsed using Markdown | +| `content` | String | - | The text of this section, which is parsed using Markdown | +| `image` | String | - | The path of the display image | +| `imageAlt` | String | - | The text that will be shown in case the image is not available | +| `imageAlign` | One of `'top'`, `'left'`, `'bottom'`, `'right'` | `'left'` | Image alignment relative to the text | +| `imageLink` | String | - | Link destination from clicking the image | **Example** diff --git a/website-1.x/versioned_docs/version-1.9.x/api-site-config.md b/website-1.x/versioned_docs/version-1.9.x/api-site-config.md index 3809635d4ffc..61fe5b61f960 100644 --- a/website-1.x/versioned_docs/version-1.9.x/api-site-config.md +++ b/website-1.x/versioned_docs/version-1.9.x/api-site-config.md @@ -129,8 +129,7 @@ The default version for the site to be shown. If this is not set, the latest ver #### `docsUrl` [string] -The base url for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. -If unset, it is defaulted to `docs`. +The base url for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. If unset, it is defaulted to `docs`. #### `disableHeaderTitle` [boolean] diff --git a/website-1.x/versioned_docs/version-1.9.x/getting-started-docker.md b/website-1.x/versioned_docs/version-1.9.x/getting-started-docker.md index 90044d055823..5dcf29b2c23a 100644 --- a/website-1.x/versioned_docs/version-1.9.x/getting-started-docker.md +++ b/website-1.x/versioned_docs/version-1.9.x/getting-started-docker.md @@ -14,13 +14,13 @@ To run the local web server: 1. **Build the docker image** -- Enter the folder where you have Docusaurus installed. Run `docker build -t docusaurus-doc .` - Once the build phase finishes, you can verify the image exists by running `docker images`. + Once the build phase finishes, you can verify the image exists by running `docker images`. - > We now include a `Dockerfile` when you install Docusaurus. + > We now include a `Dockerfile` when you install Docusaurus. 2. **Run the Docusaurus container** -- To start docker run `docker run --rm -p 3000:3000 docusaurus-doc` - This will start a docker container with the image `docusaurus-doc`. To see more detailed container info run `docker ps` . + This will start a docker container with the image `docusaurus-doc`. To see more detailed container info run `docker ps` . ## Use docker-compose @@ -37,8 +37,9 @@ Using Compose is a three-step process: 3. Run `docker-compose up` and Compose starts and runs your entire app. We include a basic `docker-compose.yml` in your project: -``` yml -version: "3" + +```yml +version: '3' services: docusaurus: @@ -56,7 +57,6 @@ services: - ./website/sidebars.json:/app/website/sidebars.json - ./website/siteConfig.js:/app/website/siteConfig.js working_dir: /app/website - ``` To run a local web server with `docker-compose` run `docker-compose up`. diff --git a/website-1.x/versioned_docs/version-1.9.x/getting-started-installation.md b/website-1.x/versioned_docs/version-1.9.x/getting-started-installation.md index 64cefdcfcd61..de3a6a70eff7 100644 --- a/website-1.x/versioned_docs/version-1.9.x/getting-started-installation.md +++ b/website-1.x/versioned_docs/version-1.9.x/getting-started-installation.md @@ -16,9 +16,7 @@ We have created an easy script that will get all of the infrastructure set up fo 1. Create a project, if none exists, and change your directory to this project's root. - You will be creating the docs in this directory. The root directory may - contain other files. The Docusaurus installation script will create two new - directories: `docs` and `website`. + You will be creating the docs in this directory. The root directory may contain other files. The Docusaurus installation script will create two new directories: `docs` and `website`. > Commonly, either an existing or newly created GitHub project will be the location for your Docusaurus site, but that is not mandatory to use Docusaurus. @@ -59,15 +57,11 @@ root-directory ## Running the example website -After running the Docusaurus initialization script, `docusaurus-init` as -described in the [Installation](#installing-docusaurus) section, you will have a -runnable, example website to use as your site's base. To run: +After running the Docusaurus initialization script, `docusaurus-init` as described in the [Installation](#installing-docusaurus) section, you will have a runnable, example website to use as your site's base. To run: 1. `cd website` -1. From within the `website` directory, run the local web server using - `yarn start` or `npm start`. -1. Load the example site at http://localhost:3000 if it did not already open - automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which. +1. From within the `website` directory, run the local web server using `yarn start` or `npm start`. +1. Load the example site at http://localhost:3000 if it did not already open automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which. You should see the example site loaded in your web browser. There's also a LiveReload server running and any changes made to the docs and files in the `website` directory will cause the page to refresh. A randomly generated primary and secondary theme color will be picked for you. diff --git a/website-1.x/versioned_docs/version-1.9.x/getting-started-publishing.md b/website-1.x/versioned_docs/version-1.9.x/getting-started-publishing.md index 749f99213183..c032addcd0d1 100644 --- a/website-1.x/versioned_docs/version-1.9.x/getting-started-publishing.md +++ b/website-1.x/versioned_docs/version-1.9.x/getting-started-publishing.md @@ -26,9 +26,9 @@ At this point, you can grab all of the files inside the `website/build` director ### Hosting on a Service: -* [ZEIT Now](#using-zeit-now) -* [GitHub Pages](#using-github-pages) -* [Netlify](#hosting-on-netlify) +- [ZEIT Now](#using-zeit-now) +- [GitHub Pages](#using-github-pages) +- [Netlify](#hosting-on-netlify) ### Using ZEIT Now @@ -60,17 +60,16 @@ Docusaurus was designed to work really well with one of the most popular hosting > Even if your repository is private, anything published to a `gh-pages` branch will be [public](https://help.github.com/articles/user-organization-and-project-pages/). -__Note:__ When you deploy as user/organization page, the publish script will deploy these sites to the root of the __`master`__ branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in __another branch of the _username_.github.io repo__ (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code). +**Note:** When you deploy as user/organization page, the publish script will deploy these sites to the root of the **`master`** branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in **another branch of the _username_.github.io repo** (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code). 2. You will need to modify the file `website/siteConfig.js` and add the required parameters. -| Name | Description | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. | -| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". | -| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" | -| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | - +| Name | Description | +| --- | --- | +| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. | +| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". | +| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" | +| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. | ```js const siteConfig = { @@ -85,14 +84,14 @@ const siteConfig = { In case you want to deploy as a user or organization site, specify the project name as `.github.io` or `.github.io`. E.g. If your GitHub username is "user42" then _user42.github.io_, or in the case of an organization name of "org123", it will be _org123.github.io_. -__Note:__ Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images. +**Note:** Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images. > While we recommend setting the `projectName` and `organizationName` in `siteConfig.js`, you can also use environment variables `ORGANIZATION_NAME` and `PROJECT_NAME`. 3. Now you have to specify the git user as an environment variable, and run the script [`publish-gh-pages`](./api-commands.md#docusaurus-publish) -| Name | Description | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| Name | Description | +| --- | --- | | `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. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. | To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. @@ -106,9 +105,9 @@ GIT_USER= \ There are also two optional parameters that are set as environment variables: -| Name | Description | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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. | +| Name | Description | +| --- | --- | +| `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. | If you run into issues related to SSH keys, visit [GitHub's authentication documentation](https://help.github.com/articles/connecting-to-github-with-ssh/). @@ -189,14 +188,16 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications). You can work around this by: -- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. -e.g. + +- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. e.g. + ```bash CUSTOM_COMMIT_MESSAGE="[skip ci]" \ yarn run publish-gh-pages # or `npm run publish-gh-pages` ``` - Alternatively you can work around this by creating a basic CircleCI config with the following contents: + ```yaml # CircleCI 2.0 Config File # This config file will prevent tests from being run on the gh-pages branch. @@ -252,8 +253,8 @@ Steps to configure your Docusaurus-powered site on Netlify. 1. Select the branch to deploy. Default is `master` 1. Configure your build steps: - * For your build command enter: `cd website; npm install; npm run build;` - * For publish directory: `website/build/` (use the `projectName` from your `siteConfig`) + - For your build command enter: `cd website; npm install; npm run build;` + - For publish directory: `website/build/` (use the `projectName` from your `siteConfig`) 1. Click **Deploy site** diff --git a/website-1.x/versioned_docs/version-1.9.x/getting-started-site-creation.md b/website-1.x/versioned_docs/version-1.9.x/getting-started-site-creation.md index ef40e8c7059b..bf0a2a996d69 100644 --- a/website-1.x/versioned_docs/version-1.9.x/getting-started-site-creation.md +++ b/website-1.x/versioned_docs/version-1.9.x/getting-started-site-creation.md @@ -43,7 +43,6 @@ To create a fully functional site, you only need to do a few steps: id: intro title: Getting Started --- - My new content here.. ``` @@ -72,18 +71,22 @@ If you prefer to have your landing page be straight to your documentation, you c 1. Add a [custom static `index.html` page](guides-custom-pages.md#adding-static-pages) in the `website/static` directory with the following contents: ```html - + - - + + Your Site Title Here - If you are not redirected automatically, follow this link. + If you are not redirected automatically, follow this + link. ``` diff --git a/website-1.x/versioned_docs/version-1.9.x/guides-blog.md b/website-1.x/versioned_docs/version-1.9.x/guides-blog.md index c627505c4c54..7fcda852852a 100644 --- a/website-1.x/versioned_docs/version-1.9.x/guides-blog.md +++ b/website-1.x/versioned_docs/version-1.9.x/guides-blog.md @@ -31,7 +31,6 @@ authorURL: https://twitter.com/foobarbaz authorFBID: 503283835 title: Introducing Docusaurus --- - Lorem Ipsum... ``` @@ -39,11 +38,11 @@ Lorem Ipsum... The only required field is `title`; however, we provide options to add author information to your blog post as well. -* `author` - The text label of the author byline. -* `authorURL` - The URL associated with the author. This could be a Twitter, GitHub, Facebook account, etc. -* `authorFBID` - The Facebook profile ID that is used to fetch the profile picture. -* `authorImageURL` - The URL to the author's image. (Note: If you use both `authorFBID` and `authorImageURL`, `authorFBID` will take precedence. Don't include `authorFBID` if you want `authorImageURL` to appear.) -* `title` - The blog post title. +- `author` - The text label of the author byline. +- `authorURL` - The URL associated with the author. This could be a Twitter, GitHub, Facebook account, etc. +- `authorFBID` - The Facebook profile ID that is used to fetch the profile picture. +- `authorImageURL` - The URL to the author's image. (Note: If you use both `authorFBID` and `authorImageURL`, `authorFBID` will take precedence. Don't include `authorFBID` if you want `authorImageURL` to appear.) +- `title` - The blog post title. ## Summary Truncation @@ -53,7 +52,6 @@ Use the `` marker in your blog post to represent what will be sho --- title: Truncation Example --- - All this will be part of the blog post summary. Even this. @@ -121,18 +119,19 @@ To do this: You can use this template: ```html - + - - + + Title of Your Blog - If you are not redirected automatically, follow this link. + If you are not redirected automatically, follow this + link. ``` diff --git a/website-1.x/versioned_docs/version-1.9.x/guides-search.md b/website-1.x/versioned_docs/version-1.9.x/guides-search.md index 68d65e261de4..3baebef4da47 100644 --- a/website-1.x/versioned_docs/version-1.9.x/guides-search.md +++ b/website-1.x/versioned_docs/version-1.9.x/guides-search.md @@ -26,18 +26,18 @@ const siteConfig = { ## Extra Search Options -You can also specify extra [search options used by Algolia](https://community.algolia.com/docsearch/documentation/) by using an `algoliaOptions` field in `algolia`. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be [found here](https://www.algolia.com/doc/api-reference/api-parameters/#overview). - -```js -const siteConfig = { - ... - algolia: { - ... - algoliaOptions: { - facetFilters: [ "language:LANGUAGE", "version:VERSION" ] - } - }, -}; +You can also specify extra [search options used by Algolia](https://community.algolia.com/docsearch/documentation/) by using an `algoliaOptions` field in `algolia`. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be [found here](https://www.algolia.com/doc/api-reference/api-parameters/#overview). + +```js +const siteConfig = { + ... + algolia: { + ... + algoliaOptions: { + facetFilters: [ "language:LANGUAGE", "version:VERSION" ] + } + }, +}; ``` Algolia might provide you with [extra search options](https://community.algolia.com/docsearch/documentation/). If so, you should add them to the `algoliaOptions` object. @@ -64,16 +64,16 @@ const siteConfig = { ## Customizing the placeholder -If you want to change the placeholder (which defaults to *Search*), add the `placeholder` field in your config. For example, you may want the search bar to display *Ask me something*: +If you want to change the placeholder (which defaults to _Search_), add the `placeholder` field in your config. For example, you may want the search bar to display _Ask me something_: ```js -const siteConfig = { - ... - algolia: { - ... +const siteConfig = { + ... + algolia: { + ... placeholder: 'Ask me something' - }, -}; + }, +}; ``` ## Disabling the Search Bar diff --git a/website-1.x/versioned_docs/version-1.9.x/guides-translation.md b/website-1.x/versioned_docs/version-1.9.x/guides-translation.md index 06eee72e8788..e8e68b947def 100644 --- a/website-1.x/versioned_docs/version-1.9.x/guides-translation.md +++ b/website-1.x/versioned_docs/version-1.9.x/guides-translation.md @@ -28,13 +28,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 `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 @@ -88,11 +88,11 @@ Running the script will generate a `website/i18n/en.json` file containing all th 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` ### Custom Translation Strings @@ -112,7 +112,7 @@ If you want to add additional custom translation strings, or override any of the } } }, - "pages-strings" : { + "pages-strings": { "id3": "string3", "id4": "string4" } @@ -129,8 +129,8 @@ Here is an example: "localized-strings": { "translation": "Translations and Localization" }, - "pages-strings" : { - "Help Translate|recruit community translators for your project": "Help Us Translate" + "pages-strings": { + "Help Translate|recruit community translators for your project": "Help Us Translate" } } ``` @@ -178,12 +178,11 @@ Below is an example Crowdin configuration for the respective languages: German, ```yaml project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID api_key_env: CROWDIN_DOCUSAURUS_API_KEY -base_path: "./" +base_path: './' preserve_hierarchy: true files: - - - source: '/docs/**/*.md' + - source: '/docs/**/*.md' translation: '/website/translated_docs/%locale%/**/%original_file_name%' languages_mapping: &anchor locale: diff --git a/website-1.x/versioned_docs/version-1.9.x/tutorial-create-new-site.md b/website-1.x/versioned_docs/version-1.9.x/tutorial-create-new-site.md index da189cf40de0..94e5108bd7bf 100644 --- a/website-1.x/versioned_docs/version-1.9.x/tutorial-create-new-site.md +++ b/website-1.x/versioned_docs/version-1.9.x/tutorial-create-new-site.md @@ -59,7 +59,6 @@ The following contents will be created in your current directory. Some example d └── yarn.lock ``` - 2. Run `cd website` to go into the `website` directory. 1. Run `npm start` or `yarn start`. diff --git a/website/docs/configuration.md b/website/docs/configuration.md index 4a73cb6217bd..3b9a289a42a1 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -42,7 +42,10 @@ List the installed [themes](using-themes.md), [plugins](using-plugins.md), and [ // docusaurus.config.js module.exports = { // ... - plugins: ['@docusaurus/plugin-content-blog', '@docusaurus/plugin-content-pages'], + plugins: [ + '@docusaurus/plugin-content-blog', + '@docusaurus/plugin-content-pages', + ], themes: ['@docusaurus/theme-classic'], }; ``` diff --git a/website/docs/deployment.md b/website/docs/deployment.md index 694791e4e6f9..4a0eba087315 100644 --- a/website/docs/deployment.md +++ b/website/docs/deployment.md @@ -87,11 +87,13 @@ There are two more optional parameters that are set as environment variables: Finally, to deploy your site to GitHub Pages, run: **Bash** + ```bash GIT_USER= yarn deploy ``` **Windows** + ```batch cmd /C "set GIT_USER= && yarn deploy" ``` diff --git a/website/docs/docusaurus.config.js.md b/website/docs/docusaurus.config.js.md index f772ab482322..d0b3a622d42c 100644 --- a/website/docs/docusaurus.config.js.md +++ b/website/docs/docusaurus.config.js.md @@ -272,7 +272,8 @@ module.exports = { 'https://docusaurus.io/script.js', // Object format. { - src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js', + src: + 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js', async: true, }, ], @@ -294,7 +295,7 @@ module.exports = { // String format. 'https://docusaurus.io/style.css', // Object format. - { + { href: 'http://mydomain.com/style.css', type: 'text/css', }, diff --git a/website/docs/installation.md b/website/docs/installation.md index 4df5cd3378b3..a98051d0c7aa 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -24,7 +24,6 @@ Example: npx @docusaurus/init@next init my-website classic ``` - If you do not specify `name` or `template`, it will prompt you for them. We recommend the `classic` template so that you can get started quickly and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus. ## Project structure diff --git a/website/docs/introduction.md b/website/docs/introduction.md index 8ce102d4721c..aea8fab09b8a 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -59,7 +59,7 @@ Our shared goal β€” to help your users find what they need fast, and understand - Share your code in live editors to get your users love your products on the spot - πŸ” **Search** Your full site is searchable - 🌍 **i18n** (_coming soon_) -- πŸ’Ύ **Document Versioning** Helps you keep documentation in sync with project releases. +- πŸ’Ύ **Document Versioning** Helps you keep documentation in sync with project releases. Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast. diff --git a/website/docs/migrating-from-v1-to-v2.md b/website/docs/migrating-from-v1-to-v2.md index ad8ce4e3609c..6aa4657d8fb3 100644 --- a/website/docs/migrating-from-v1-to-v2.md +++ b/website/docs/migrating-from-v1-to-v2.md @@ -514,17 +514,21 @@ For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord ch > ⚠️ Although we've implemented docs versioning since 2.0.0-alpha.37, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work. ## Changes from v1 + - Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for reasoning on v1's problem ### Migrate your versioned_docs frontmatter + - Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation. -Example, you have a `docs/hello.md`. +Example, you have a `docs/hello.md`. + ```md --- id: hello title: Hello, World ! --- + Hi, Endilie here :) ``` @@ -538,6 +542,7 @@ id: version-1.0.0-hello title: Hello, World ! original_id: hello --- + Hi, Endilie here :) ``` @@ -548,6 +553,7 @@ In comparison, Docusaurus 2 `website/versioned_docs/version-1.0.0/hello.md` look id: hello title: Hello, World ! --- + Hi, Endilie here :) ``` @@ -565,22 +571,23 @@ title: Hello, World ! Hi, Endilie here :) ``` - ### Migrate your versioned_sidebars -- Refer to versioned_docs id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1). +- Refer to versioned_docs id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1). Because in v1 there is a good chance someone created a new file with front matter id `"version-${version}-${id}"` that can conflict with versioned_docs id. Example, Docusaurus 1 can't differentiate `docs/xxx.md` + ```md --- id: version-1.0.0-hello --- + Another content ``` -and `website/versioned_docs/version-1.0.0/hello.md` +and `website/versioned_docs/version-1.0.0/hello.md` ```md --- @@ -588,6 +595,7 @@ id: version-1.0.0-hello title: Hello, World ! original_id: hello --- + Hi, Endilie here :) ``` @@ -596,6 +604,7 @@ Since we don't allow `/` in v1 & v2 for frontmatter, conflicts are less likely t So v1 users need to migrate their versioned_sidebars file Example `versioned_sidebars/version-1.0.0-sidebars.json`: + ```json {2-3,5-6,9-10} { + "version-1.0.0/docs": { @@ -617,12 +626,10 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`: In v2, we use snapshot approach on documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality). For example, if your `versions.json` looks like this in v1 + ```json // versions.json -[ - "1.1.0", - "1.0.0" -] +["1.1.0", "1.0.0"] ``` Docusaurus v1 creates versioned docs **if and only if the doc content is different**. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is `hello.md`. @@ -656,4 +663,4 @@ website β”œβ”€β”€ versioned_sidebars β”‚ β”œβ”€β”€ version-1.1.0-sidebars.json β”‚ └── version-1.0.0-sidebars.json -``` \ No newline at end of file +``` diff --git a/website/docs/sidebar.md b/website/docs/sidebar.md index fb74d725863c..bbc1aadefa5d 100644 --- a/website/docs/sidebar.md +++ b/website/docs/sidebar.md @@ -30,15 +30,16 @@ A sidebar object is defined like this. ```typescript type Sidebar = { - [sidebarId: string]: { - [sidebarCategory: string]: SidebarItem[]; - } | SidebarItem[]; -} + [sidebarId: string]: + | { + [sidebarCategory: string]: SidebarItem[]; + } + | SidebarItem[]; +}; ``` Below is an example of a sidebar object. The key `docs` is the id of the sidebar (can be renamed to something else) and `Getting Started` is a category within the sidebar. `greeting` and `doc1` are both [sidebar item](#sidebar-item). - ```js // sidebars.js module.exports = { @@ -121,10 +122,12 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a ### Doc ```typescript -type SidebarItemDoc = string | { - type: 'doc'; - id: string; -}; +type SidebarItemDoc = + | string + | { + type: 'doc'; + id: string; + }; ``` Sidebar item type that links to a doc page. Example: @@ -204,7 +207,7 @@ type SidebarItemCategory = { type: 'category'; label: string; // Sidebar label text. items: SidebarItem[]; // Array of sidebar items. -} +}; ``` As an example, here's how we created the subcategory for "Docs" under "Guides" in this site: diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index db5df7b41a4c..8c132d556195 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -193,7 +193,7 @@ module.exports = { ### `@docusaurus/plugin-content-docs` -Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. +Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. **Installation** @@ -407,10 +407,9 @@ import thumbnail from './path/to/img.png'; | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. | -| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up).| +| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). | | `size` | `integer` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) | | `min` | `integer` | | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. | | `max` | `integer` | | See `min` above | | `steps` | `integer` | `4` | Configure the number of images generated between `min` and `max` (inclusive) | | `quality` | `integer` | `85` | JPEG compression quality | - diff --git a/website/versioned_docs/version-2.0.0-alpha.36/configuration.md b/website/versioned_docs/version-2.0.0-alpha.36/configuration.md index 4a73cb6217bd..3b9a289a42a1 100644 --- a/website/versioned_docs/version-2.0.0-alpha.36/configuration.md +++ b/website/versioned_docs/version-2.0.0-alpha.36/configuration.md @@ -42,7 +42,10 @@ List the installed [themes](using-themes.md), [plugins](using-plugins.md), and [ // docusaurus.config.js module.exports = { // ... - plugins: ['@docusaurus/plugin-content-blog', '@docusaurus/plugin-content-pages'], + plugins: [ + '@docusaurus/plugin-content-blog', + '@docusaurus/plugin-content-pages', + ], themes: ['@docusaurus/theme-classic'], }; ``` diff --git a/website/versioned_docs/version-2.0.0-alpha.36/deployment.md b/website/versioned_docs/version-2.0.0-alpha.36/deployment.md index f2234f89deb3..41d63fea3bf2 100644 --- a/website/versioned_docs/version-2.0.0-alpha.36/deployment.md +++ b/website/versioned_docs/version-2.0.0-alpha.36/deployment.md @@ -87,11 +87,13 @@ There are two more optional parameters that are set as environment variables: Finally, to deploy your site to GitHub Pages, run: **Bash** + ```bash GIT_USER= yarn deploy ``` **Windows** + ```batch cmd /C "set GIT_USER= && yarn deploy" ``` diff --git a/website/versioned_docs/version-2.0.0-alpha.36/docusaurus.config.js.md b/website/versioned_docs/version-2.0.0-alpha.36/docusaurus.config.js.md index f772ab482322..d0b3a622d42c 100644 --- a/website/versioned_docs/version-2.0.0-alpha.36/docusaurus.config.js.md +++ b/website/versioned_docs/version-2.0.0-alpha.36/docusaurus.config.js.md @@ -272,7 +272,8 @@ module.exports = { 'https://docusaurus.io/script.js', // Object format. { - src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js', + src: + 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js', async: true, }, ], @@ -294,7 +295,7 @@ module.exports = { // String format. 'https://docusaurus.io/style.css', // Object format. - { + { href: 'http://mydomain.com/style.css', type: 'text/css', }, diff --git a/website/versioned_docs/version-2.0.0-alpha.36/installation.md b/website/versioned_docs/version-2.0.0-alpha.36/installation.md index 0c7a428c3b0d..92c821b321f2 100644 --- a/website/versioned_docs/version-2.0.0-alpha.36/installation.md +++ b/website/versioned_docs/version-2.0.0-alpha.36/installation.md @@ -24,7 +24,6 @@ Example: npx @docusaurus/init@next init my-website classic ``` - If you do not specify `name` or `template`, it will prompt you for them. We recommend the `classic` template so that you can get started quickly and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus. ## Project structure diff --git a/website/versioned_docs/version-2.0.0-alpha.37/configuration.md b/website/versioned_docs/version-2.0.0-alpha.37/configuration.md index 4a73cb6217bd..3b9a289a42a1 100644 --- a/website/versioned_docs/version-2.0.0-alpha.37/configuration.md +++ b/website/versioned_docs/version-2.0.0-alpha.37/configuration.md @@ -42,7 +42,10 @@ List the installed [themes](using-themes.md), [plugins](using-plugins.md), and [ // docusaurus.config.js module.exports = { // ... - plugins: ['@docusaurus/plugin-content-blog', '@docusaurus/plugin-content-pages'], + plugins: [ + '@docusaurus/plugin-content-blog', + '@docusaurus/plugin-content-pages', + ], themes: ['@docusaurus/theme-classic'], }; ``` diff --git a/website/versioned_docs/version-2.0.0-alpha.37/deployment.md b/website/versioned_docs/version-2.0.0-alpha.37/deployment.md index 694791e4e6f9..4a0eba087315 100644 --- a/website/versioned_docs/version-2.0.0-alpha.37/deployment.md +++ b/website/versioned_docs/version-2.0.0-alpha.37/deployment.md @@ -87,11 +87,13 @@ There are two more optional parameters that are set as environment variables: Finally, to deploy your site to GitHub Pages, run: **Bash** + ```bash GIT_USER= yarn deploy ``` **Windows** + ```batch cmd /C "set GIT_USER= && yarn deploy" ``` diff --git a/website/versioned_docs/version-2.0.0-alpha.37/docusaurus.config.js.md b/website/versioned_docs/version-2.0.0-alpha.37/docusaurus.config.js.md index f772ab482322..d0b3a622d42c 100644 --- a/website/versioned_docs/version-2.0.0-alpha.37/docusaurus.config.js.md +++ b/website/versioned_docs/version-2.0.0-alpha.37/docusaurus.config.js.md @@ -272,7 +272,8 @@ module.exports = { 'https://docusaurus.io/script.js', // Object format. { - src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js', + src: + 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js', async: true, }, ], @@ -294,7 +295,7 @@ module.exports = { // String format. 'https://docusaurus.io/style.css', // Object format. - { + { href: 'http://mydomain.com/style.css', type: 'text/css', }, diff --git a/website/versioned_docs/version-2.0.0-alpha.37/installation.md b/website/versioned_docs/version-2.0.0-alpha.37/installation.md index 4df5cd3378b3..a98051d0c7aa 100644 --- a/website/versioned_docs/version-2.0.0-alpha.37/installation.md +++ b/website/versioned_docs/version-2.0.0-alpha.37/installation.md @@ -24,7 +24,6 @@ Example: npx @docusaurus/init@next init my-website classic ``` - If you do not specify `name` or `template`, it will prompt you for them. We recommend the `classic` template so that you can get started quickly and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus. ## Project structure diff --git a/website/versioned_docs/version-2.0.0-alpha.37/introduction.md b/website/versioned_docs/version-2.0.0-alpha.37/introduction.md index 8ce102d4721c..aea8fab09b8a 100644 --- a/website/versioned_docs/version-2.0.0-alpha.37/introduction.md +++ b/website/versioned_docs/version-2.0.0-alpha.37/introduction.md @@ -59,7 +59,7 @@ Our shared goal β€” to help your users find what they need fast, and understand - Share your code in live editors to get your users love your products on the spot - πŸ” **Search** Your full site is searchable - 🌍 **i18n** (_coming soon_) -- πŸ’Ύ **Document Versioning** Helps you keep documentation in sync with project releases. +- πŸ’Ύ **Document Versioning** Helps you keep documentation in sync with project releases. Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast. diff --git a/website/versioned_docs/version-2.0.0-alpha.37/lifecycle-apis.md b/website/versioned_docs/version-2.0.0-alpha.37/lifecycle-apis.md index 39320c64a50a..b9b8d5f3e56f 100644 --- a/website/versioned_docs/version-2.0.0-alpha.37/lifecycle-apis.md +++ b/website/versioned_docs/version-2.0.0-alpha.37/lifecycle-apis.md @@ -281,7 +281,7 @@ module.exports = function(context, options) { tagName: 'script', attributes: { charset: 'utf-8', - src: '/noflash.js' + src: '/noflash.js', }, }, ], diff --git a/website/versioned_docs/version-2.0.0-alpha.37/migrating-from-v1-to-v2.md b/website/versioned_docs/version-2.0.0-alpha.37/migrating-from-v1-to-v2.md index 3686da4a60a9..b6d01b226e29 100644 --- a/website/versioned_docs/version-2.0.0-alpha.37/migrating-from-v1-to-v2.md +++ b/website/versioned_docs/version-2.0.0-alpha.37/migrating-from-v1-to-v2.md @@ -514,17 +514,21 @@ For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord ch > ⚠️ Although we've implemented docs versioning since 2.0.0-alpha.37, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work. ## Changes from v1 + - Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for reasoning on v1's problem ### Migrate your versioned_docs frontmatter + - Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation. -Example, you have a `docs/hello.md`. +Example, you have a `docs/hello.md`. + ```md --- id: hello title: Hello, World ! --- + Hi, Endilie here :) ``` @@ -538,6 +542,7 @@ id: version-1.0.0-hello title: Hello, World ! original_id: hello --- + Hi, Endilie here :) ``` @@ -548,6 +553,7 @@ In comparison, Docusaurus 2 `website/versioned_docs/version-1.0.0/hello.md` look id: hello title: Hello, World ! --- + Hi, Endilie here :) ``` @@ -565,22 +571,23 @@ title: Hello, World ! Hi, Endilie here :) ``` - ### Migrate your versioned_sidebars -- Refer to versioned_docs id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1). +- Refer to versioned_docs id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1). Because in v1 there is a good chance someone created a new file with front matter id `"version-${version}-${id}"` that can conflict with versioned_docs id. Example, Docusaurus 1 can't differentiate `docs/xxx.md` + ```md --- id: version-1.0.0-hello --- + Another content ``` -and `website/versioned_docs/version-1.0.0/hello.md` +and `website/versioned_docs/version-1.0.0/hello.md` ```md --- @@ -588,6 +595,7 @@ id: version-1.0.0-hello title: Hello, World ! original_id: hello --- + Hi, Endilie here :) ``` @@ -596,6 +604,7 @@ Since we don't allow `/` in v1 & v2 for frontmatter, conflicts are less likely t So v1 users need to migrate their versioned_sidebars file Example `versioned_sidebars/version-1.0.0-sidebars.json`: + ```json {2-3,5-6,9-10} { + "version-1.0.0/docs": { @@ -617,12 +626,10 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`: In v2, we use snapshot approach on documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality). For example, if your `versions.json` looks like this in v1 + ```json // versions.json -[ - "1.1.0", - "1.0.0" -] +["1.1.0", "1.0.0"] ``` Docusaurus v1 creates versioned docs **if and only if the doc content is different**. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is `hello.md`. @@ -656,4 +663,4 @@ website β”œβ”€β”€ versioned_sidebars β”‚ β”œβ”€β”€ version-1.1.0-sidebars.json β”‚ └── version-1.0.0-sidebars.json -``` \ No newline at end of file +``` diff --git a/website/versioned_docs/version-2.0.0-alpha.37/sidebar.md b/website/versioned_docs/version-2.0.0-alpha.37/sidebar.md index fb74d725863c..bbc1aadefa5d 100644 --- a/website/versioned_docs/version-2.0.0-alpha.37/sidebar.md +++ b/website/versioned_docs/version-2.0.0-alpha.37/sidebar.md @@ -30,15 +30,16 @@ A sidebar object is defined like this. ```typescript type Sidebar = { - [sidebarId: string]: { - [sidebarCategory: string]: SidebarItem[]; - } | SidebarItem[]; -} + [sidebarId: string]: + | { + [sidebarCategory: string]: SidebarItem[]; + } + | SidebarItem[]; +}; ``` Below is an example of a sidebar object. The key `docs` is the id of the sidebar (can be renamed to something else) and `Getting Started` is a category within the sidebar. `greeting` and `doc1` are both [sidebar item](#sidebar-item). - ```js // sidebars.js module.exports = { @@ -121,10 +122,12 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a ### Doc ```typescript -type SidebarItemDoc = string | { - type: 'doc'; - id: string; -}; +type SidebarItemDoc = + | string + | { + type: 'doc'; + id: string; + }; ``` Sidebar item type that links to a doc page. Example: @@ -204,7 +207,7 @@ type SidebarItemCategory = { type: 'category'; label: string; // Sidebar label text. items: SidebarItem[]; // Array of sidebar items. -} +}; ``` As an example, here's how we created the subcategory for "Docs" under "Guides" in this site: diff --git a/website/versioned_docs/version-2.0.0-alpha.37/theme-classic.md b/website/versioned_docs/version-2.0.0-alpha.37/theme-classic.md index af67036466ce..b2beec4a8803 100644 --- a/website/versioned_docs/version-2.0.0-alpha.37/theme-classic.md +++ b/website/versioned_docs/version-2.0.0-alpha.37/theme-classic.md @@ -1,6 +1,6 @@ --- id: theme-classic -title: "@docusaurus/theme-classic" +title: '@docusaurus/theme-classic' --- > :warning: _This section is a work in progress._ diff --git a/website/versioned_docs/version-2.0.0-alpha.37/using-plugins.md b/website/versioned_docs/version-2.0.0-alpha.37/using-plugins.md index db5df7b41a4c..8c132d556195 100644 --- a/website/versioned_docs/version-2.0.0-alpha.37/using-plugins.md +++ b/website/versioned_docs/version-2.0.0-alpha.37/using-plugins.md @@ -193,7 +193,7 @@ module.exports = { ### `@docusaurus/plugin-content-docs` -Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. +Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. **Installation** @@ -407,10 +407,9 @@ import thumbnail from './path/to/img.png'; | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. | -| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up).| +| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). | | `size` | `integer` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) | | `min` | `integer` | | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. | | `max` | `integer` | | See `min` above | | `steps` | `integer` | `4` | Configure the number of images generated between `min` and `max` (inclusive) | | `quality` | `integer` | `85` | JPEG compression quality | - diff --git a/website/versioned_docs/version-2.0.0-alpha.38/configuration.md b/website/versioned_docs/version-2.0.0-alpha.38/configuration.md index 4a73cb6217bd..3b9a289a42a1 100644 --- a/website/versioned_docs/version-2.0.0-alpha.38/configuration.md +++ b/website/versioned_docs/version-2.0.0-alpha.38/configuration.md @@ -42,7 +42,10 @@ List the installed [themes](using-themes.md), [plugins](using-plugins.md), and [ // docusaurus.config.js module.exports = { // ... - plugins: ['@docusaurus/plugin-content-blog', '@docusaurus/plugin-content-pages'], + plugins: [ + '@docusaurus/plugin-content-blog', + '@docusaurus/plugin-content-pages', + ], themes: ['@docusaurus/theme-classic'], }; ``` diff --git a/website/versioned_docs/version-2.0.0-alpha.38/deployment.md b/website/versioned_docs/version-2.0.0-alpha.38/deployment.md index 694791e4e6f9..4a0eba087315 100644 --- a/website/versioned_docs/version-2.0.0-alpha.38/deployment.md +++ b/website/versioned_docs/version-2.0.0-alpha.38/deployment.md @@ -87,11 +87,13 @@ There are two more optional parameters that are set as environment variables: Finally, to deploy your site to GitHub Pages, run: **Bash** + ```bash GIT_USER= yarn deploy ``` **Windows** + ```batch cmd /C "set GIT_USER= && yarn deploy" ``` diff --git a/website/versioned_docs/version-2.0.0-alpha.38/docusaurus.config.js.md b/website/versioned_docs/version-2.0.0-alpha.38/docusaurus.config.js.md index f772ab482322..d0b3a622d42c 100644 --- a/website/versioned_docs/version-2.0.0-alpha.38/docusaurus.config.js.md +++ b/website/versioned_docs/version-2.0.0-alpha.38/docusaurus.config.js.md @@ -272,7 +272,8 @@ module.exports = { 'https://docusaurus.io/script.js', // Object format. { - src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js', + src: + 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js', async: true, }, ], @@ -294,7 +295,7 @@ module.exports = { // String format. 'https://docusaurus.io/style.css', // Object format. - { + { href: 'http://mydomain.com/style.css', type: 'text/css', }, diff --git a/website/versioned_docs/version-2.0.0-alpha.38/installation.md b/website/versioned_docs/version-2.0.0-alpha.38/installation.md index 4df5cd3378b3..a98051d0c7aa 100644 --- a/website/versioned_docs/version-2.0.0-alpha.38/installation.md +++ b/website/versioned_docs/version-2.0.0-alpha.38/installation.md @@ -24,7 +24,6 @@ Example: npx @docusaurus/init@next init my-website classic ``` - If you do not specify `name` or `template`, it will prompt you for them. We recommend the `classic` template so that you can get started quickly and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus. ## Project structure diff --git a/website/versioned_docs/version-2.0.0-alpha.38/introduction.md b/website/versioned_docs/version-2.0.0-alpha.38/introduction.md index 8ce102d4721c..aea8fab09b8a 100644 --- a/website/versioned_docs/version-2.0.0-alpha.38/introduction.md +++ b/website/versioned_docs/version-2.0.0-alpha.38/introduction.md @@ -59,7 +59,7 @@ Our shared goal β€” to help your users find what they need fast, and understand - Share your code in live editors to get your users love your products on the spot - πŸ” **Search** Your full site is searchable - 🌍 **i18n** (_coming soon_) -- πŸ’Ύ **Document Versioning** Helps you keep documentation in sync with project releases. +- πŸ’Ύ **Document Versioning** Helps you keep documentation in sync with project releases. Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast. diff --git a/website/versioned_docs/version-2.0.0-alpha.38/migrating-from-v1-to-v2.md b/website/versioned_docs/version-2.0.0-alpha.38/migrating-from-v1-to-v2.md index aaefcca1ccae..f39ef20ce351 100644 --- a/website/versioned_docs/version-2.0.0-alpha.38/migrating-from-v1-to-v2.md +++ b/website/versioned_docs/version-2.0.0-alpha.38/migrating-from-v1-to-v2.md @@ -514,17 +514,21 @@ For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord ch > ⚠️ Although we've implemented docs versioning since 2.0.0-alpha.37, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work. ## Changes from v1 + - Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for reasoning on v1's problem ### Migrate your versioned_docs frontmatter + - Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation. -Example, you have a `docs/hello.md`. +Example, you have a `docs/hello.md`. + ```md --- id: hello title: Hello, World ! --- + Hi, Endilie here :) ``` @@ -538,6 +542,7 @@ id: version-1.0.0-hello title: Hello, World ! original_id: hello --- + Hi, Endilie here :) ``` @@ -548,6 +553,7 @@ In comparison, Docusaurus 2 `website/versioned_docs/version-1.0.0/hello.md` look id: hello title: Hello, World ! --- + Hi, Endilie here :) ``` @@ -565,22 +571,23 @@ title: Hello, World ! Hi, Endilie here :) ``` - ### Migrate your versioned_sidebars -- Refer to versioned_docs id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1). +- Refer to versioned_docs id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1). Because in v1 there is a good chance someone created a new file with front matter id `"version-${version}-${id}"` that can conflict with versioned_docs id. Example, Docusaurus 1 can't differentiate `docs/xxx.md` + ```md --- id: version-1.0.0-hello --- + Another content ``` -and `website/versioned_docs/version-1.0.0/hello.md` +and `website/versioned_docs/version-1.0.0/hello.md` ```md --- @@ -588,6 +595,7 @@ id: version-1.0.0-hello title: Hello, World ! original_id: hello --- + Hi, Endilie here :) ``` @@ -596,6 +604,7 @@ Since we don't allow `/` in v1 & v2 for frontmatter, conflicts are less likely t So v1 users need to migrate their versioned_sidebars file Example `versioned_sidebars/version-1.0.0-sidebars.json`: + ```json {2-3,5-6,9-10} { + "version-1.0.0/docs": { @@ -617,12 +626,10 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`: In v2, we use snapshot approach on documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality). For example, if your `versions.json` looks like this in v1 + ```json // versions.json -[ - "1.1.0", - "1.0.0" -] +["1.1.0", "1.0.0"] ``` Docusaurus v1 creates versioned docs **if and only if the doc content is different**. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is `hello.md`. @@ -656,4 +663,4 @@ website β”œβ”€β”€ versioned_sidebars β”‚ β”œβ”€β”€ version-1.1.0-sidebars.json β”‚ └── version-1.0.0-sidebars.json -``` \ No newline at end of file +``` diff --git a/website/versioned_docs/version-2.0.0-alpha.38/sidebar.md b/website/versioned_docs/version-2.0.0-alpha.38/sidebar.md index fb74d725863c..bbc1aadefa5d 100644 --- a/website/versioned_docs/version-2.0.0-alpha.38/sidebar.md +++ b/website/versioned_docs/version-2.0.0-alpha.38/sidebar.md @@ -30,15 +30,16 @@ A sidebar object is defined like this. ```typescript type Sidebar = { - [sidebarId: string]: { - [sidebarCategory: string]: SidebarItem[]; - } | SidebarItem[]; -} + [sidebarId: string]: + | { + [sidebarCategory: string]: SidebarItem[]; + } + | SidebarItem[]; +}; ``` Below is an example of a sidebar object. The key `docs` is the id of the sidebar (can be renamed to something else) and `Getting Started` is a category within the sidebar. `greeting` and `doc1` are both [sidebar item](#sidebar-item). - ```js // sidebars.js module.exports = { @@ -121,10 +122,12 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a ### Doc ```typescript -type SidebarItemDoc = string | { - type: 'doc'; - id: string; -}; +type SidebarItemDoc = + | string + | { + type: 'doc'; + id: string; + }; ``` Sidebar item type that links to a doc page. Example: @@ -204,7 +207,7 @@ type SidebarItemCategory = { type: 'category'; label: string; // Sidebar label text. items: SidebarItem[]; // Array of sidebar items. -} +}; ``` As an example, here's how we created the subcategory for "Docs" under "Guides" in this site: diff --git a/website/versioned_docs/version-2.0.0-alpha.38/using-plugins.md b/website/versioned_docs/version-2.0.0-alpha.38/using-plugins.md index db5df7b41a4c..8c132d556195 100644 --- a/website/versioned_docs/version-2.0.0-alpha.38/using-plugins.md +++ b/website/versioned_docs/version-2.0.0-alpha.38/using-plugins.md @@ -193,7 +193,7 @@ module.exports = { ### `@docusaurus/plugin-content-docs` -Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. +Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. **Installation** @@ -407,10 +407,9 @@ import thumbnail from './path/to/img.png'; | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. | -| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up).| +| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). | | `size` | `integer` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) | | `min` | `integer` | | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. | | `max` | `integer` | | See `min` above | | `steps` | `integer` | `4` | Configure the number of images generated between `min` and `max` (inclusive) | | `quality` | `integer` | `85` | JPEG compression quality | - diff --git a/website/versioned_docs/version-2.0.0-alpha.39/configuration.md b/website/versioned_docs/version-2.0.0-alpha.39/configuration.md index 4a73cb6217bd..3b9a289a42a1 100644 --- a/website/versioned_docs/version-2.0.0-alpha.39/configuration.md +++ b/website/versioned_docs/version-2.0.0-alpha.39/configuration.md @@ -42,7 +42,10 @@ List the installed [themes](using-themes.md), [plugins](using-plugins.md), and [ // docusaurus.config.js module.exports = { // ... - plugins: ['@docusaurus/plugin-content-blog', '@docusaurus/plugin-content-pages'], + plugins: [ + '@docusaurus/plugin-content-blog', + '@docusaurus/plugin-content-pages', + ], themes: ['@docusaurus/theme-classic'], }; ``` diff --git a/website/versioned_docs/version-2.0.0-alpha.39/deployment.md b/website/versioned_docs/version-2.0.0-alpha.39/deployment.md index 694791e4e6f9..4a0eba087315 100644 --- a/website/versioned_docs/version-2.0.0-alpha.39/deployment.md +++ b/website/versioned_docs/version-2.0.0-alpha.39/deployment.md @@ -87,11 +87,13 @@ There are two more optional parameters that are set as environment variables: Finally, to deploy your site to GitHub Pages, run: **Bash** + ```bash GIT_USER= yarn deploy ``` **Windows** + ```batch cmd /C "set GIT_USER= && yarn deploy" ``` diff --git a/website/versioned_docs/version-2.0.0-alpha.39/docusaurus.config.js.md b/website/versioned_docs/version-2.0.0-alpha.39/docusaurus.config.js.md index f772ab482322..d0b3a622d42c 100644 --- a/website/versioned_docs/version-2.0.0-alpha.39/docusaurus.config.js.md +++ b/website/versioned_docs/version-2.0.0-alpha.39/docusaurus.config.js.md @@ -272,7 +272,8 @@ module.exports = { 'https://docusaurus.io/script.js', // Object format. { - src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js', + src: + 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js', async: true, }, ], @@ -294,7 +295,7 @@ module.exports = { // String format. 'https://docusaurus.io/style.css', // Object format. - { + { href: 'http://mydomain.com/style.css', type: 'text/css', }, diff --git a/website/versioned_docs/version-2.0.0-alpha.39/installation.md b/website/versioned_docs/version-2.0.0-alpha.39/installation.md index 4df5cd3378b3..a98051d0c7aa 100644 --- a/website/versioned_docs/version-2.0.0-alpha.39/installation.md +++ b/website/versioned_docs/version-2.0.0-alpha.39/installation.md @@ -24,7 +24,6 @@ Example: npx @docusaurus/init@next init my-website classic ``` - If you do not specify `name` or `template`, it will prompt you for them. We recommend the `classic` template so that you can get started quickly and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus. ## Project structure diff --git a/website/versioned_docs/version-2.0.0-alpha.39/introduction.md b/website/versioned_docs/version-2.0.0-alpha.39/introduction.md index 8ce102d4721c..aea8fab09b8a 100644 --- a/website/versioned_docs/version-2.0.0-alpha.39/introduction.md +++ b/website/versioned_docs/version-2.0.0-alpha.39/introduction.md @@ -59,7 +59,7 @@ Our shared goal β€” to help your users find what they need fast, and understand - Share your code in live editors to get your users love your products on the spot - πŸ” **Search** Your full site is searchable - 🌍 **i18n** (_coming soon_) -- πŸ’Ύ **Document Versioning** Helps you keep documentation in sync with project releases. +- πŸ’Ύ **Document Versioning** Helps you keep documentation in sync with project releases. Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast. diff --git a/website/versioned_docs/version-2.0.0-alpha.39/migrating-from-v1-to-v2.md b/website/versioned_docs/version-2.0.0-alpha.39/migrating-from-v1-to-v2.md index ad8ce4e3609c..6aa4657d8fb3 100644 --- a/website/versioned_docs/version-2.0.0-alpha.39/migrating-from-v1-to-v2.md +++ b/website/versioned_docs/version-2.0.0-alpha.39/migrating-from-v1-to-v2.md @@ -514,17 +514,21 @@ For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord ch > ⚠️ Although we've implemented docs versioning since 2.0.0-alpha.37, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work. ## Changes from v1 + - Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for reasoning on v1's problem ### Migrate your versioned_docs frontmatter + - Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation. -Example, you have a `docs/hello.md`. +Example, you have a `docs/hello.md`. + ```md --- id: hello title: Hello, World ! --- + Hi, Endilie here :) ``` @@ -538,6 +542,7 @@ id: version-1.0.0-hello title: Hello, World ! original_id: hello --- + Hi, Endilie here :) ``` @@ -548,6 +553,7 @@ In comparison, Docusaurus 2 `website/versioned_docs/version-1.0.0/hello.md` look id: hello title: Hello, World ! --- + Hi, Endilie here :) ``` @@ -565,22 +571,23 @@ title: Hello, World ! Hi, Endilie here :) ``` - ### Migrate your versioned_sidebars -- Refer to versioned_docs id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1). +- Refer to versioned_docs id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1). Because in v1 there is a good chance someone created a new file with front matter id `"version-${version}-${id}"` that can conflict with versioned_docs id. Example, Docusaurus 1 can't differentiate `docs/xxx.md` + ```md --- id: version-1.0.0-hello --- + Another content ``` -and `website/versioned_docs/version-1.0.0/hello.md` +and `website/versioned_docs/version-1.0.0/hello.md` ```md --- @@ -588,6 +595,7 @@ id: version-1.0.0-hello title: Hello, World ! original_id: hello --- + Hi, Endilie here :) ``` @@ -596,6 +604,7 @@ Since we don't allow `/` in v1 & v2 for frontmatter, conflicts are less likely t So v1 users need to migrate their versioned_sidebars file Example `versioned_sidebars/version-1.0.0-sidebars.json`: + ```json {2-3,5-6,9-10} { + "version-1.0.0/docs": { @@ -617,12 +626,10 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`: In v2, we use snapshot approach on documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality). For example, if your `versions.json` looks like this in v1 + ```json // versions.json -[ - "1.1.0", - "1.0.0" -] +["1.1.0", "1.0.0"] ``` Docusaurus v1 creates versioned docs **if and only if the doc content is different**. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is `hello.md`. @@ -656,4 +663,4 @@ website β”œβ”€β”€ versioned_sidebars β”‚ β”œβ”€β”€ version-1.1.0-sidebars.json β”‚ └── version-1.0.0-sidebars.json -``` \ No newline at end of file +``` diff --git a/website/versioned_docs/version-2.0.0-alpha.39/sidebar.md b/website/versioned_docs/version-2.0.0-alpha.39/sidebar.md index fb74d725863c..bbc1aadefa5d 100644 --- a/website/versioned_docs/version-2.0.0-alpha.39/sidebar.md +++ b/website/versioned_docs/version-2.0.0-alpha.39/sidebar.md @@ -30,15 +30,16 @@ A sidebar object is defined like this. ```typescript type Sidebar = { - [sidebarId: string]: { - [sidebarCategory: string]: SidebarItem[]; - } | SidebarItem[]; -} + [sidebarId: string]: + | { + [sidebarCategory: string]: SidebarItem[]; + } + | SidebarItem[]; +}; ``` Below is an example of a sidebar object. The key `docs` is the id of the sidebar (can be renamed to something else) and `Getting Started` is a category within the sidebar. `greeting` and `doc1` are both [sidebar item](#sidebar-item). - ```js // sidebars.js module.exports = { @@ -121,10 +122,12 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a ### Doc ```typescript -type SidebarItemDoc = string | { - type: 'doc'; - id: string; -}; +type SidebarItemDoc = + | string + | { + type: 'doc'; + id: string; + }; ``` Sidebar item type that links to a doc page. Example: @@ -204,7 +207,7 @@ type SidebarItemCategory = { type: 'category'; label: string; // Sidebar label text. items: SidebarItem[]; // Array of sidebar items. -} +}; ``` As an example, here's how we created the subcategory for "Docs" under "Guides" in this site: diff --git a/website/versioned_docs/version-2.0.0-alpha.39/using-plugins.md b/website/versioned_docs/version-2.0.0-alpha.39/using-plugins.md index db5df7b41a4c..8c132d556195 100644 --- a/website/versioned_docs/version-2.0.0-alpha.39/using-plugins.md +++ b/website/versioned_docs/version-2.0.0-alpha.39/using-plugins.md @@ -193,7 +193,7 @@ module.exports = { ### `@docusaurus/plugin-content-docs` -Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. +Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. **Installation** @@ -407,10 +407,9 @@ import thumbnail from './path/to/img.png'; | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. | -| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up).| +| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). | | `size` | `integer` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) | | `min` | `integer` | | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. | | `max` | `integer` | | See `min` above | | `steps` | `integer` | `4` | Configure the number of images generated between `min` and `max` (inclusive) | | `quality` | `integer` | `85` | JPEG compression quality | -