diff --git a/.eslintignore b/.eslintignore index c56f7af44c..0f08c470b8 100644 --- a/.eslintignore +++ b/.eslintignore @@ -2,6 +2,7 @@ __fixtures__ dist node_modules build +coverage jest.config.js jest.transform.js website-1.x/ diff --git a/.gitignore b/.gitignore index 418b6c11d1..062df8797c 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ node_modules yarn-error.log build +coverage .docusaurus .cache-loader types diff --git a/.prettierignore b/.prettierignore index 4f32c3d676..fd0e7bbf91 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,6 +1,7 @@ dist node_modules build +coverage .docusaurus packages/docusaurus-utils/lib/ packages/docusaurus/lib/ diff --git a/CHANGELOG-2.x.md b/CHANGELOG-2.x.md index 15a5fc5489..831aea8ce5 100644 --- a/CHANGELOG-2.x.md +++ b/CHANGELOG-2.x.md @@ -1,5 +1,67 @@ # Docusaurus 2 Changelog +## 2.0.0-alpha.56 + +#### :boom: Breaking Change + +- `docusaurus-theme-classic` + - [#2818](https://github.com/facebook/docusaurus/pull/2818) feat(v2): automatically add base url to logo link ([@lex111](https://github.com/lex111)) +- `docusaurus-theme-classic`, `docusaurus-theme-search-algolia` + - [#2791](https://github.com/facebook/docusaurus/pull/2791) refactor(v2): show search icon only on mobiles ([@lex111](https://github.com/lex111)) +- `docusaurus` + - [#2780](https://github.com/facebook/docusaurus/pull/2780) feat(v2): open external links in new tab by default ([@jknoxville](https://github.com/jknoxville)) + +#### :rocket: New Feature + +- `docusaurus-types`, `docusaurus` + - [#2770](https://github.com/facebook/docusaurus/pull/2770) feat(v2): allow deploy without building website ([@lex111](https://github.com/lex111)) +- `docusaurus-theme-classic` + - [#2818](https://github.com/facebook/docusaurus/pull/2818) feat(v2): automatically add base url to logo link ([@lex111](https://github.com/lex111)) + +#### :bug: Bug Fix + +- `docusaurus-theme-classic` + - [#2645](https://github.com/facebook/docusaurus/pull/2645) fix(v2): enable scrolling for sidebar menu only ([@lex111](https://github.com/lex111)) + - [#2800](https://github.com/facebook/docusaurus/pull/2800) fix(v2): make proper h1 font size on mobiles ([@lex111](https://github.com/lex111)) +- `docusaurus` + - [#2788](https://github.com/facebook/docusaurus/pull/2788) fix(v2): use `require.resolve` for all webpack presets and plugins ([@SamChou19815](https://github.com/SamChou19815)) +- `docusaurus-plugin-content-docs` + - [#2785](https://github.com/facebook/docusaurus/pull/2785) fix(v2): do not show sidebar on reserved docs home page ([@lex111](https://github.com/lex111)) + - [#2777](https://github.com/facebook/docusaurus/pull/2777) fix(v2): check for docs homepage correctly ([@lex111](https://github.com/lex111)) + +#### :nail_care: Polish + +- `docusaurus-theme-classic` + - [#2820](https://github.com/facebook/docusaurus/pull/2820) chore(v2): upgrade Infima to 0.2.0-alpha.12 ([@lex111](https://github.com/lex111)) +- `docusaurus-theme-search-algolia` + - [#2814](https://github.com/facebook/docusaurus/pull/2814) refactor(v2): align search icon to center on mobiles ([@lex111](https://github.com/lex111)) + - [#2799](https://github.com/facebook/docusaurus/pull/2799) refactor(v2): increase search input on medium screens ([@lex111](https://github.com/lex111)) +- `docusaurus-init` + - [#2802](https://github.com/facebook/docusaurus/pull/2802) misc: minor improvements for init templates ([@lex111](https://github.com/lex111)) +- `docusaurus-theme-classic`, `docusaurus-theme-search-algolia` + - [#2791](https://github.com/facebook/docusaurus/pull/2791) refactor(v2): show search icon only on mobiles ([@lex111](https://github.com/lex111)) +- `docusaurus` + - [#2783](https://github.com/facebook/docusaurus/pull/2783) refactor(v2): make external links more secure ([@lex111](https://github.com/lex111)) + +#### :memo: Documentation + +- [#2809](https://github.com/facebook/docusaurus/pull/2809) docs(v2): add mention on DocSearch when you run the crawler on your own ([@s-pace](https://github.com/s-pace)) + +#### :house: Internal + +- [#2778](https://github.com/facebook/docusaurus/pull/2778) fix(v2): do not highlight root docs path in navbar ([@lex111](https://github.com/lex111)) + +#### Committers: 8 + +- Alexey Pyltsyn ([@lex111](https://github.com/lex111)) +- James McShane ([@jmcshane](https://github.com/jmcshane)) +- John Knox ([@jknoxville](https://github.com/jknoxville)) +- Kasper Bøgebjerg Pedersen ([@kasperp](https://github.com/kasperp)) +- Muhammad Ali ([@mrmuhammadali](https://github.com/mrmuhammadali)) +- Piotr Baran ([@piotros](https://github.com/piotros)) +- Sam Zhou ([@SamChou19815](https://github.com/SamChou19815)) +- Sylvain Pace ([@s-pace](https://github.com/s-pace)) + ## 2.0.0-alpha.55 #### :boom: Breaking Change diff --git a/lerna.json b/lerna.json index 6d94b279fa..3c7729095f 100644 --- a/lerna.json +++ b/lerna.json @@ -1,5 +1,5 @@ { - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "npmClient": "yarn", "useWorkspaces": true, "changelog": { diff --git a/package.json b/package.json index 82d4dc77ce..78b7c51c9c 100644 --- a/package.json +++ b/package.json @@ -94,6 +94,6 @@ } }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-1.x/package.json b/packages/docusaurus-1.x/package.json index f96c5b7180..d5cd35d205 100644 --- a/packages/docusaurus-1.x/package.json +++ b/packages/docusaurus-1.x/package.json @@ -1,7 +1,7 @@ { "name": "docusaurus", "description": "Easy to Maintain Open Source Documentation Websites", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "license": "MIT", "keywords": [ "documentation", diff --git a/packages/docusaurus-init-1.x/package.json b/packages/docusaurus-init-1.x/package.json index e16e4ea90a..b9e0741b23 100644 --- a/packages/docusaurus-init-1.x/package.json +++ b/packages/docusaurus-init-1.x/package.json @@ -1,7 +1,7 @@ { "name": "docusaurus-init", "description": "Initialization script for Docusaurus", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "license": "MIT", "preferGlobal": true, "keywords": [ diff --git a/packages/docusaurus-init/package.json b/packages/docusaurus-init/package.json index 798c34a039..7c1fbbc388 100644 --- a/packages/docusaurus-init/package.json +++ b/packages/docusaurus-init/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/init", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Create Docusaurus app easily", "repository": { "type": "git", @@ -29,6 +29,6 @@ "shelljs": "^0.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-init/templates/bootstrap/package.json b/packages/docusaurus-init/templates/bootstrap/package.json index 6eb40962ca..dbc57d0a5c 100644 --- a/packages/docusaurus-init/templates/bootstrap/package.json +++ b/packages/docusaurus-init/templates/bootstrap/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-bootstrap-template", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "private": true, "scripts": { "start": "docusaurus start", @@ -9,8 +9,8 @@ "deploy": "docusaurus deploy" }, "dependencies": { - "@docusaurus/core": "^2.0.0-alpha.55", - "@docusaurus/preset-bootstrap": "^2.0.0-alpha.55", + "@docusaurus/core": "^2.0.0-alpha.56", + "@docusaurus/preset-bootstrap": "^2.0.0-alpha.56", "classnames": "^2.2.6", "react": "^16.8.4", "react-dom": "^16.8.4" diff --git a/packages/docusaurus-init/templates/classic/package.json b/packages/docusaurus-init/templates/classic/package.json index 934e521408..6420af2cbb 100644 --- a/packages/docusaurus-init/templates/classic/package.json +++ b/packages/docusaurus-init/templates/classic/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-classic-template", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "private": true, "scripts": { "start": "docusaurus start", @@ -9,8 +9,8 @@ "deploy": "docusaurus deploy" }, "dependencies": { - "@docusaurus/core": "^2.0.0-alpha.55", - "@docusaurus/preset-classic": "^2.0.0-alpha.55", + "@docusaurus/core": "^2.0.0-alpha.56", + "@docusaurus/preset-classic": "^2.0.0-alpha.56", "classnames": "^2.2.6", "react": "^16.8.4", "react-dom": "^16.8.4" diff --git a/packages/docusaurus-init/templates/facebook/package.json b/packages/docusaurus-init/templates/facebook/package.json index cde15372f3..a38fb5adf3 100644 --- a/packages/docusaurus-init/templates/facebook/package.json +++ b/packages/docusaurus-init/templates/facebook/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-facebook-template", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "private": true, "scripts": { "start": "docusaurus start", @@ -13,8 +13,8 @@ "prettier:diff": "prettier --config .prettierrc --list-different \"**/*.{js,md}\"" }, "dependencies": { - "@docusaurus/core": "^2.0.0-alpha.55", - "@docusaurus/preset-classic": "^2.0.0-alpha.55", + "@docusaurus/core": "^2.0.0-alpha.56", + "@docusaurus/preset-classic": "^2.0.0-alpha.56", "classnames": "^2.2.6", "react": "^16.8.4", "react-dom": "^16.8.4" diff --git a/packages/docusaurus-mdx-loader/package.json b/packages/docusaurus-mdx-loader/package.json index d58c32affc..a991566c39 100644 --- a/packages/docusaurus-mdx-loader/package.json +++ b/packages/docusaurus-mdx-loader/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/mdx-loader", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Docusaurus Loader for MDX", "main": "src/index.js", "publishConfig": { @@ -30,6 +30,6 @@ "unist-util-remove-position": "^2.0.1" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-module-type-aliases/package.json b/packages/docusaurus-module-type-aliases/package.json index 9b088d3556..3524b47a7d 100644 --- a/packages/docusaurus-module-type-aliases/package.json +++ b/packages/docusaurus-module-type-aliases/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/module-type-aliases", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Docusaurus module type aliases", "types": "./src/index.d.ts", "publishConfig": { diff --git a/packages/docusaurus-plugin-content-blog/package.json b/packages/docusaurus-plugin-content-blog/package.json index 2f710a3290..5d52f67a5c 100644 --- a/packages/docusaurus-plugin-content-blog/package.json +++ b/packages/docusaurus-plugin-content-blog/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-content-blog", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Blog plugin for Docusaurus", "main": "lib/index.js", "scripts": { @@ -11,11 +11,11 @@ }, "license": "MIT", "devDependencies": { - "@docusaurus/types": "^2.0.0-alpha.55" + "@docusaurus/types": "^2.0.0-alpha.56" }, "dependencies": { - "@docusaurus/mdx-loader": "^2.0.0-alpha.55", - "@docusaurus/utils": "^2.0.0-alpha.55", + "@docusaurus/mdx-loader": "^2.0.0-alpha.56", + "@docusaurus/utils": "^2.0.0-alpha.56", "feed": "^4.1.0", "fs-extra": "^8.1.0", "globby": "^10.0.1", @@ -30,6 +30,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-plugin-content-docs/package.json b/packages/docusaurus-plugin-content-docs/package.json index 6a30b2c45f..b90371009b 100644 --- a/packages/docusaurus-plugin-content-docs/package.json +++ b/packages/docusaurus-plugin-content-docs/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-content-docs", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Docs content plugin for Docusaurus", "main": "lib/index.js", "scripts": { @@ -11,13 +11,13 @@ }, "license": "MIT", "devDependencies": { - "@docusaurus/types": "^2.0.0-alpha.55", + "@docusaurus/types": "^2.0.0-alpha.56", "commander": "^5.0.0", "picomatch": "^2.1.1" }, "dependencies": { - "@docusaurus/mdx-loader": "^2.0.0-alpha.55", - "@docusaurus/utils": "^2.0.0-alpha.55", + "@docusaurus/mdx-loader": "^2.0.0-alpha.56", + "@docusaurus/utils": "^2.0.0-alpha.56", "execa": "^3.4.0", "fs-extra": "^8.1.0", "globby": "^10.0.1", @@ -36,6 +36,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js index 402803c0c4..975f1203fe 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js @@ -9,25 +9,30 @@ module.exports = { docs: [ { type: 'category', + collapsed: true, label: 'level 1', items: [ 'a', { type: 'category', + collapsed: true, label: 'level 2', items: [ { type: 'category', + collapsed: true, label: 'level 3', items: [ 'c', { type: 'category', + collapsed: true, label: 'level 4', items: [ 'd', { type: 'category', + collapsed: true, label: 'deeper more more', items: ['e'], }, diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed-first-level.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed-first-level.json new file mode 100644 index 0000000000..1251a7d454 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed-first-level.json @@ -0,0 +1,20 @@ +{ + "docs": [ + { + "type": "category", + "label": "Introduction", + "items": [ + "doc1" + ], + "collapsed": false + }, + { + "type": "category", + "label": "Powering MDX", + "items": [ + "doc2" + ], + "collapsed": false + } + ] +} \ No newline at end of file diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed.json new file mode 100644 index 0000000000..2199c5f557 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed.json @@ -0,0 +1,21 @@ +{ + "docs": { + "Test": [ + { + "type": "category", + "label": "Introduction", + "items": ["doc1"], + "collapsed": false + } + ], + "Reference": [ + { + "type": "category", + "label": "Powering MDX", + "items": ["doc2"], + "collapsed": false + } + ] + } + } + \ No newline at end of file diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap index 321cb87ce3..9c2e00cd32 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap @@ -4,6 +4,7 @@ exports[`simple website content 1`] = ` Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "items": Array [ @@ -36,6 +37,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/hello", @@ -236,6 +238,7 @@ exports[`versioned website content: all sidebars 1`] = ` Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/next/foo/bar", @@ -247,6 +250,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/next/hello", @@ -260,6 +264,7 @@ Object { ], "version-1.0.0/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/1.0.0/foo/bar", @@ -276,6 +281,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/1.0.0/hello", @@ -289,6 +295,7 @@ Object { ], "version-1.0.1/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/foo/bar", @@ -300,6 +307,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/hello", @@ -319,6 +327,7 @@ Object { "docsSidebars": Object { "version-1.0.0/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/1.0.0/foo/bar", @@ -335,6 +344,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/1.0.0/hello", @@ -361,6 +371,7 @@ Object { "docsSidebars": Object { "version-1.0.1/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/foo/bar", @@ -372,6 +383,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/hello", @@ -397,6 +409,7 @@ Object { "docsSidebars": Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/next/foo/bar", @@ -408,6 +421,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/next/hello", diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/sidebars.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/sidebars.test.ts.snap index e0bc01bdc9..0aa670c44b 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/sidebars.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/sidebars.test.ts.snap @@ -4,6 +4,7 @@ exports[`loadSidebars sidebars link 1`] = ` Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "https://github.com", @@ -18,30 +19,107 @@ Object { } `; +exports[`loadSidebars sidebars with category.collapsed property 1`] = ` +Object { + "docs": Array [ + Object { + "collapsed": true, + "items": Array [ + Object { + "collapsed": false, + "items": Array [ + Object { + "id": "doc1", + "type": "doc", + }, + ], + "label": "Introduction", + "type": "category", + }, + ], + "label": "Test", + "type": "category", + }, + Object { + "collapsed": true, + "items": Array [ + Object { + "collapsed": false, + "items": Array [ + Object { + "id": "doc2", + "type": "doc", + }, + ], + "label": "Powering MDX", + "type": "category", + }, + ], + "label": "Reference", + "type": "category", + }, + ], +} +`; + +exports[`loadSidebars sidebars with category.collapsed property at first level 1`] = ` +Object { + "docs": Array [ + Object { + "collapsed": false, + "items": Array [ + Object { + "id": "doc1", + "type": "doc", + }, + ], + "label": "Introduction", + "type": "category", + }, + Object { + "collapsed": false, + "items": Array [ + Object { + "id": "doc2", + "type": "doc", + }, + ], + "label": "Powering MDX", + "type": "category", + }, + ], +} +`; + exports[`loadSidebars sidebars with deep level of category 1`] = ` Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "id": "a", "type": "doc", }, Object { + "collapsed": true, "items": Array [ Object { + "collapsed": true, "items": Array [ Object { "id": "c", "type": "doc", }, Object { + "collapsed": true, "items": Array [ Object { "id": "d", "type": "doc", }, Object { + "collapsed": true, "items": Array [ Object { "id": "e", @@ -100,6 +178,7 @@ exports[`loadSidebars sidebars with known sidebar item type 1`] = ` Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "id": "foo/bar", @@ -123,6 +202,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "id": "hello", diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/version.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/version.test.ts.snap index 47ffaef77f..26c10f3c0a 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/version.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/version.test.ts.snap @@ -4,6 +4,7 @@ exports[`docsVersion first time versioning 1`] = ` Object { "version-1.0.0/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "items": Array [ @@ -33,6 +34,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "id": "version-1.0.0/hello", @@ -50,6 +52,7 @@ exports[`docsVersion not the first time versioning 1`] = ` Object { "version-2.0.0/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "id": "version-2.0.0/foo/bar", @@ -60,6 +63,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "id": "version-2.0.0/hello", diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts index 49a788dfd9..11d882b22a 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts @@ -126,4 +126,19 @@ describe('loadSidebars', () => { const result = loadSidebars(null); expect(result).toEqual({}); }); + + test('sidebars with category.collapsed property', async () => { + const sidebarPath = path.join(fixtureDir, 'sidebars-collapsed.json'); + const result = loadSidebars([sidebarPath]); + expect(result).toMatchSnapshot(); + }); + + test('sidebars with category.collapsed property at first level', async () => { + const sidebarPath = path.join( + fixtureDir, + 'sidebars-collapsed-first-level.json', + ); + const result = loadSidebars([sidebarPath]); + expect(result).toMatchSnapshot(); + }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars.ts b/packages/docusaurus-plugin-content-docs/src/sidebars.ts index cfe1b36254..abe988984b 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars.ts @@ -33,6 +33,7 @@ function normalizeCategoryShorthand( ): SidebarItemCategoryRaw[] { return Object.entries(sidebar).map(([label, items]) => ({ type: 'category', + collapsed: true, label, items, })); @@ -56,7 +57,7 @@ function assertItem(item: Object, keys: string[]): void { } function assertIsCategory(item: any): asserts item is SidebarItemCategoryRaw { - assertItem(item, ['items', 'label']); + assertItem(item, ['items', 'label', 'collapsed']); if (typeof item.label !== 'string') { throw new Error( `Error loading ${JSON.stringify(item)}. "label" must be a string.`, @@ -67,6 +68,12 @@ function assertIsCategory(item: any): asserts item is SidebarItemCategoryRaw { `Error loading ${JSON.stringify(item)}. "items" must be an array.`, ); } + // "collapsed" is an optional property + if (item.hasOwnProperty('collapsed') && typeof item.collapsed !== 'boolean') { + throw new Error( + `Error loading ${JSON.stringify(item)}. "collapsed" must be a boolean.`, + ); + } } function assertIsDoc(item: any): asserts item is SidebarItemDoc { diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index 16c3a034ad..642d9703ab 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/types.ts @@ -42,12 +42,14 @@ export interface SidebarItemCategory { type: 'category'; label: string; items: SidebarItem[]; + collapsed?: boolean; } export interface SidebarItemCategoryRaw { type: 'category'; label: string; items: SidebarItemRaw[]; + collapsed?: boolean; } export type SidebarItem = @@ -83,6 +85,7 @@ export interface DocsSidebarItemCategory { type: 'category'; label: string; items: DocsSidebarItem[]; + collapsed?: boolean; } export type DocsSidebarItem = SidebarItemLink | DocsSidebarItemCategory; diff --git a/packages/docusaurus-plugin-content-pages/package.json b/packages/docusaurus-plugin-content-pages/package.json index 1b6651ebe0..36c2c8d789 100644 --- a/packages/docusaurus-plugin-content-pages/package.json +++ b/packages/docusaurus-plugin-content-pages/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-content-pages", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Pages content plugin for Docusaurus", "main": "lib/index.js", "scripts": { @@ -11,8 +11,8 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/types": "^2.0.0-alpha.55", - "@docusaurus/utils": "^2.0.0-alpha.55", + "@docusaurus/types": "^2.0.0-alpha.56", + "@docusaurus/utils": "^2.0.0-alpha.56", "globby": "^10.0.1" }, "peerDependencies": { @@ -21,6 +21,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-plugin-google-analytics/package.json b/packages/docusaurus-plugin-google-analytics/package.json index 7a036bb34d..03be915f29 100644 --- a/packages/docusaurus-plugin-google-analytics/package.json +++ b/packages/docusaurus-plugin-google-analytics/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-google-analytics", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Global analytics (analytics.js) plugin for Docusaurus", "main": "src/index.js", "publishConfig": { @@ -11,6 +11,6 @@ "@docusaurus/core": "^2.0.0" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-plugin-google-gtag/package.json b/packages/docusaurus-plugin-google-gtag/package.json index 925fce153f..ddf3886244 100644 --- a/packages/docusaurus-plugin-google-gtag/package.json +++ b/packages/docusaurus-plugin-google-gtag/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-google-gtag", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Global Site Tag (gtag.js) plugin for Docusaurus", "main": "src/index.js", "publishConfig": { @@ -11,6 +11,6 @@ "@docusaurus/core": "^2.0.0" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-plugin-ideal-image/package.json b/packages/docusaurus-plugin-ideal-image/package.json index a25fc0fa2d..cd31dac95e 100644 --- a/packages/docusaurus-plugin-ideal-image/package.json +++ b/packages/docusaurus-plugin-ideal-image/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-ideal-image", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder)", "main": "lib/index.js", "scripts": { @@ -11,11 +11,11 @@ }, "license": "MIT", "devDependencies": { - "@docusaurus/types": "^2.0.0-alpha.55", + "@docusaurus/types": "^2.0.0-alpha.56", "fs-extra": "^9.0.0" }, "dependencies": { - "@docusaurus/lqip-loader": "^2.0.0-alpha.55", + "@docusaurus/lqip-loader": "^2.0.0-alpha.56", "@endiliey/react-ideal-image": "^0.0.11", "@endiliey/responsive-loader": "^1.3.2", "react-waypoint": "^9.0.2", @@ -27,6 +27,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-plugin-sitemap/package.json b/packages/docusaurus-plugin-sitemap/package.json index ff11c38204..4d74bcf80d 100644 --- a/packages/docusaurus-plugin-sitemap/package.json +++ b/packages/docusaurus-plugin-sitemap/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-sitemap", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Simple sitemap generation plugin for Docusaurus", "main": "lib/index.js", "scripts": { @@ -11,13 +11,13 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/types": "^2.0.0-alpha.55", + "@docusaurus/types": "^2.0.0-alpha.56", "sitemap": "^3.2.2" }, "peerDependencies": { "@docusaurus/core": "^2.0.0" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-preset-bootstrap/package.json b/packages/docusaurus-preset-bootstrap/package.json index 69d6d74699..1b20e24efb 100644 --- a/packages/docusaurus-preset-bootstrap/package.json +++ b/packages/docusaurus-preset-bootstrap/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/preset-bootstrap", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Preset for bootstrap Docusaurus", "main": "src/index.js", "license": "MIT", @@ -8,10 +8,10 @@ "access": "public" }, "dependencies": { - "@docusaurus/plugin-content-blog": "^2.0.0-alpha.55", - "@docusaurus/plugin-content-docs": "^2.0.0-alpha.55", - "@docusaurus/plugin-content-pages": "^2.0.0-alpha.55", - "@docusaurus/theme-bootstrap": "^2.0.0-alpha.55" + "@docusaurus/plugin-content-blog": "^2.0.0-alpha.56", + "@docusaurus/plugin-content-docs": "^2.0.0-alpha.56", + "@docusaurus/plugin-content-pages": "^2.0.0-alpha.56", + "@docusaurus/theme-bootstrap": "^2.0.0-alpha.56" }, "peerDependencies": { "@docusaurus/core": "^2.0.0", @@ -19,6 +19,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-preset-classic/package.json b/packages/docusaurus-preset-classic/package.json index 6245056ec4..eb6172ff3c 100644 --- a/packages/docusaurus-preset-classic/package.json +++ b/packages/docusaurus-preset-classic/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/preset-classic", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Preset for classic Docusaurus", "main": "src/index.js", "publishConfig": { @@ -8,14 +8,14 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/plugin-content-blog": "^2.0.0-alpha.55", - "@docusaurus/plugin-content-docs": "^2.0.0-alpha.55", - "@docusaurus/plugin-content-pages": "^2.0.0-alpha.55", - "@docusaurus/plugin-google-analytics": "^2.0.0-alpha.55", - "@docusaurus/plugin-google-gtag": "^2.0.0-alpha.55", - "@docusaurus/plugin-sitemap": "^2.0.0-alpha.55", - "@docusaurus/theme-classic": "^2.0.0-alpha.55", - "@docusaurus/theme-search-algolia": "^2.0.0-alpha.55" + "@docusaurus/plugin-content-blog": "^2.0.0-alpha.56", + "@docusaurus/plugin-content-docs": "^2.0.0-alpha.56", + "@docusaurus/plugin-content-pages": "^2.0.0-alpha.56", + "@docusaurus/plugin-google-analytics": "^2.0.0-alpha.56", + "@docusaurus/plugin-google-gtag": "^2.0.0-alpha.56", + "@docusaurus/plugin-sitemap": "^2.0.0-alpha.56", + "@docusaurus/theme-classic": "^2.0.0-alpha.56", + "@docusaurus/theme-search-algolia": "^2.0.0-alpha.56" }, "peerDependencies": { "@docusaurus/core": "^2.0.0", @@ -23,6 +23,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-theme-bootstrap/package.json b/packages/docusaurus-theme-bootstrap/package.json index 9d0e3ef1d2..52e1122820 100644 --- a/packages/docusaurus-theme-bootstrap/package.json +++ b/packages/docusaurus-theme-bootstrap/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-bootstrap", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Bootstrap theme for docusaurus", "main": "src/index.js", "license": "MIT", @@ -20,6 +20,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-theme-classic/package-lock.json b/packages/docusaurus-theme-classic/package-lock.json index d550616d8a..f8e090c635 100644 --- a/packages/docusaurus-theme-classic/package-lock.json +++ b/packages/docusaurus-theme-classic/package-lock.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-classic", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/docusaurus-theme-classic/package.json b/packages/docusaurus-theme-classic/package.json index 82fa70ab02..d3d00bc756 100644 --- a/packages/docusaurus-theme-classic/package.json +++ b/packages/docusaurus-theme-classic/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-classic", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Classic theme for Docusaurus", "main": "src/index.js", "publishConfig": { @@ -12,7 +12,7 @@ "@mdx-js/react": "^1.5.8", "classnames": "^2.2.6", "clipboard": "^2.0.6", - "infima": "0.2.0-alpha.11", + "infima": "0.2.0-alpha.12", "parse-numeric-range": "^0.0.2", "prism-react-renderer": "^1.1.0", "prismjs": "^1.20.0", @@ -26,6 +26,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js b/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js index cad9db38d5..b8c8cff518 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js +++ b/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js @@ -6,6 +6,7 @@ */ import React, {useState, useCallback} from 'react'; +import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; import classnames from 'classnames'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; import useAnnouncementBarContext from '@theme/hooks/useAnnouncementBarContext'; @@ -44,6 +45,28 @@ function DocSidebarItem({ setCollapsed((state) => !state); }); + // Make sure we have access to the window + const activePageRelativeUrl = ExecutionEnvironment.canUseDOM + ? window.location.pathname + window.location.search + : null; + + // We need to know if the category item + // is the parent of the active page + // If it is, this returns true and make sure to highlight this category + const isCategoryOfActivePage = (_items, _activePageRelativeUrl) => { + // Make sure we have items + if (typeof _items !== 'undefined') { + return _items.some((categoryItem) => { + // Grab the category item's href + const childHref = categoryItem.href; + // Compare it to the current active page + return _activePageRelativeUrl === childHref; + }); + } + + return false; + }; + switch (type) { case 'category': return ( @@ -56,7 +79,10 @@ function DocSidebarItem({ mutateSidebarCollapsingState(childItem, path)) .filter((val) => val).length > 0; + + // Check if the user wants the category to be expanded by default + const shouldExpand = item.collapsed === false; + // eslint-disable-next-line no-param-reassign item.collapsed = !anyChildItemsActive; + + if (shouldExpand) { + // eslint-disable-next-line no-param-reassign + item.collapsed = false; + } + return anyChildItemsActive; } diff --git a/packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.js b/packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.js index 812b5213a5..3087eb34c2 100644 --- a/packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.js +++ b/packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.js @@ -13,11 +13,7 @@ const STORAGE_ID_KEY = 'docusaurus.announcement.id'; const useAnnouncementBar = () => { const { - siteConfig: { - themeConfig: { - announcementBar: {id}, - }, - } = {}, + siteConfig: {themeConfig: {announcementBar: {id} = {}}} = {}, } = useDocusaurusContext(); const [isClosed, setClosed] = useState(true); const handleClose = () => { @@ -26,6 +22,10 @@ const useAnnouncementBar = () => { }; useEffect(() => { + if (!id) { + return; + } + const viewedId = localStorage.getItem(STORAGE_ID_KEY); const isNewAnnouncement = id !== viewedId; diff --git a/packages/docusaurus-theme-classic/src/theme/hooks/useLogo.js b/packages/docusaurus-theme-classic/src/theme/hooks/useLogo.js index ddb15ad1a8..2cbb6fad16 100644 --- a/packages/docusaurus-theme-classic/src/theme/hooks/useLogo.js +++ b/packages/docusaurus-theme-classic/src/theme/hooks/useLogo.js @@ -12,10 +12,10 @@ import isInternalUrl from '@docusaurus/isInternalUrl'; const useLogo = () => { const { - siteConfig: {baseUrl, themeConfig: {navbar: {logo = {}} = {}}} = {}, + siteConfig: {themeConfig: {navbar: {logo = {}} = {}}} = {}, } = useDocusaurusContext(); const {isDarkTheme} = useThemeContext(); - const logoLink = logo.href || baseUrl; + const logoLink = useBaseUrl(logo.href || '/'); let logoLinkProps = {}; if (logo.target) { diff --git a/packages/docusaurus-theme-live-codeblock/package.json b/packages/docusaurus-theme-live-codeblock/package.json index 9325bbf7f1..6b27eee1a1 100644 --- a/packages/docusaurus-theme-live-codeblock/package.json +++ b/packages/docusaurus-theme-live-codeblock/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-live-codeblock", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Docusaurus Live CodeBlock", "main": "src/index.js", "publishConfig": { @@ -21,6 +21,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-theme-search-algolia/package.json b/packages/docusaurus-theme-search-algolia/package.json index d7af43802a..dcb7cbdf7d 100644 --- a/packages/docusaurus-theme-search-algolia/package.json +++ b/packages/docusaurus-theme-search-algolia/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-search-algolia", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Algolia search component for Docusaurus", "main": "src/index.js", "publishConfig": { @@ -21,6 +21,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus-types/package.json b/packages/docusaurus-types/package.json index fd955a59b0..b5f10aefa0 100644 --- a/packages/docusaurus-types/package.json +++ b/packages/docusaurus-types/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/types", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Common used typings for Docusaurus packages", "main": "./src/index.js", "types": "./src/index.d.ts", diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts index 61b34feef3..a8fffdc4f8 100644 --- a/packages/docusaurus-types/src/index.d.ts +++ b/packages/docusaurus-types/src/index.d.ts @@ -67,6 +67,7 @@ export interface BuildCLIOptions { bundleAnalyzer: boolean; outDir: string; minify: boolean; + skipBuild: boolean; } export interface LoadContext { diff --git a/packages/docusaurus-utils/package.json b/packages/docusaurus-utils/package.json index 4707fadbb7..88401575b3 100644 --- a/packages/docusaurus-utils/package.json +++ b/packages/docusaurus-utils/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/utils", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Node utility functions for Docusaurus packages", "main": "./lib/index.js", "types": "./lib/index.d.ts", @@ -19,6 +19,6 @@ "lodash.kebabcase": "^4.1.1" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus/bin/docusaurus.js b/packages/docusaurus/bin/docusaurus.js index 22bac22067..97068cfd00 100755 --- a/packages/docusaurus/bin/docusaurus.js +++ b/packages/docusaurus/bin/docusaurus.js @@ -71,8 +71,12 @@ cli '--out-dir ', 'The full path for the new output directory, relative to the current workspace (default: build).', ) - .action((siteDir = '.', {outDir}) => { - wrapCommand(deploy)(path.resolve(siteDir), {outDir}); + .option( + '--skip-build', + 'Skip building website before deploy it (default: false)', + ) + .action((siteDir = '.', {outDir, skipBuild}) => { + wrapCommand(deploy)(path.resolve(siteDir), {outDir, skipBuild}); }); cli diff --git a/packages/docusaurus/package.json b/packages/docusaurus/package.json index 1744bb0c13..9be6b71459 100644 --- a/packages/docusaurus/package.json +++ b/packages/docusaurus/package.json @@ -1,7 +1,7 @@ { "name": "@docusaurus/core", "description": "Easy to Maintain Open Source Documentation Websites", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "license": "MIT", "publishConfig": { "access": "public" @@ -29,8 +29,8 @@ "url": "https://github.com/facebook/docusaurus/issues" }, "devDependencies": { - "@docusaurus/module-type-aliases": "^2.0.0-alpha.55", - "@docusaurus/types": "^2.0.0-alpha.55" + "@docusaurus/module-type-aliases": "^2.0.0-alpha.56", + "@docusaurus/types": "^2.0.0-alpha.56" }, "dependencies": { "@babel/core": "^7.9.0", @@ -40,7 +40,7 @@ "@babel/preset-react": "^7.9.4", "@babel/preset-typescript": "^7.9.0", "@babel/runtime": "^7.9.2", - "@docusaurus/utils": "^2.0.0-alpha.55", + "@docusaurus/utils": "^2.0.0-alpha.56", "@endiliey/static-site-generator-webpack-plugin": "^4.0.0", "@svgr/webpack": "^5.4.0", "babel-loader": "^8.1.0", @@ -96,6 +96,6 @@ "react-dom": "^16.8.4" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/docusaurus/src/commands/deploy.ts b/packages/docusaurus/src/commands/deploy.ts index 87db8f33ac..4d0c8af01e 100644 --- a/packages/docusaurus/src/commands/deploy.ts +++ b/packages/docusaurus/src/commands/deploy.ts @@ -9,6 +9,7 @@ import fs from 'fs-extra'; import path from 'path'; import shell from 'shelljs'; import {CONFIG_FILE_NAME, GENERATED_FILES_DIR_NAME} from '../constants'; +import {loadContext} from '../server'; import {loadConfig} from '../server/config'; import {build} from './build'; import {BuildCLIOptions} from '@docusaurus/types'; @@ -17,6 +18,9 @@ export async function deploy( siteDir: string, cliOptions: Partial = {}, ): Promise { + const {outDir} = loadContext(siteDir, cliOptions.outDir); + const tempDir = path.join(siteDir, GENERATED_FILES_DIR_NAME); + console.log('Deploy command invoked ...'); if (!shell.which('git')) { throw new Error('Git not installed or on the PATH!'); @@ -94,95 +98,103 @@ export async function deploy( // out to deployment branch. const currentCommit = shell.exec('git rev-parse HEAD').stdout.trim(); - // Clear Docusaurus 2 cache dir for deploy consistency. - const tempDir = path.join(siteDir, '.docusaurus'); - fs.removeSync(tempDir); + const runDeploy = (outDir) => { + if (shell.cd(tempDir).code !== 0) { + throw new Error( + `Temp dir ${GENERATED_FILES_DIR_NAME} does not exists. Run build website first.`, + ); + } - // Build static html files, then push to deploymentBranch branch of specified repo. - build(siteDir, cliOptions, false) - .then((outDir) => { - shell.cd(tempDir); + if ( + shell.exec(`git clone ${remoteBranch} ${projectName}-${deploymentBranch}`) + .code !== 0 + ) { + throw new Error('Error: git clone failed'); + } - if ( - shell.exec( - `git clone ${remoteBranch} ${projectName}-${deploymentBranch}`, - ).code !== 0 - ) { - throw new Error('Error: git clone failed'); - } + shell.cd(`${projectName}-${deploymentBranch}`); - shell.cd(`${projectName}-${deploymentBranch}`); - - // If the default branch is the one we're deploying to, then we'll fail - // to create it. This is the case of a cross-repo publish, where we clone - // a github.io repo with a default master branch. - const defaultBranch = shell - .exec('git rev-parse --abbrev-ref HEAD') - .stdout.trim(); - if (defaultBranch !== deploymentBranch) { - if (shell.exec(`git checkout origin/${deploymentBranch}`).code !== 0) { - if ( - shell.exec(`git checkout --orphan ${deploymentBranch}`).code !== 0 - ) { - throw new Error(`Error: Git checkout ${deploymentBranch} failed`); - } - } else if ( - shell.exec(`git checkout -b ${deploymentBranch}`).code + - shell.exec( - `git branch --set-upstream-to=origin/${deploymentBranch}`, - ).code !== - 0 + // If the default branch is the one we're deploying to, then we'll fail + // to create it. This is the case of a cross-repo publish, where we clone + // a github.io repo with a default master branch. + const defaultBranch = shell + .exec('git rev-parse --abbrev-ref HEAD') + .stdout.trim(); + if (defaultBranch !== deploymentBranch) { + if (shell.exec(`git checkout origin/${deploymentBranch}`).code !== 0) { + if ( + shell.exec(`git checkout --orphan ${deploymentBranch}`).code !== 0 ) { throw new Error(`Error: Git checkout ${deploymentBranch} failed`); } + } else if ( + shell.exec(`git checkout -b ${deploymentBranch}`).code + + shell.exec(`git branch --set-upstream-to=origin/${deploymentBranch}`) + .code !== + 0 + ) { + throw new Error(`Error: Git checkout ${deploymentBranch} failed`); + } + } + + shell.exec('git rm -rf .'); + + shell.cd('../..'); + + const fromPath = outDir; + const toPath = path.join( + GENERATED_FILES_DIR_NAME, + `${projectName}-${deploymentBranch}`, + ); + + fs.copy(fromPath, toPath, (error) => { + if (error) { + throw new Error( + `Error: Copying build assets failed with error '${error}'`, + ); } - shell.exec('git rm -rf .'); + shell.cd(toPath); + shell.exec('git add --all'); - shell.cd('../..'); - - const fromPath = outDir; - const toPath = path.join( - GENERATED_FILES_DIR_NAME, - `${projectName}-${deploymentBranch}`, - ); - - fs.copy(fromPath, toPath, (error) => { - if (error) { - throw new Error( - `Error: Copying build assets failed with error '${error}'`, - ); + const commitMessage = + process.env.CUSTOM_COMMIT_MESSAGE || + `Deploy website - based on ${currentCommit}`; + const commitResults = shell.exec(`git commit -m "${commitMessage}"`); + if ( + shell.exec(`git push --force origin ${deploymentBranch}`).code !== 0 + ) { + throw new Error('Error: Git push failed'); + } else if (commitResults.code === 0) { + // The commit might return a non-zero value when site is up to date. + let websiteURL = ''; + if (githubHost === 'github.com') { + websiteURL = projectName.includes('.github.io') + ? `https://${organizationName}.github.io/` + : `https://${organizationName}.github.io/${projectName}/`; + } else { + // GitHub enterprise hosting. + websiteURL = `https://${githubHost}/pages/${organizationName}/${projectName}/`; } - - shell.cd(toPath); - shell.exec('git add --all'); - - const commitMessage = - process.env.CUSTOM_COMMIT_MESSAGE || - `Deploy website - based on ${currentCommit}`; - const commitResults = shell.exec(`git commit -m "${commitMessage}"`); - if ( - shell.exec(`git push --force origin ${deploymentBranch}`).code !== 0 - ) { - throw new Error('Error: Git push failed'); - } else if (commitResults.code === 0) { - // The commit might return a non-zero value when site is up to date. - let websiteURL = ''; - if (githubHost === 'github.com') { - websiteURL = projectName.includes('.github.io') - ? `https://${organizationName}.github.io/` - : `https://${organizationName}.github.io/${projectName}/`; - } else { - // GitHub enterprise hosting. - websiteURL = `https://${githubHost}/pages/${organizationName}/${projectName}/`; - } - shell.echo(`Website is live at ${websiteURL}`); - shell.exit(0); - } - }); - }) - .catch((buildError) => { - console.error(buildError); - process.exit(1); + shell.echo(`Website is live at ${websiteURL}`); + shell.exit(0); + } }); + }; + + if (!cliOptions.skipBuild) { + // Clear Docusaurus 2 cache dir for deploy consistency. + fs.removeSync(tempDir); + + // Build static html files, then push to deploymentBranch branch of specified repo. + build(siteDir, cliOptions, false) + .then(runDeploy) + .catch((buildError) => { + console.error(buildError); + process.exit(1); + }); + } else { + // Push current build to deploymentBranch branch of specified repo. + runDeploy(outDir); + } } diff --git a/packages/lqip-loader/package.json b/packages/lqip-loader/package.json index 3e7b27ddf9..1cd6450977 100644 --- a/packages/lqip-loader/package.json +++ b/packages/lqip-loader/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/lqip-loader", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "Low Quality Image Placeholders (LQIP) loader for webpack", "main": "src/index.js", "publishConfig": { @@ -17,6 +17,6 @@ "sharp": "*" }, "engines": { - "node": ">=10.9.0" + "node": ">=10.15.1" } } diff --git a/packages/stylelint-copyright/package.json b/packages/stylelint-copyright/package.json index 345f1a6070..7c9d8dcd78 100644 --- a/packages/stylelint-copyright/package.json +++ b/packages/stylelint-copyright/package.json @@ -1,6 +1,6 @@ { "name": "stylelint-copyright", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "description": "stylelint plugin to check css files for a copyright header", "main": "index.js", "license": "MIT", diff --git a/website-1.x/package.json b/website-1.x/package.json index 7bfc3c2b59..f92dcc9be1 100644 --- a/website-1.x/package.json +++ b/website-1.x/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-1-website", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "private": true, "scripts": { "start": "docusaurus-start", @@ -14,6 +14,6 @@ "crowdin-download": "crowdin --config ../crowdin.yaml download -b master" }, "dependencies": { - "docusaurus": "^2.0.0-alpha.55" + "docusaurus": "^2.0.0-alpha.56" } } diff --git a/website/docs/cli.md b/website/docs/cli.md index de0b9df084..ec40208547 100644 --- a/website/docs/cli.md +++ b/website/docs/cli.md @@ -110,3 +110,4 @@ Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the | Name | Default | Description | | --- | --- | --- | | `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. | +| `--skip-build` | `false` | Deploy website without building it. This may be useful when using custom deploy script. | diff --git a/website/docs/docs.md b/website/docs/docs.md index 5cfc0996fb..dcca52da45 100644 --- a/website/docs/docs.md +++ b/website/docs/docs.md @@ -243,6 +243,7 @@ type SidebarItemCategory = { type: 'category'; label: string; // Sidebar label text. items: SidebarItem[]; // Array of sidebar items. + collapsed: boolean; // Set the category to be collapsed or open by default }; ``` @@ -292,6 +293,26 @@ module.exports = { }; ``` +#### Expanded categories by default + +For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`: + +```js title="sidebars.js" +module.exports = { + docs: { + Guides: [ + 'creating-pages', + { + type: 'category', + label: 'Docs', + collapsed: false, + items: ['markdown-features', 'sidebar', 'versioning'], + }, + ], + }, +}; +``` + ## Docs-only mode If you just want the documentation feature, you can enable "docs-only mode". diff --git a/website/docs/installation.md b/website/docs/installation.md index 102575469c..9659bac6da 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -7,7 +7,7 @@ Docusaurus is essentially a set of npm [packages](https://github.com/facebook/do ## Requirements -- [Node.js](https://nodejs.org/en/download/) version >= 10.9.0 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed +- [Node.js](https://nodejs.org/en/download/) version >= 10.15.1 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed - [Yarn](https://yarnpkg.com/en/) version >= 1.5 (which can be checked by running `yarn version`). Yarn is a performant package manager for JavaScript and replaces the `npm` client. It is not strictly necessary but highly encouraged. ## Scaffold project website diff --git a/website/package.json b/website/package.json index f52087b14f..47e15557b4 100644 --- a/website/package.json +++ b/website/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-website", - "version": "2.0.0-alpha.55", + "version": "2.0.0-alpha.56", "private": true, "scripts": { "start": "docusaurus start", @@ -9,11 +9,11 @@ "deploy": "docusaurus deploy" }, "dependencies": { - "@docusaurus/core": "^2.0.0-alpha.55", - "@docusaurus/theme-live-codeblock": "^2.0.0-alpha.55", - "@docusaurus/plugin-ideal-image": "^2.0.0-alpha.55", - "@docusaurus/plugin-client-redirects": "^2.0.0-alpha.55", - "@docusaurus/preset-classic": "^2.0.0-alpha.55", + "@docusaurus/core": "^2.0.0-alpha.56", + "@docusaurus/plugin-ideal-image": "^2.0.0-alpha.56", + "@docusaurus/plugin-client-redirects": "^2.0.0-alpha.56", + "@docusaurus/preset-classic": "^2.0.0-alpha.56", + "@docusaurus/theme-live-codeblock": "^2.0.0-alpha.56", "classnames": "^2.2.6", "color": "^3.1.2", "npm-to-yarn": "^1.0.0-2", diff --git a/website/sidebars.js b/website/sidebars.js index 97658a054d..94f27479d4 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -6,30 +6,51 @@ */ module.exports = { - docs: { - Docusaurus: ['introduction', 'design-principles', 'contributing'], - 'Getting Started': ['installation', 'configuration'], - Guides: [ - 'creating-pages', - 'styling-layout', - 'static-assets', - { - Docs: ['docs-introduction', 'markdown-features', 'versioning'], - }, - 'blog', - 'search', - 'deployment', - 'migrating-from-v1-to-v2', - ], - 'Advanced Guides': ['using-plugins', 'using-themes', 'presets'], - 'API Reference': [ - 'cli', - 'docusaurus-core', - 'docusaurus.config.js', - 'lifecycle-apis', - 'theme-classic', - ], - }, + docs: [ + { + type: 'category', + label: 'Docusaurus', + items: ['introduction', 'design-principles', 'contributing'], + }, + { + type: 'category', + label: 'Getting Started', + collapsed: false, + items: ['installation', 'configuration'], + }, + { + type: 'category', + label: 'Guides', + items: [ + 'creating-pages', + 'styling-layout', + 'static-assets', + { + Docs: ['docs-introduction', 'markdown-features', 'versioning'], + }, + 'blog', + 'search', + 'deployment', + 'migrating-from-v1-to-v2', + ], + }, + { + type: 'category', + label: 'Advanced Guides', + items: ['using-plugins', 'using-themes', 'presets'], + }, + { + type: 'category', + label: 'API Reference', + items: [ + 'cli', + 'docusaurus-core', + 'docusaurus.config.js', + 'lifecycle-apis', + 'theme-classic', + ], + }, + ], community: [ 'support', 'team', diff --git a/website/versioned_docs/version-2.0.0-alpha.43/cli.md b/website/versioned_docs/version-2.0.0-alpha.43/cli.md deleted file mode 100644 index 87324205f0..0000000000 --- a/website/versioned_docs/version-2.0.0-alpha.43/cli.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: cli -title: CLI ---- - -Docusaurus provides a set of scripts to help you generate, serve, and deploy your website. - -Once your website is generated, your website package will contain the Docusaurus scripts that you may invoke with your package manager: - -```json -// package.json -{ - // ... - "scripts": { - "start": "docusaurus start", - "build": "docusaurus build", - "swizzle": "docusaurus swizzle", - "deploy": "docusaurus deploy" - } -} -``` - -## Docusaurus CLI commands - -Below is a list of Docusaurus CLI commands and their usages: - - - -### `docusaurus start` - -Builds and serves the static site with [Webpack Dev Server](https://webpack.js.org/configuration/dev-server). - -**options** - -| Options | Default | Description | -| --- | --- | --- | -| `--port` | `3000` | Specifies the port of the dev server | -| `--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` | -| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). | -| `--no-open` | `false` | Do not open automatically the page in the browser. | - -### `docusaurus build` - -Compiles your site for production. - -**options** - -| Options | Default | Description | -| --- | --- | --- | -| `--bundle-analyzer` | | Analyze your bundle with [bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) | - -### `docusaurus swizzle` - -> ⚠️ We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future. - -Swizzle any Docusaurus Theme components with your own component with `docusaurus swizzle`. - -```shell -docusaurus swizzle [componentName] [siteDir] -``` - -**params** - -- `themeName`: name of the theme you are using -- `swizzleComponent`: name of the component to be swizzled - -Running the above command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme. - -To unswizzle a component, simply delete the files of the swizzled component. - - - -To learn more about swizzling, check [here](#). - -### `docusaurus deploy` - -Deploys your site with [GitHub Pages](https://pages.github.com/). diff --git a/website/versioned_docs/version-2.0.0-alpha.43/deployment.md b/website/versioned_docs/version-2.0.0-alpha.43/deployment.md deleted file mode 100644 index f12cf898b7..0000000000 --- a/website/versioned_docs/version-2.0.0-alpha.43/deployment.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -id: deployment -title: Deployment ---- - -To build the static files of your website for production, run: - -```bash npm2yarn -npm run build -``` - -Once it finishes, you should see the production build under the `build/` directory. - -You can deploy your site to static site hosting services such as [ZEIT Now](https://zeit.co/now), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), and [Render](https://render.com/static-sites). Docusaurus sites are statically rendered so they work without JavaScript too! - -## Deploying to ZEIT Now - -Deploying your Docusaurus project to [ZEIT Now](https://zeit.co/now) will provide you with [various benefits](https://zeit.co/now) in the areas of performance and ease of use. - -Most importantly, however, deploying a Docusaurus project only takes a couple seconds: - -1. First, install their [command-line interface](https://zeit.co/download): - -```bash -npm i -g now -``` - -2. Run a single command inside the root directory of your project: - -```bash -now -``` - -**That's all.** Your docs will automatically be deployed. - -Now you can connect your site to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit. - -## Deploying to GitHub Pages - -Docusaurus provides a easy way to publish to GitHub Pages. - -### `docusaurus.config.js` settings - -First, modify your `docusaurus.config.js` and add the required params: - -| Name | Description | -| --- | --- | -| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, it is your GitHub username. In the case of Docusaurus, it is "_facebook_" which is the GitHub organization that owns Docusaurus. | -| `projectName` | The name of the GitHub repository. For example, the repository name for Docusaurus is "docusaurus", so the project name is "docusaurus". | -| `url` | URL for your GitHub Page's user/organization page. This is commonly 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/`. | - -In case you want to use your custom domain for GitHub Pages, create a `CNAME` file in the `static` directory. Anything within the `static` directory will be copied to the root of the `build` directory for deployment. - -You may refer to GitHub Pages' documentation [User, Organization, and Project Pages](https://help.github.com/en/articles/user-organization-and-project-pages) for more details. - -Example: - -```jsx {3-6} -module.exports = { - ... - url: 'https://endiliey.github.io', // Your website URL - baseUrl: '/', - projectName: 'endiliey.github.io', - organizationName: 'endiliey' - ... -} -``` - -### Environment settings - -Specify the Git user as an environment variable. - -| 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 GitHub username. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. | - -There are two more optional parameters that are set as environment variables: - -| Name | Description | -| --- | --- | -| `USE_SSH` | Set to `true` to use SSH instead of the default HTTPS for the connection to the GitHub repo. | -| `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. | - -### Deploy - -Finally, to deploy your site to GitHub Pages, run: - -**Bash** - -```bash -GIT_USER= yarn deploy -``` - -**Windows** - -```batch -cmd /C "set "GIT_USER=" && yarn deploy" -``` - - - -## Deploying to Netlify - -To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured: - -```js {3-4} -// docusaurus.config.js -module.exports = { - url: 'https://docusaurus-2.netlify.com', // url to your site with no trailing slash - baseUrl: '/', // base directory of your site relative to your repo -}; -``` - -Then, [create your site with Netlify](https://app.netlify.com/start). - -While you set up the site, specify the build commands and directories as follows: - -- build command: `npm run build` -- build directory: `build` - -If you did not configure these build options, you may still go to "Site settings" -> "Build and deploy" after your site is created. - -Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `master`. - -## Deploying to Render - -Render offers [free static site hosting](https://render.com/docs/static-sites) with fully managed SSL, custom domains, a global CDN and continuous auto deploys from your Git repo. Deploy your app in just a few minutes by following these steps. - -1. Create a new **Web Service** on Render, and give Render permission to access your Docusaurus repo. - -2. Select the branch to deploy. The default is `master`. - -3. Enter the following values during creation. - - | Field | Value | - | --------------------- | ------------- | - | **Environment** | `Static Site` | - | **Build Command** | `yarn build` | - | **Publish Directory** | `build` | - -That's it! Your app will be live on your Render URL as soon as the build finishes. diff --git a/website/versioned_docs/version-2.0.0-alpha.43/theme-classic.md b/website/versioned_docs/version-2.0.0-alpha.43/theme-classic.md deleted file mode 100644 index ff1b7d0442..0000000000 --- a/website/versioned_docs/version-2.0.0-alpha.43/theme-classic.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -id: theme-classic -title: '@docusaurus/theme-classic' ---- - -> :warning: _This section is a work in progress._ - -## Common - -### Dark mode - -To remove the ability to switch on dark mode, there is an option `themeConfig.disableDarkMode`, which is implicitly set to `false`. - -```js -// docusaurus.config.js -module.exports = { - ... - themeConfig: { - disableDarkMode: false, - ... - }, -}; -``` - -### Meta image - -You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`. - -```js -// docusaurus.config.js -module.exports = { - ... - themeConfig: { - /** - * Relative to your site's "static" directory. - * Cannot be SVGs. Can be external URLs too. - */ - image: 'img/docusaurus.png', - ... - }, -} -``` - -## Navbar - -### Navbar Title & Logo - -You can add a logo and title to the navbar via `themeConfig.navbar`. Logo can be placed in [static folder](static-assets.md). Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. You can also set a different logo for dark mode. - -```js -// docusaurus.config.js -module.exports = { - ... - themeConfig: { - navbar: { - title: 'Site Title', - logo: { - alt: 'Site Logo', - src: 'img/logo.svg', - srcDark: 'img/logo_dark.svg', // default to logo.src - href: 'https://v2.docusaurus.io/', // default to siteConfig.baseUrl - }, - }, - ... - }, -} -``` - -### Navbar Links - -You can add links to the navbar via `themeConfig.navbar.links`: - -```js -// docusaurus/config.js -module.exports = { - ... - themeConfig: { - navbar: { - links: [ - { - to: 'docs/docusaurus.config.js', - label: 'docusaurus.config.js', - position: 'left', - }, - // ... other links - ], - }, - ... - }, -} -``` - -Outbound links automatically get `target="_blank" rel="noopener noreferrer"`. - -### Auto-hide sticky navbar - -You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up. - -```js -// docusaurus/config.js -module.exports = { - ... - themeConfig: { - navbar: { - hideOnScroll: true, - }, - ... - }, -} -``` - -## Footer - -## `CodeBlock` - -Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks. - -### Theme - -By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so. - -```js {5,6} -// docusaurus/config.js -module.exports = { - themeConfig: { - prism: { - theme: require('prism-react-renderer/themes/github'), - darkTheme: require('prism-react-renderer/themes/dracula'), - }, - }, -}; -``` - -**Note:** If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the [docs for guidance](markdown-features.mdx#line-highlighting). - -### Default language - -You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed, e.g.: - -```js -// docusaurus/config.js -module.exports = { - ... - themeConfig: { - prism: { - defaultLanguage: 'javascript', - }, - ... - }, -}; -``` diff --git a/website/versioned_docs/version-2.0.0-alpha.43/blog.md b/website/versioned_docs/version-2.0.0-alpha.56/blog.md similarity index 82% rename from website/versioned_docs/version-2.0.0-alpha.43/blog.md rename to website/versioned_docs/version-2.0.0-alpha.56/blog.md index 1b84ecdbdf..a0a4bc41ab 100644 --- a/website/versioned_docs/version-2.0.0-alpha.43/blog.md +++ b/website/versioned_docs/version-2.0.0-alpha.56/blog.md @@ -9,12 +9,19 @@ To setup your site's blog, start by creating a `blog` directory. Then, add a navbar link to your blog within `docusaurus.config.js`: -```js -links: [ - ... - {to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right' - ... -] +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // ... + navbar: { + links: [ + // ... + // highlight-next-line + {to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right' + ], + }, + }, +}; ``` ## Adding posts @@ -30,7 +37,6 @@ author: Joel Marcey author_title: Co-creator of Docusaurus 1 author_url: https://github.com/JoelMarcey author_image_url: https://graph.facebook.com/611217057/picture/?height=200&width=200 -authorURL: https://github.com/JoelMarcey tags: [hello, docusaurus-v2] --- Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**](https://v2.docusaurus.io/). @@ -52,6 +58,7 @@ The only required field is `title`; however, we provide options to add author in - `author_title` - A description of the author. - `title` - The blog post title. - `tags` - A list of strings to tag to your post. +- `draft` - A boolean flag to indicate that the blog post is work in process and therefore should not be published yet. However, draft blog posts will be displayed during development. ## Summary truncation @@ -90,8 +97,7 @@ feedOptions?: { Example usage: -```js {9-12} -// docusaurus.config.js +```js {8-11} title="docusaurus.config.js" module.exports = { // ... presets: [ @@ -112,13 +118,13 @@ module.exports = { Accessing the feed: -The feed for RSS can be found at +The feed for RSS can be found at: ```text https://{your-domain}/blog/rss.xml ``` -and for atom +and for Atom: ```text https://{your-domain}/blog/atom.xml @@ -130,10 +136,7 @@ https://{your-domain}/blog/atom.xml You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path. -**Note:** Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route! - -```js {10} -// docusaurus.config.js +```js {9} title="docusaurus.config.js" module.exports = { // ... presets: [ @@ -150,6 +153,12 @@ module.exports = { }; ``` +:::note + +Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route! + +::: + + +### `docusaurus start` + +Builds and serves a preview of your site locally with [Webpack Dev Server](https://webpack.js.org/configuration/dev-server). + +#### Options + +| Name | Default | Description | +| --- | --- | --- | +| `--port` | `3000` | Specifies the port of the dev server. | +| `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. | +| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). | +| `--no-open` | `false` | Do not open automatically the page in the browser. | +| `--poll` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). | + +:::important + +Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production. + +::: + +### `docusaurus build` + +Compiles your site for production. + +#### Options + +| Name | Default | Description | +| --- | --- | --- | +| `--bundle-analyzer` | `false` | Analyze your bundle with the [webpack bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). | +| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. | +| `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. | + +### `docusaurus swizzle` + +:::caution + +We highly discourage swizzling of components until we've reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future. + +::: + +Change any Docusaurus theme components to your liking with `docusaurus swizzle`. + +```shell +docusaurus swizzle [componentName] [siteDir] + +# Example (leaving out the siteDir to indicate this directory) +docusaurus swizzle @docusaurus/theme-classic DocSidebar +``` + +Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme. + +#### Options + +| Name | Description | +| ------------------ | ------------------------------------- | +| `themeName` | The name of the theme you are using. | +| `swizzleComponent` | The name of the component to swizzle. | + +To unswizzle a component, simply delete the files of the swizzled component. + + + +### `docusaurus deploy` + +Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the docs on [deployment](deployment.md/#deploying-to-github-pages) for more details. + +#### Options + +| Name | Default | Description | +| --- | --- | --- | +| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. | +| `--skip-build` | `false` | Deploy website without building it. This may be useful when using custom deploy script. | diff --git a/website/versioned_docs/version-2.0.0-alpha.43/configuration.md b/website/versioned_docs/version-2.0.0-alpha.56/configuration.md similarity index 69% rename from website/versioned_docs/version-2.0.0-alpha.43/configuration.md rename to website/versioned_docs/version-2.0.0-alpha.56/configuration.md index 3b9a289a42..5555732d21 100644 --- a/website/versioned_docs/version-2.0.0-alpha.43/configuration.md +++ b/website/versioned_docs/version-2.0.0-alpha.56/configuration.md @@ -3,24 +3,24 @@ id: configuration title: Configuration --- -Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We will guard the fields of this file, and facilitate making this data object accessible across your site. +Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We guard the fields of this file, and facilitate making this data object accessible across your site. -Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to customize fields. +Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to customize the site. -## What goes into `docusaurus.config.js`? +## What goes into a `docusaurus.config.js`? -You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` at root that includes the necessary data for the initial site. +You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` that includes defaults for the common options. However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented. The high-level overview of Docusaurus configuration can be categorized into: -- [Site Metadata](#site-metadata) -- [Deployment Configurations](#deployment-configurations) -- [Theme, Plugin, and Preset Configurations](#theme-plugin-and-preset-configurations) -- [Custom Configurations](#custom-configurations) +- [Site metadata](#site-metadata) +- [Deployment configurations](#deployment-configurations) +- [Theme, plugin, and preset configurations](#theme-plugin-and-preset-configurations) +- [Custom configurations](#custom-configurations) -For exact reference to each of the configurable fields, you may refer to [**docusaurus.config.js API reference**](docusaurus.config.js.md). +For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](docusaurus.config.js.md). ### Site metadata @@ -30,16 +30,15 @@ They are used in a number of places such as your site's title and headings, brow ### Deployment configurations -Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with Docusaurus' `deploy` command. +Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with the `deploy` command. It is recommended to check the [deployment docs](deployment.md) for more information. ### Theme, plugin, and preset configurations -List the installed [themes](using-themes.md), [plugins](using-plugins.md), and [presets](presets.md) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages: +List the [theme](using-themes.md), [plugins](using-plugins.md), and [presets](presets.md) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages: -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { // ... plugins: [ @@ -52,8 +51,7 @@ module.exports = { They can also be loaded from local directories: -```js -// docusaurus.config.js +```js title="docusaurus.config.js" const path = require('path'); module.exports = { @@ -64,8 +62,7 @@ module.exports = { To specify options for a plugin or theme, replace the name of the plugin or theme in the config file with an array containing the name and an options object: -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { // ... plugins: [ @@ -85,8 +82,7 @@ module.exports = { To specify options for a plugin or theme that is bundled in a preset, pass the options through the `presets` field. In this example, `docs` refers to `@docusaurus/plugin-content-docs` and `theme` refers to `@docusaurus/theme-classic`. -```js -//docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { // ... presets: [ @@ -109,17 +105,20 @@ For further help configuring themes, plugins, and presets, see [Using Themes](us ### Custom configurations -Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields` +Docusaurus guards `docusaurus.config.js` from unknown fields. To add custom fields, define them in `customFields`. Example: -```js {3-6} -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { + // ... + // highlight-start customFields: { image: '', keywords: [], }, + // highlight-end + // ... }; ``` @@ -127,19 +126,26 @@ module.exports = { Your configuration object will be made available to all the components of your site. And you may access them via React context as `siteConfig`. -Basic Example: +Basic example: -```jsx {2,5-6} +```jsx import React from 'react'; +// highlight-next-line import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; const Hello = () => { + // highlight-start const context = useDocusaurusContext(); const {siteConfig = {}} = context; + // highlight-end const {title, tagline} = siteConfig; return
{`${title} · ${tagline}`}
; }; ``` -> If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in `docusaurus.config.js`. +:::tip + +If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in `docusaurus.config.js`. + +::: diff --git a/website/versioned_docs/version-2.0.0-alpha.43/contributing.md b/website/versioned_docs/version-2.0.0-alpha.56/contributing.md similarity index 95% rename from website/versioned_docs/version-2.0.0-alpha.43/contributing.md rename to website/versioned_docs/version-2.0.0-alpha.56/contributing.md index b0d825e050..130a7f42a9 100644 --- a/website/versioned_docs/version-2.0.0-alpha.43/contributing.md +++ b/website/versioned_docs/version-2.0.0-alpha.56/contributing.md @@ -3,7 +3,7 @@ id: contributing title: Contributing --- -[Docusaurus 2](https://v2.docusaurus.io) is currently under alpha development. We have [early adopters who already started using it](/showcase). We are now welcoming contributors to collaborate on the next Docusaurus. +[Docusaurus 2](https://v2.docusaurus.io/) is currently under alpha development. We have [early adopters who already started using it](/showcase). We are now welcoming contributors to collaborate on the next Docusaurus. 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: @@ -48,7 +48,7 @@ We use [GitHub Issues](https://github.com/facebook/docusaurus/issues) for our pu If you have questions about using Docusaurus, contact the Docusaurus Twitter account at [@docusaurus](https://twitter.com/docusaurus), and we will do our best to answer your questions. -You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/master/.github/ISSUE_TEMPLATE/feature.md) +You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/master/.github/ISSUE_TEMPLATE/feature.md/) ### Reporting security bugs @@ -97,7 +97,7 @@ Use lower case not title case! #### Style guide -[Prettier](https://prettier.io) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `npm run prettier`. +[Prettier](https://prettier.io/) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `npm run prettier`. However, there are still some styles that Prettier cannot pick up. @@ -124,7 +124,7 @@ We have a list of [beginner friendly issues](https://github.com/facebook/docusau ### Proposing a change -If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with [feature template](https://github.com/facebook/docusaurus/issues/new?template=feature.md). +If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with [feature template](https://github.com/facebook/docusaurus/issues/new?template=feature.md/). If you intend to change the public API (e.g., something in `docusaurus.config.js`), or make any non-trivial changes to the implementation, we recommend filing an issue with [proposal template](https://github.com/facebook/docusaurus/issues/new?template=proposal.md) and including `[Proposal]` in the title. This lets us reach an agreement on your proposal before you put significant effort into it. These types of issues should be rare. @@ -138,7 +138,7 @@ Please make sure the following is done when submitting a pull request: 1. Fork [the repository](https://github.com/facebook/docusaurus) and create your branch from `master`. 1. Add the copyright notice to the top of any code new files you've added. -1. Describe your [test plan](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/docusaurus/blob/master/admin/testing-changes-on-Docusaurus-itself.md)! +1. Describe your [test plan](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/docusaurus/blob/master/admin/testing-changes-on-Docusaurus-itself.md/)! 1. Make sure your code lints (`yarn prettier && yarn lint`). 1. Make sure your Jest tests pass (`yarn test`). 1. If you haven't already, [sign the CLA](https://code.facebook.com/cla). diff --git a/website/versioned_docs/version-2.0.0-alpha.43/creating-pages.md b/website/versioned_docs/version-2.0.0-alpha.56/creating-pages.md similarity index 76% rename from website/versioned_docs/version-2.0.0-alpha.43/creating-pages.md rename to website/versioned_docs/version-2.0.0-alpha.56/creating-pages.md index e8dbc01d25..7306a1b06d 100644 --- a/website/versioned_docs/version-2.0.0-alpha.43/creating-pages.md +++ b/website/versioned_docs/version-2.0.0-alpha.56/creating-pages.md @@ -5,13 +5,15 @@ title: Creating Pages In this section, we will learn about creating ad-hoc pages in Docusaurus using React. This is most useful for creating one-off standalone pages like a showcase page, playground page or support page. +The functionality of pages is powered by `@docusaurus/plugin-content-pages`. + ## Adding a new page In the `/src/pages/` directory, create a file called `hello.js` with the following contents: -```jsx +```jsx title="/src/pages/hello.js" import React from 'react'; import Layout from '@theme/Layout'; @@ -41,6 +43,12 @@ Once you save the file, the development server will automatically reload the cha Each page doesn't come with any styling. You will need to import the `Layout` component from `@theme/Layout` and wrap your contents within that component if you want the navbar and/or footer to appear. +:::tip + +You can also create a page in TypeScript, in which case the file name should use the `.tsx` extension, eg. `hello.tsx`. + +::: + ## Routing If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example: @@ -55,7 +63,7 @@ In this component-based development era, it is encouraged to co-locate your styl - Add a `/src/pages/support.js` file - Create a `/src/pages/support/` directory and a `/src/pages/support/index.js` file. -The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For e.g. a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. **Note:** this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (`support/index.js`). +The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. **Note:** this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (`support/index.js`). ```sh my-website @@ -69,6 +77,12 @@ my-website . ``` +:::caution + +All JavaScript/TypeScript files within the `src/pages/` directory will have corresponding website paths generated for them. Do not put reusable components or test files (ending with `.test.js`) into that directory otherwise they will be turned into pages, which might not be intended. + +::: + ## Using React React is used as the UI library to create pages. Every page component should export a React component and you can leverage on the expressiveness of React to build rich and interactive content. diff --git a/website/versioned_docs/version-2.0.0-alpha.56/deployment.md b/website/versioned_docs/version-2.0.0-alpha.56/deployment.md new file mode 100644 index 0000000000..1f281157fb --- /dev/null +++ b/website/versioned_docs/version-2.0.0-alpha.56/deployment.md @@ -0,0 +1,299 @@ +--- +id: deployment +title: Deployment +--- + +To build the static files of your website for production, run: + +```bash npm2yarn +npm run build +``` + +Once it finishes, the static files will be generated within the `build/` directory. + +You can deploy your site to static site hosting services such as [ZEIT Now](https://zeit.co/now), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), [Render](https://render.com/static-sites), and [Surge](https://surge.sh/help/getting-started-with-surge). Docusaurus sites are statically rendered so they work without JavaScript too! + +## Deploying to GitHub Pages + +Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.github.com/). Which is hosting that comes for free with every GitHub repository. + +### `docusaurus.config.js` settings + +First, modify your `docusaurus.config.js` and add the required params: + +| Name | Description | +| --- | --- | +| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, it is your GitHub username. In the case of Docusaurus, it is "_facebook_" which is the GitHub organization that owns Docusaurus. | +| `projectName` | The name of the GitHub repository. For example, the repository name for Docusaurus is "docusaurus", so the project name is "docusaurus". | +| `url` | URL for your GitHub Page's user/organization page. This is commonly 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/`. | + +In case you want to use your custom domain for GitHub Pages, create a `CNAME` file in the `static` directory. Anything within the `static` directory will be copied to the root of the `build` directory for deployment. + +You may refer to GitHub Pages' documentation [User, Organization, and Project Pages](https://help.github.com/en/articles/user-organization-and-project-pages) for more details. + +Example: + +```jsx {3-6} title="docusaurus.config.js" +module.exports = { + // ... + url: 'https://endiliey.github.io', // Your website URL + baseUrl: '/', + projectName: 'endiliey.github.io', + organizationName: 'endiliey', + // ... +}; +``` + +:::tip + +By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.com/). Since Jekyll will discard any files that begin with `_`, it is recommended that you disable Jekyll by adding an empty file named `.nojekyll` file to your `static` directory. + +::: + +### Environment settings + +Specify the Git user as an environment variable. + +| 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 GitHub username. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. | + +There are two more optional parameters that are set as environment variables: + +| Name | Description | +| --- | --- | +| `USE_SSH` | Set to `true` to use SSH instead of the default HTTPS for the connection to the GitHub repo. | +| `DEPLOYMENT_BRANCH` | The branch that the website will be deployed to, defaults to `gh-pages` for normal repos and `master` for repository names ending in `github.io`. | +| `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. | + +### Deploy + +Finally, to deploy your site to GitHub Pages, run: + +**Bash** + +```bash +GIT_USER= yarn deploy +``` + +**Windows** + +```batch +cmd /C "set "GIT_USER=" && yarn deploy" +``` + +### Triggering deployment with GitHub Actions + +[GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository. + +This workflow assumes your documentation resided in `documentation` branch of your repository and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for `gh-pages` branch. + +1. Generate a new [SSH key](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). +1. By default, your public key should have been created in `~/.ssh/id_rsa.pub` or use the name you've provided in the previous step to add your key to [GitHub deploy keys](https://developer.github.com/v3/guides/managing-deploy-keys/). +1. Copy key to clipboard with `xclip -sel clip < ~/.ssh/id_rsa.pub` and paste it as a [deploy key](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys) in your repository. Copy file content if the command line doesn't work for you. Check the box for `Allow write access` before saving your deployment key. +1. You'll need your private key as a [GitHub secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) to allow Docusaurus to run the deployment for you. +1. Copy your private key with `xclip -sel clip < ~/.ssh/id_rsa` and paste a GitHub secret with name `GH_PAGES_DEPLOY`. Copy file content if the command line doesn't work for you. Save your secret. +1. Create you [documentation workflow file](https://help.github.com/en/actions/configuring-and-managing-workflows/configuring-a-workflow#creating-a-workflow-file) in `.github/workflows/`. In this example it's `documentation.yml`. + +```yaml title="documentation.yml" +name: documentation + +on: + pull_request: + branches: [documentation] + push: + branches: [documentation] + +jobs: + checks: + if: github.event_name != 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - uses: actions/setup-node@v1 + with: + node-version: '12.x' + run: | + npm ci + npm run build + gh-release: + if: github.event_name != 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - uses: actions/setup-node@v1 + with: + node-version: '12.x' + - name: Add key to allow access to repository + env: + SSH_AUTH_SOCK: /tmp/ssh_agent.sock + run: | + mkdir -p ~/.ssh + ssh-keyscan github.com >> ~/.ssh/known_hosts + echo "${{ secrets.GH_PAGES_DEPLOY }}" > ~/.ssh/id_rsa + chmod 600 ~/.ssh/id_rsa + cat <> ~/.ssh/config + Host github.com + HostName github.com + IdentityFile ~/.ssh/id_rsa + EOT + - name: Release to GitHub Pages + env: + USE_SSH: true + GIT_USER: git + run: | + git config --global user.email "actions@gihub.com" + git config --global user.name "gh-actions" + npm ci + npx docusaurus deploy +``` + +1. Now when a new pull request arrives towards your repository in branch `documentation` it will automatically ensure that Docusaurus build is successful. +1. When pull request is merged to `documentation` branch or someone pushes to `documentation` branch directly it will be built and deployed to `gh-pages` branch. +1. After this step, your updated documentation will be available on the GitHub pages. + +### Triggering deployment with Travis CI + +Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate the deployment of your website is to invoke the `yarn deploy` script whenever your website is updated. The following section covers how to do just that using [Travis CI](https://travis-ci.com/), a popular continuous integration service provider. + +1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). +1. Using your GitHub account, [add the Travis CI app](https://github.com/marketplace/travis-ci) to the repository you want to activate. +1. Open your Travis CI dashboard. The URL looks like https://travis-ci.com/USERNAME/REPO, and navigate to the `More options` > `Setting` > `Environment Variables` section of your repository. +1. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username). +1. Create a `.travis.yml` on the root of your repository with the following: + +```yaml title=".travis.yml" +language: node_js +node_js: + - '10' +branches: + only: + - master +cache: + yarn: true +script: + - git config --global user.name "${GH_NAME}" + - git config --global user.email "${GH_EMAIL}" + - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc + - yarn && GIT_USER="${GH_NAME}" yarn deploy +``` + +Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script. + +## Deploying to Netlify + +To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured: + +```js {2-3} title="docusaurus.config.js" +module.exports = { + url: 'https://docusaurus-2.netlify.com', // Url to your site with no trailing slash + baseUrl: '/', // Base directory of your site relative to your repo + // ... +}; +``` + +Then, [create your site with Netlify](https://app.netlify.com/start). + +While you set up the site, specify the build commands and directories as follows: + +- build command: `npm run build` +- build directory: `build` + +If you did not configure these build options, you may still go to "Site settings" -> "Build and deploy" after your site is created. + +Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `master`. + +:::important + +Make sure to disable Netlify setting `Pretty URLs` to prevent lowercased URLs, unnecessary redirects and 404 errors. + +::: + +## Deploying to ZEIT Now + +Deploying your Docusaurus project to [ZEIT Now](https://zeit.co/now) will provide you with [various benefits](https://zeit.co/now) in the areas of performance and ease of use. + +Most importantly, however, deploying a Docusaurus project only takes a couple of seconds: + +1. First, install their [command-line interface](https://zeit.co/download): + +```bash +npm i -g now +``` + +1. Run a single command inside the root directory of your project: + +```bash +now +``` + +**That's all.** Your docs will automatically be deployed. + +Now you can connect your site to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit. + +## Deploying to Render + +Render offers [free static site hosting](https://render.com/docs/static-sites) with fully managed SSL, custom domains, a global CDN and continuous auto-deploy from your Git repo. Deploy your app in just a few minutes by following these steps. + +1. Create a new **Web Service** on Render, and give Render permission to access your Docusaurus repo. + +1. Select the branch to deploy. The default is `master`. + +1. Enter the following values during creation. + + | Field | Value | + | --------------------- | ------------- | + | **Environment** | `Static Site` | + | **Build Command** | `yarn build` | + | **Publish Directory** | `build` | + +That's it! Your app will be live on your Render URL as soon as the build finishes. + +## Deploying to Surge + +Surge is a [static web hosting platform](https://surge.sh/help/getting-started-with-surge), it is used to deploy your Docusaurus project from the command line in a minute. Deploying your project to Surge is easy and it is also free (including a custom domain and SSL). + +Deploy your app in a matter of seconds using surge with the following steps: + +1. First, install Surge using npm by running the following command: + +```bash +npm install --g surge +``` + +1. To build the static files of your site for production in the root directory of your project, run: + +```bash +npm run build +``` + +1. Then, run this command inside the root directory of your project: + +```bash +surge build/ +``` + +First-time users of Surge would be prompted to create an account from the command line(happens only once). + +Confirm that the site you want to publish is in the `build` directory, a randomly generated subdomain `*.surge.sh subdomain` is always given(which can be edited). + +### Using your domain + +If you have a domain name you can deploy your site using surge to your domain using the command: + +```bash +surge build/ yourdomain.com +``` + +Your site is now deployed for free at `subdomain.surge.sh` or `yourdomain.com` depending on the method you chose. + +### Setting up CNAME file + +Store your domain in a CNAME file for future deployments with the following command: + +```bash +echo subdomain.surge.sh > CNAME +``` + +You can deploy any other changes in the future with the command `surge`. diff --git a/website/versioned_docs/version-2.0.0-alpha.43/design-principles.md b/website/versioned_docs/version-2.0.0-alpha.56/design-principles.md similarity index 97% rename from website/versioned_docs/version-2.0.0-alpha.43/design-principles.md rename to website/versioned_docs/version-2.0.0-alpha.56/design-principles.md index 05d13d38b7..8e85dbfde8 100644 --- a/website/versioned_docs/version-2.0.0-alpha.43/design-principles.md +++ b/website/versioned_docs/version-2.0.0-alpha.56/design-principles.md @@ -3,7 +3,11 @@ id: design-principles title: Design Principles --- -> :warning: _This section is a work in progress._ +:::caution + +This section is a work in progress. + +::: - **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8). - **Intuitive** - Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with. diff --git a/website/versioned_docs/version-2.0.0-alpha.43/sidebar.md b/website/versioned_docs/version-2.0.0-alpha.56/docs.md similarity index 51% rename from website/versioned_docs/version-2.0.0-alpha.43/sidebar.md rename to website/versioned_docs/version-2.0.0-alpha.56/docs.md index 1978b05e2c..5cfc0996fb 100644 --- a/website/versioned_docs/version-2.0.0-alpha.43/sidebar.md +++ b/website/versioned_docs/version-2.0.0-alpha.56/docs.md @@ -1,12 +1,75 @@ --- -id: sidebar -title: Sidebar +id: docs-introduction +title: Docs Introduction +sidebar_label: Introduction --- +The docs feature provides users with a way to organize Markdown files in a hierarchical format. + +## Document ID + +Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory. + +For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`. + +```bash +website # Root directory of your site +└── docs +   ├── greeting.md + └── guide + └── hello.md +``` + +However, the last part of the `id` can be defined by user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`. + +```yml +--- +id: part1 +--- +Lorem ipsum +``` + +## Home page docs + +Using the `homePageId` property, you can create a home page of your docs. To do this, you can create a new document, especially for this purpose with the id as `_index`, or you could specify an existing document id. + +```js {8} title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + homePageId: 'getting-started', // Defaults to `_index` + // ... + }, + }, + ], + ], + // ... +}; +``` + +Given the example above, now when you navigate to the path `/docs` you will see that the document content with id is `getting-started`. This functionality also works for docs with versioning enabled. + +:::important + +The document id of `_index` is reserved exclusively for the home doc page, so it will not work as a standalone route. + +::: + +:::note + +The page `docs` that you created (eg. `src/pages/docs.js`) will take precedence over the route generated via the `homePageId` option. + +::: + +## Sidebar + To generate a sidebar to your Docusaurus site, you need to define a file that exports a sidebar object and pass that into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`. -```js {9-10} -// docusaurus.config.js +```js {8-9} title="docusaurus.config.js" module.exports = { // ... presets: [ @@ -17,16 +80,16 @@ module.exports = { // Sidebars filepath relative to the site dir. sidebarPath: require.resolve('./sidebars.js'), }, - ... + // ... }, ], ], }; ``` -## Sidebar object +### Sidebar object -A sidebar object is defined like this. +A sidebar object is defined like this: ```typescript type Sidebar = { @@ -40,8 +103,7 @@ type Sidebar = { 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 +```js title="sidebars.js" module.exports = { docs: { 'Getting started': ['greeting'], @@ -50,10 +112,9 @@ module.exports = { }; ``` -If you don't want to rely on iteration order of JavaScript object keys for the category name, the following sidebar object is also equivalent of the above. +Keep in mind that EcmaScript does not guarantee `Object.keys({a,b}) === ['a','b']` (yet, this is generally true). If you don't want to rely on iteration order of JavaScript object keys for the category name, the following sidebar object is also equivalent of the above shorthand syntax. -```js -// sidebars.js +```js title="sidebars.js" module.exports = { docs: [ { @@ -74,8 +135,7 @@ You can also have multiple sidebars for different Markdown files by adding more Example: -```js -// sidebars.js +```js title="sidebars.js" module.exports = { firstSidebar: { 'Category A': ['doc1'], @@ -87,30 +147,7 @@ module.exports = { }; ``` -## Document ID - -Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory. - -For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`. - -```bash -website # root directory of your site -└── docs -   ├── greeting.md - └── guide - └── hello.md -``` - -However, the last part of the `id` can be defined by user in the frontmatter. For example, if `guide/hello.md` content is defined as below, it's final `id` is `guide/part1`. - -```yml ---- -id: part1 ---- -Lorem ipsum -``` - -## Sidebar item +#### Sidebar item As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a few types we support: @@ -119,7 +156,7 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a - [Ref](#ref) - [Category](#category) -### Doc +#### Doc ```typescript type SidebarItemDoc = @@ -147,8 +184,7 @@ Using just the [Document ID](#document-id) is perfectly valid as well, the follo Note that using this type will bind the linked doc to current sidebar, this means that if you access `doc1` page, the sidebar displayed will be the sidebar this item is on. For below case, `doc1` is bounded to `firstSidebar`. -```js -// sidebars.js +```js title="sidebars.js" module.exports = { firstSidebar: { 'Category A': ['doc1'], @@ -160,7 +196,7 @@ module.exports = { }; ``` -### Link +#### Link ```typescript type SidebarItemLink = { @@ -175,12 +211,12 @@ Sidebar item type that links to a non-document page. Example: ```js { type: 'link', - label: 'Custom Label', // string - the label that should be displayed. - href: 'https://example.com' // string - the target URL. + label: 'Custom Label', // The label that should be displayed (string). + href: 'https://example.com' // The target URL (string). } ``` -### Ref +#### Ref ```typescript type SidebarItemRef = { @@ -194,11 +230,11 @@ Sidebar item type that links to doc without bounding it to the sidebar. Example: ```js { type: 'ref', - id: 'doc1', // string - document id + id: 'doc1', // Document id (string). } ``` -### Category +#### Category This is used to add hierarchies to the sidebar: @@ -212,8 +248,7 @@ type SidebarItemCategory = { As an example, here's how we created the subcategory for "Docs" under "Guides" in this site: -```js -// sidebars.js +```js title="sidebars.js" module.exports = { docs: { Guides: [ @@ -221,24 +256,77 @@ module.exports = { { type: 'category', label: 'Docs', - items: ['markdown-features', 'sidebar'], + items: ['markdown-features', 'sidebar', 'versioning'], }, ], }, }; ``` -### Collapsible categories +**Note**: it's possible to use the shorthand syntax to create nested categories: + +```js title="sidebars.js" +module.exports = { + docs: { + Guides: [ + 'creating-pages', + { + Docs: ['markdown-features', 'sidebar', 'versioning'], + }, + ], + }, +}; +``` + +#### Collapsible categories For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`: -```js {5} -// docusaurus.config.js +```js {4} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { sidebarCollapsible: false, - ... + // ... }, -} +}; ``` + +## Docs-only mode + +If you just want the documentation feature, you can enable "docs-only mode". + +To achieve this, set the `routeBasePath` property of the `docs` object in `@docusaurus/preset-classic` in `docusaurus.config.js` to the root of your site, and also in that object set the `homePageId` property with the value of the document ID that you show as root of the docs. + +:::note + +More details on functionality of home page for docs can be found in [appropriate section](#home-page-docs). + +::: + +```js {8-9} title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + routeBasePath: '/', // Set this value to '/'. + homePageId: 'getting-started', // Set to existing document id. + // ... + }, + }, + ], + ], + // ... +}; +``` + +Now, when visiting your site, it will show your initial document instead of a landing page. + +:::tip + +There's also a "blog-only mode", for those who only want to use the blog component of Docusaurus 2. You can use the same method detailed above, except that you need to delete the `/src/pages/index.js` file. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode). + +::: diff --git a/website/versioned_docs/version-2.0.0-alpha.43/docusaurus-core.md b/website/versioned_docs/version-2.0.0-alpha.56/docusaurus-core.md similarity index 57% rename from website/versioned_docs/version-2.0.0-alpha.43/docusaurus-core.md rename to website/versioned_docs/version-2.0.0-alpha.56/docusaurus-core.md index 48343885f6..92e54798ca 100644 --- a/website/versioned_docs/version-2.0.0-alpha.43/docusaurus-core.md +++ b/website/versioned_docs/version-2.0.0-alpha.56/docusaurus-core.md @@ -4,9 +4,11 @@ title: Docusaurus Client API sidebar_label: Client API --- -Docusaurus provides some API on client that can be helpful when building your site. +Docusaurus provides some APIs on the clients that can be helpful to you when building your site. -## `Head` +## Components + +### `` This reusable React component will manage all of your changes to the document head. It takes plain HTML tags and outputs plain HTML tags and is beginner-friendly. It is a wrapper around [React Helmet](https://github.com/nfl/react-helmet). @@ -55,11 +57,11 @@ Outputs ``` -## `Link` +### `` This component enables linking to internal pages as well as a powerful performance feature called preloading. Preloading is used to prefetch resources so that the resources are fetched by the time the user navigates with this component. We use an `IntersectionObserver` to fetch a low-priority request when the `` is in the viewport and then use an `onMouseOver` event to trigger a high-priority request when it is likely that a user will navigate to the requested resource. -The component is a wrapper around react-router’s `` component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s `` component. +The component is a wrapper around react-router’s `` component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s `` component. ```jsx {2,7} import React from 'react'; @@ -71,14 +73,14 @@ const Page = () => ( Check out my blog!

- {/* Note that external links still use `a` tags. */} + {/* Note that external links still use `a` tags, but automatically opens in new tab. */} Follow me on Twitter!

); ``` -### `to`: string +#### `to`: string The target location to navigate to. Example: `/docs/introduction`. @@ -86,19 +88,45 @@ The target location to navigate to. Example: `/docs/introduction`. ``` -### `activeClassName`: string +### `` -The class to give the `` when it is active. The default given class is `active`. This will be joined with the `className` prop. +Rendering a `` will navigate to a new location. The new location will override the current location in the history stack, like server-side redirects (HTTP 3xx) do. You can refer to [React Router's Redirect documentation](https://reacttraining.com/react-router/web/api/Redirect) for more info on available props. -```jsx {1} - - FAQs - +Example usage: + +```jsx {2,5} +import React from 'react'; +import {Redirect} from '@docusaurus/router'; + +function Home() { + return ; +} ``` -## `useDocusaurusContext` +### `` -React Hooks to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](docusaurus.config.js.md). +The `` component accepts a `children` prop, a render function which will not be executed during the pre-rendering phase of the build process. This is useful for hiding code that is only meant to run in the browsers (e.g. where the `window`/`document` objects are being accessed). To improve SEO, you can also provide fallback content using the `fallback` prop, which will be prerendered until in the build process and replaced with the client-side only contents when viewed in the browser. + +```jsx +import BrowserOnly from '@docusaurus/BrowserOnly'; + +function MyComponent() { + return ( + The fallback content to display on prerendering}> + {() => { + // Something that should be excluded during build process prerendering. + }} + + ); +} +``` + +## Hooks + +### `useDocusaurusContext` + +React hook to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](docusaurus.config.js.md). ```ts interface DocusaurusContext { @@ -121,9 +149,9 @@ const Test = () => { }; ``` -## `useBaseUrl` +### `useBaseUrl` -React Hook to automatically prepend `baseUrl` to a string automatically. This is particularly useful if you don't want to hardcode your baseUrl. +React hook to automatically prepend `baseUrl` to a string automatically. This is particularly useful if you don't want to hardcode your config's `baseUrl`. We highly recommend you to use this. Example usage: @@ -145,17 +173,25 @@ function Help() { } ``` -## `Redirect` +## Modules -Rendering a `` will navigate to a new location. The new location will override the current location in the history stack, like server-side redirects (HTTP 3xx) do. You can refer to [React Router's Redirect documentation](https://reacttraining.com/react-router/web/api/Redirect) for more info on available props. +### `ExecutionEnvironment` -Example usage: +A module which exposes a few boolean variables to check the current rendering environment. Useful if you want to only run certain code on client/server or need to write server-side rendering compatible code. -```jsx {2,5} +```jsx {2} import React from 'react'; -import {Redirect} from '@docusaurus/router'; +import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; -function Home() { - return ; +function MyPage() { + const location = ExecutionEnvironment.canUseDOM ? window.href.location : null; + return
{location}
; } ``` + +| Field | Description | +| --- | --- | +| `ExecutionEnvironment.canUseDOM` | `true` if on client, `false` if prerendering. | +| `ExecutionEnvironment.canUseEventListeners` | `true` if on client and has `window.addEventListener`. | +| `ExecutionEnvironment.canUseIntersectionObserver` | `true` if on client and has `IntersectionObserver`. | +| `ExecutionEnvironment.canUseViewport` | `true` if on client and has `window.screen`. | diff --git a/website/versioned_docs/version-2.0.0-alpha.43/docusaurus.config.js.md b/website/versioned_docs/version-2.0.0-alpha.56/docusaurus.config.js.md similarity index 87% rename from website/versioned_docs/version-2.0.0-alpha.43/docusaurus.config.js.md rename to website/versioned_docs/version-2.0.0-alpha.56/docusaurus.config.js.md index d0b3a622d4..b114bb759c 100644 --- a/website/versioned_docs/version-2.0.0-alpha.43/docusaurus.config.js.md +++ b/website/versioned_docs/version-2.0.0-alpha.56/docusaurus.config.js.md @@ -16,35 +16,19 @@ description: API reference for Docusaurus configuration file. Title for your website. -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { title: 'Docusaurus', }; ``` -### `tagline` - -- Type: `string` - -The tagline for your website. - -```js -// docusaurus.config.js -module.exports = { - tagline: - 'Docusaurus makes it easy to maintain Open Source documentation websites.', -}; -``` - ### `favicon` - Type: `string` URL for site favicon. Example: -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { favicon: 'https://v2.docusaurus.io/favicon.ico', }; @@ -63,8 +47,7 @@ You can also use the favicon URL relative to the `static` directory of your site So you can refer it like below: -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { favicon: 'img/favicon.ico', }; @@ -76,8 +59,7 @@ module.exports = { URL for your website. This can also be considered the top-level hostname. For example, `https://facebook.github.io` is the URL of https://facebook.github.io/metro/, and `https://docusaurus.io` is the URL for https://docusaurus.io. This field is related to the [baseUrl](#baseurl) field. -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { url: 'https://docusaurus.io', }; @@ -89,8 +71,7 @@ module.exports = { Base URL for your site. This can also be considered the path after the host. For example, `/metro/` is the baseUrl of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field. -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { baseUrl: '/', }; @@ -98,16 +79,28 @@ module.exports = { ## Optional fields +### `tagline` + +- Type: `string` + +The tagline for your website. + +```js title="docusaurus.config.js" +module.exports = { + tagline: + 'Docusaurus makes it easy to maintain Open Source documentation websites.', +}; +``` + ### `organizationName` - Type: `string` The GitHub user or organization that owns the repository. Used by the deployment command. -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { - // Docusaurus's organization is facebook + // Docusaurus' organization is facebook organizationName: 'facebook', }; ``` @@ -118,8 +111,7 @@ module.exports = { The name of the GitHub repository. Used by the deployment command. -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { projectName: 'docusaurus', }; @@ -131,8 +123,7 @@ module.exports = { The hostname of your server. Useful if you are using GitHub Enterprise. -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { githubHost: 'github.com', }; @@ -150,8 +141,7 @@ For Docusaurus' default theme _classic_, we use `themeConfig` to customize your Example: -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { themeConfig: { navbar: { @@ -163,6 +153,7 @@ module.exports = { links: [ { to: 'docs/docusaurus.config.js', + activeBasePath: 'docs', label: 'docusaurus.config.js', position: 'left', }, @@ -187,7 +178,7 @@ module.exports = { alt: 'Facebook Open Source Logo', src: 'https://docusaurus.io/img/oss_logo.png', }, - copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, + copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here }, }, }; @@ -199,8 +190,7 @@ module.exports = { - Type: `any[]` -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { plugins: [], }; @@ -212,8 +202,7 @@ module.exports = { - Type: `any[]` -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { themes: [], }; @@ -225,8 +214,7 @@ module.exports = { - Type: `any[]` -```js -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { presets: [], }; @@ -234,12 +222,11 @@ module.exports = { ### `customFields` -Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields` +Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`. - Type: `Object` -```jsx -// docusaurus.config.js +```js title="docusaurus.config.js" module.exports = { customFields: { admin: 'endi', @@ -264,8 +251,7 @@ Note that `