15308555518/ docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-12-25 17:22:50 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'master' into feature/client-side-redirects

This commit is contained in:
Sébastien Lorber 2020-05-28 16:11:58 +02:00 committed by GitHub
parent 4913ca638e 0047db2896
commit 768ed7368b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
87 changed files with 2775 additions and 1220 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.eslintignore
View File

@ -2,6 +2,7 @@ __fixtures__
dist
node_modules
build
coverage
jest.config.js
jest.transform.js
website-1.x/

1
.gitignore vendored
View File

@ -11,6 +11,7 @@ node_modules
yarn-error.log
build
coverage
.docusaurus
.cache-loader
types

1
.prettierignore
View File

@ -1,6 +1,7 @@
dist
node_modules
build
coverage
.docusaurus
packages/docusaurus-utils/lib/
packages/docusaurus/lib/

62
CHANGELOG-2.x.md
View File

@ -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

2
lerna.json
View File

@ -1,5 +1,5 @@
{
"version": "2.0.0-alpha.55",
"version": "2.0.0-alpha.56",
"npmClient": "yarn",
"useWorkspaces": true,
"changelog": {

2
package.json
View File

@ -94,6 +94,6 @@
}
},
"engines": {
"node": ">=10.9.0"
"node": ">=10.15.1"
}
}

2
packages/docusaurus-1.x/package.json
View File

@ -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",

2
packages/docusaurus-init-1.x/package.json
View File

@ -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": [

4
packages/docusaurus-init/package.json
View File

@ -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"
}
}

6
packages/docusaurus-init/templates/bootstrap/package.json
View File

@ -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"

6
packages/docusaurus-init/templates/classic/package.json
View File

@ -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"

6
packages/docusaurus-init/templates/facebook/package.json
View File

@ -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"

4
packages/docusaurus-mdx-loader/package.json
View File

@ -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"
}
}

2
packages/docusaurus-module-type-aliases/package.json
View File

@ -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": {

10
packages/docusaurus-plugin-content-blog/package.json
View File

@ -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"
}
}

10
packages/docusaurus-plugin-content-docs/package.json
View File

@ -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"
}
}

5
packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js
View File

@ -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'],
},

20
packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed-first-level.json Normal file
View File

@ -0,0 +1,20 @@
{
"docs": [
{
"type": "category",
"label": "Introduction",
"items": [
"doc1"
],
"collapsed": false
},
{
"type": "category",
"label": "Powering MDX",
"items": [
"doc2"
],
"collapsed": false
}
]
}

21
packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed.json Normal file
View File

@ -0,0 +1,21 @@
{
"docs": {
"Test": [
{
"type": "category",
"label": "Introduction",
"items": ["doc1"],
"collapsed": false
}
],
"Reference": [
{
"type": "category",
"label": "Powering MDX",
"items": ["doc2"],
"collapsed": false
}
]
}
}

14
packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
View File

@ -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",

80
packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/sidebars.test.ts.snap
View File

@ -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",

4
packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/version.test.ts.snap
View File

@ -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",

15
packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts
View File

@ -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();
});
});

9
packages/docusaurus-plugin-content-docs/src/sidebars.ts
View File

@ -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 {

3
packages/docusaurus-plugin-content-docs/src/types.ts
View File

@ -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;

8
packages/docusaurus-plugin-content-pages/package.json
View File

@ -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"
}
}

4
packages/docusaurus-plugin-google-analytics/package.json
View File

@ -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"
}
}

4
packages/docusaurus-plugin-google-gtag/package.json
View File

@ -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"
}
}

8
packages/docusaurus-plugin-ideal-image/package.json
View File

@ -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"
}
}

6
packages/docusaurus-plugin-sitemap/package.json
View File

@ -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"
}
}

12
packages/docusaurus-preset-bootstrap/package.json
View File

@ -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"
}
}

20
packages/docusaurus-preset-classic/package.json
View File

@ -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"
}
}

4
packages/docusaurus-theme-bootstrap/package.json
View File

@ -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"
}
}

2
packages/docusaurus-theme-classic/package-lock.json generated
View File

@ -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": {

6
packages/docusaurus-theme-classic/package.json
View File

@ -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"
}
}

38
packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js
View File

@ -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({
<a
className={classnames('menu__link', {
'menu__link--sublist': collapsible,
'menu__link--active': collapsible && !item.collapsed,
'menu__link--active':
collapsible &&
!item.collapsed &&
isCategoryOfActivePage(items, activePageRelativeUrl),
})}
href="#!"
onClick={collapsible ? handleItemClick : undefined}
@ -116,8 +142,18 @@ function mutateSidebarCollapsingState(item, path) {
items
.map((childItem) => 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;
}

10
packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.js
View File

@ -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;

4
packages/docusaurus-theme-classic/src/theme/hooks/useLogo.js
View File

@ -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) {

4
packages/docusaurus-theme-live-codeblock/package.json
View File

@ -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"
}
}

4
packages/docusaurus-theme-search-algolia/package.json
View File

@ -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"
}
}

2
packages/docusaurus-types/package.json
View File

@ -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",

1
packages/docusaurus-types/src/index.d.ts vendored
View File

@ -67,6 +67,7 @@ export interface BuildCLIOptions {
bundleAnalyzer: boolean;
outDir: string;
minify: boolean;
skipBuild: boolean;
}
export interface LoadContext {

4
packages/docusaurus-utils/package.json
View File

@ -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"
}
}

8
packages/docusaurus/bin/docusaurus.js
View File

@ -71,8 +71,12 @@ cli
'--out-dir <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

10
packages/docusaurus/package.json
View File

@ -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"
}
}

172
packages/docusaurus/src/commands/deploy.ts
View File

@ -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<BuildCLIOptions> = {},
): Promise<void> {
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);
}
}

4
packages/lqip-loader/package.json
View File

@ -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"
}
}

2
packages/stylelint-copyright/package.json
View File

@ -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",

4
website-1.x/package.json
View File

@ -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"
}
}

1
website/docs/cli.md
View File

@ -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. |

21
website/docs/docs.md
View File

@ -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".

2
website/docs/installation.md
View File

@ -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

12
website/package.json
View File

@ -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",

69
website/sidebars.js
View File

@ -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',

88
website/versioned_docs/version-2.0.0-alpha.43/cli.md
View File

@ -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:
<!-- TODO: init docs after the init command is implemented
### `docusaurus init`
The `docusaurus init` command is intended to be used with `docusaurus` installed globally:
```shell
$ yarn global add docusaurus
# or
$ npm install --global docusaurus
```
-->
### `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 <themeName> [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.
<!-- TODO a separate section for swizzle tutorial -->
To learn more about swizzling, check [here](#).
### `docusaurus deploy`
Deploys your site with [GitHub Pages](https://pages.github.com/).

148
website/versioned_docs/version-2.0.0-alpha.43/deployment.md
View File

@ -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=<GITHUB_USERNAME> yarn deploy
```
**Windows**
```batch
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
```
<!--
TODO: Talk about deployment steps and different hosting options.
References:
- https://www.gatsbyjs.org/docs/deploying-and-hosting/
-->
## 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.

151
website/versioned_docs/version-2.0.0-alpha.43/theme-classic.md
View File

@ -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',
},
...
},
};
```

39
website/versioned_docs/version-2.0.0-alpha.43/blog.md → website/versioned_docs/version-2.0.0-alpha.56/blog.md
View File

@ -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!
:::
<!--
Adding a blog using the blog plugin.

113
website/versioned_docs/version-2.0.0-alpha.56/cli.md Normal file
View File

@ -0,0 +1,113 @@
---
id: cli
title: CLI
---
Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.
Once your website is bootstrapped, the website source will contain the Docusaurus scripts that you can invoke with your package manager:
```json title="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:
<!-- TODO: init docs after the init command is implemented
### `docusaurus init`
The `docusaurus init` command is intended to be used with `docusaurus` installed globally:
```shell
$ yarn global add docusaurus
# or
$ npm install --global docusaurus
```
-->
### `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 <themeName> [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.
<!--
TODO a separate section for swizzle tutorial.
To learn more about swizzling, check [here](#).
-->
### `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. |

56
website/versioned_docs/version-2.0.0-alpha.43/configuration.md → website/versioned_docs/version-2.0.0-alpha.56/configuration.md
View File

@ -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 <div>{`${title} · ${tagline}`}</div>;
};
```
> 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`.
:::

10
website/versioned_docs/version-2.0.0-alpha.43/contributing.md → website/versioned_docs/version-2.0.0-alpha.56/contributing.md
View File

@ -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).

18
website/versioned_docs/version-2.0.0-alpha.43/creating-pages.md → website/versioned_docs/version-2.0.0-alpha.56/creating-pages.md
View File

@ -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
<!-- TODO: What will the user see if pages/ is empty? -->
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.

299
website/versioned_docs/version-2.0.0-alpha.56/deployment.md Normal file
View File

@ -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=<GITHUB_USERNAME> yarn deploy
```
**Windows**
```batch
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && 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 <<EOT >> ~/.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`.

6
website/versioned_docs/version-2.0.0-alpha.43/design-principles.md → website/versioned_docs/version-2.0.0-alpha.56/design-principles.md
View File

@ -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.

200
website/versioned_docs/version-2.0.0-alpha.43/sidebar.md → website/versioned_docs/version-2.0.0-alpha.56/docs.md
View File

@ -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).
:::

82
website/versioned_docs/version-2.0.0-alpha.43/docusaurus-core.md → website/versioned_docs/version-2.0.0-alpha.56/docusaurus-core.md
View File

@ -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
### `<Head/>`
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
</head>
```
## `Link`
### `<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 `<Link>` 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 `<NavLink>` component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s `<NavLink>` component.
The component is a wrapper around react-router’s `<Link>` component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s `<Link>` component.
```jsx {2,7}
import React from 'react';
@ -71,14 +73,14 @@ const Page = () => (
Check out my <Link to="/blog">blog</Link>!
</p>
<p>
{/* 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 <a href="https://twitter.com/docusaurus">Twitter</a>!
</p>
</div>
);
```
### `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`.
<Link to="/courses" />
```
### `activeClassName`: string
### `<Redirect/>`
The class to give the `<Link>` when it is active. The default given class is `active`. This will be joined with the `className` prop.
Rendering a `<Redirect>` 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}
<Link to="/faq" activeClassName="selected">
FAQs
</Link>
Example usage:
```jsx {2,5}
import React from 'react';
import {Redirect} from '@docusaurus/router';
function Home() {
return <Redirect to="/docs/test" />;
}
```
## `useDocusaurusContext`
### `<BrowserOnly/>`
React Hooks to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](docusaurus.config.js.md).
The `<BrowserOnly>` 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 (
<BrowserOnly
fallback={<div>The fallback content to display on prerendering</div>}>
{() => {
// Something that should be excluded during build process prerendering.
}}
</BrowserOnly>
);
}
```
## 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 `<Redirect>` 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 <Redirect to="/docs/test" />;
function MyPage() {
const location = ExecutionEnvironment.canUseDOM ? window.href.location : null;
return <div>{location}</div>;
}
```
| 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`. |

79
website/versioned_docs/version-2.0.0-alpha.43/docusaurus.config.js.md → website/versioned_docs/version-2.0.0-alpha.56/docusaurus.config.js.md
View File

@ -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 `<script>` added here are render-blocking so you might want to add `as
Example:
```js
// docusaurus.config.js
```js title="docusaurus.config.js"
module.exports = {
scripts: [
// String format.
@ -288,8 +274,7 @@ An array of CSS sources to load. The values can be either strings or plain objec
Example:
```js
// docusaurus.config.js
```js title="docusaurus.config.js"
module.exports = {
stylesheets: [
// String format.

47
website/versioned_docs/version-2.0.0-alpha.43/installation.md → website/versioned_docs/version-2.0.0-alpha.56/installation.md
View File

@ -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
@ -26,7 +26,7 @@ npx @docusaurus/init@next init my-website classic
If you do not specify `name` or `template`, it will prompt you for them. We recommend the `classic` template so that you can get started quickly and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.
**Important Note:** If you are setting up a new Docusaurus website for a Facebook open source project, use the `facebook` template instead, which comes with some useful Facebook-specific defaults:
**[FB-Only]:** If you are setting up a new Docusaurus website for a Facebook open source project, use the `facebook` template instead, which comes with some useful Facebook-specific defaults:
```bash
npx @docusaurus/init@next init my-website facebook
@ -47,7 +47,6 @@ my-website
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── package.json
├── src
│ ├── css
│ │ └── custom.css
@ -65,8 +64,8 @@ my-website
### Project structure rundown
- `/blog/` - Contains the blog markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md).
- `/docs/` - Contains the markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](markdown-features.mdx).
- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md).
- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](markdown-features.mdx).
- `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
- `/src/pages` - Any files within this directory will be converted into a website page. More details can be found in the [pages guide](creating-pages.md).
- `/static/` - Static directory. Any contents inside here will be copied into the root of the final `build` directory.
@ -97,6 +96,44 @@ npm run build
and contents will be generated within the `/build` directory, which can be copied to any static file hosting service like [GitHub pages](https://pages.github.com/), [Now](https://zeit.co/now) or [Netlify](https://www.netlify.com/). Check out the docs on [deployment](deployment.md) for more details.
## Updating your Docusaurus version
There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in `package.json` to the desired version. Note that all `@docusaurus/`-namespaced packages should be using the same version.
:::important
Please update to the latest Docusaurus 2 version shown at the top of the page, not what is shown below.
:::
```json title="package.json"
"dependencies": {
"@docusaurus/core": "^2.0.0-alpha.49",
"@docusaurus/preset-classic": "^2.0.0-alpha.49",
// ...
}
```
Then, in the directory containing `package.json`, run your package manager's install command:
```bash npm2yarn
npm install
```
To check that that the update occurred successfully, run:
```bash npm2yarn
npm docusaurus --version
```
You should see the correct version as output.
Alternatively, if you are using Yarn, you can do:
```bash
yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49
```
## Problems?
Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/docusaurus), on our [GitHub repository](https://github.com/facebook/docusaurus) or [Twitter](https://twitter.com/docusaurus).

49
website/versioned_docs/version-2.0.0-alpha.43/introduction.md → website/versioned_docs/version-2.0.0-alpha.56/introduction.md
View File

@ -4,34 +4,35 @@ title: Introduction
description: Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.
---
import useBaseUrl from '@docusaurus/useBaseUrl';
## Disclaimer
## :warning: Disclaimer
It has been a year since we made the first **alpha release** of Docusaurus 2 and things have been pretty stable since then. Many of Facebook's new open source websites are using Docusaurus 2 now. At this point, we highly encourage you to use Docusaurus 2 over Docusaurus 1 for your new websites. For feedback and questions, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink:
This is an **early and alpha release** of Docusaurus 2. We are making it available early to maximize community participation and feedback. Expect it to evolve a lot over the course of the alpha-beta period. If you are adventurous enough to be an early adopter, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink:.
**You should use this if**
**You should use this if:**
- :white_check_mark: You want to contribute to Docusaurus 2
- :white_check_mark: You want to provide feedback to make sure it suits your needs
- :white_check_mark: You are curious about what's next as a Docusaurus user
- :white_check_mark: You want to build a modern website with client-side routing and prerendering
- :white_check_mark: You want to provide feedback to make sure Docusaurus 2 suits your needs
- :white_check_mark: You are curious about what comes next as a Docusaurus user
- :white_check_mark: You want to ease the pain of migration in future
- :white_check_mark: You do not need support for IE11
**Do not use this if**
**Do not use this if:**
- :x: You need a full production-ready solution (<small>try [Docusaurus 1](https://docusaurus.io/) instead</small>)
- :x: You need a fully production-ready solution (try [Docusaurus 1](https://docusaurus.io/) instead)
- :x: You need the translation features present in v1
- :x: You prefer not to work with potential breaking changes and/or features not yet working properly as we improve it during alpha period
- :x: You prefer not to work with potential breaking changes and/or features not yet working properly as we improve it during the alpha period
- :x: You need support for IE11
## A better Docusaurus is coming to town
<img alt="Docusaurus " src={useBaseUrl('img/slash-introducing.svg')} />
<img alt="Docusaurus " src={require('@docusaurus/useBaseUrl').default('img/slash-introducing.svg')} />
Docusaurus 1 used to be a pure documentation site generator. In Docusaurus 2, we rebuilt it from the ground up, allowing for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n (_coming soon_).
Beyond that, Docusaurus 2 is a **performant static site generator** and can be used to create most content-driven websites (e.g. Documentation, Blogs, Product Landing and Marketing Pages, etc) extremely fast.
Beyond that, Docusaurus 2 is a **performant static site generator** and can be used to create common content-driven websites (e.g. Documentation, Blogs, Product Landing and Marketing Pages, etc) extremely quickly.
While our main focus will still be helping you get your documentations right and well, the shared nature of building this static site generator makes it possible for you to build your whole website interface one-stop.
While our main focus will still be helping you get your documentations right and well, it is possible to build this any kind of website using Docusaurus 2 as it is just a React application. **Docusaurus can now be used to build any website, not just documentation websites.**
## Features
@ -40,9 +41,9 @@ Docusaurus is built with high attention to your experience building your site an
- ⚛️ **Built with 💚 and React**
- Extend and customize with React
- Gain full control of your site's browsing experience by `swizzling` in your own components
- 🔌 **Pluggable**
- Bootstrap your site with a basic template, then pick and plug functionalities built by us and our community.
- Open source your plugins to share with your fellow documentarians, because sharing is caring.
- **Pluggable**
- Bootstrap your site with a basic template, then pick and plug functionalities built by us and our community
- Open source your plugins to share with your fellow documentarians, because sharing is caring
- ✂️ **Developer experience**
- Multiple bootstrapping templates to get your site up and running, start writing your docs right now
- Universal configuration entry point to make it more maintainable by contributors
@ -58,14 +59,14 @@ Our shared goal — to help your users find what they need fast, and understand
- 📝 **Powered by MDX**
- Write interactive components via JSX and React embedded in markdown
- Share your code in live editors to get your users love your products on the spot
- 🔍 **Search** Your full site is searchable
- 🔍 **Search** - Your full site is searchable
- 💾 **Document Versioning** - Helps you keep documentation in sync with project releases.
- 🌍 **i18n** (_coming soon_)
- 💾 **Document Versioning** Helps you keep documentation in sync with project releases.
Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast.
- ⚡️ **Lightning fast** Docusaurus 2 follows [The PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast
- 🦖 **Accessible** Attention to accessibility, making your site equally accessible to all users
- ⚡️ **Lightning fast** - Docusaurus 2 follows the [PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast
- 🦖 **Accessible** - Attention to accessibility, making your site equally accessible to all users
## Comparison with other tools
@ -83,19 +84,19 @@ Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and i
### GitBook
Gitbook has very clean slate design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's doc site. As a result, many have to turn to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161).
GitBook has very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's documentation site. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161).
Currently, Gitbook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
### Jekyll
Jekyll is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with Jekyll.
In comparison with statically generated HTML and interactivity based on `<script />` tags, Docusaurus sites are React apps. With tooling of our current ecosystem, we hope to set new standards on doc sites performance, asset build pipeline and optimizations, and ease to setup.
In comparison with statically generated HTML and interactivity added using `<script />` tags, Docusaurus sites are React apps. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites performance, asset build pipeline and optimizations, and ease to setup.
### VuePress
VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you wanted a Vue-based solution, VuePress would be a decent choice.
VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice.
<!-- TODO: Add a Next.js comparison -->

73
website/versioned_docs/version-2.0.0-alpha.43/lifecycle-apis.md → website/versioned_docs/version-2.0.0-alpha.56/lifecycle-apis.md
View File

@ -3,7 +3,11 @@ id: lifecycle-apis
title: Lifecycle APIs
---
> :warning: _This section is a work in progress._
:::caution
This section is a work in progress.
:::
Lifecycle APIs are shared by Themes and Plugins.
@ -13,8 +17,7 @@ Specifies the paths to watch for plugins and themes. The paths are watched by th
Example:
```js {6-8}
// docusaurus-plugin/src/index.js
```js {5-7} title="docusaurus-plugin/src/index.js"
const path = require('path');
module.exports = function (context, options) {
return {
@ -33,8 +36,7 @@ Plugins should use this lifecycle to fetch from data sources (filesystem, remote
For example, this plugin below return a random integer between 1 to 10 as content;
```js {6-7}
// docusaurus-plugin/src/index.js
```js {5-6} title="docusaurus-plugin/src/index.js"
const path = require('path');
module.exports = function (context, options) {
return {
@ -50,6 +52,10 @@ module.exports = function (context, options) {
Plugins should use the data loaded in `loadContent` and construct the pages/routes that consume the loaded data (optional).
## `async routesLoaded(routes)`
Plugins can modify the routes that were generated by all plugins. `routesLoaded` is called after `contentLoaded` hook.
### `content`
`contentLoaded` will be called _after_ `loadContent` is done, the return value of `loadContent()` will be passed to `contentLoaded` as `content`.
@ -89,8 +95,7 @@ A helper function to help you write some data (usually a string or JSON) to disk
For example, this plugin below create a `/roll` page which display "You won xxxx" to user.
```jsx
// website/src/components/roll.js
```jsx title="website/src/components/roll.js"
import React from 'react';
export default function (props) {
@ -100,19 +105,18 @@ export default function (props) {
}
```
```javascript {5-20}
// docusaurus-plugin/src/index.js
```javascript {4-19} title="docusaurus-plugin/src/index.js"
module.exports = function(context, options) {
return {
name: 'docusaurus-plugin',
async contentLoaded({content, actions}) {
const {createData, addRoute} = actions;
// create a data named 'prizes.json'
// Create a data named 'prizes.json'.
const prizes = JSON.stringify(['$1', 'a cybertruck', 'nothing']);
const prizesDataPath = await createData('prizes.json', prizes);
// add '/roll' page using 'website/src/component/roll.js` as the component
// and providing 'prizes' as props
// Add '/roll' page using 'website/src/component/roll.js` as the component
// and providing 'prizes' as props.
addRoute({
path: '/roll',
component: '@site/src/components/roll.js',
@ -150,8 +154,7 @@ You may use them to return your webpack configures conditionally.
For example, this plugin below modify the webpack config to transpile `.foo` file.
```js {5-12}
// docusaurus-plugin/src/index.js
```js {4-11} title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'custom-docusaurus-plugin',
@ -193,13 +196,12 @@ type Props = {
Example:
```js {5-10}
// docusaurus-plugin/src/index.js
```js {4-9} title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
// Print out to console all the rendered routes
// Print out to console all the rendered routes.
routesPaths.map((route) => {
console.log(route);
});
@ -214,8 +216,7 @@ Register an extra command to enhance the CLI of docusaurus. `cli` is [commander]
Example:
```js {5-12}
// docusaurus-plugin/src/index.js
```js {4-11} title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
@ -233,7 +234,7 @@ module.exports = function (context, options) {
## `injectHtmlTags()`
Inject head and/or body html tags to Docusaurus generated html.
Inject head and/or body HTML tags to Docusaurus generated HTML.
```typescript
function injectHtmlTags(): {
@ -246,7 +247,7 @@ type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];
interface HtmlTagObject {
/**
* Attributes of the html tag
* Attributes of the HTML tag
* E.g. `{'disabled': true, 'value': 'demo', 'rel': 'preconnect'}`
*/
attributes?: {
@ -265,8 +266,7 @@ interface HtmlTagObject {
Example:
```js {5-29}
// docusaurus-plugin/src/index.js
```js {4-28} title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
@ -303,8 +303,7 @@ Returns the path to the directory where the theme components can be found. When
If you use the folder directory above, your `getThemePath` can be:
```js {7-9}
// my-theme/src/index.js
```js {6-8} title="my-theme/src/index.js"
const path = require('path');
module.exports = function (context, options) {
@ -323,8 +322,7 @@ Returns an array of paths to the modules that are to be imported in the client b
As an example, to make your theme load a `customCss` object from `options` passed in by the user:
```js {8-10}
// my-theme/src/index.js
```js {7-9} title="my-theme/src/index.js"
const path = require('path');
module.exports = function (context, options) {
@ -370,17 +368,22 @@ module.exports = function (context, opts) {
name: 'docusaurus-my-project-cool-plugin',
async loadContent() {
// The loadContent hook is executed after siteConfig and env has been loaded
// You can return a JavaScript object that will be passed to contentLoaded hook
// The loadContent hook is executed after siteConfig and env has been loaded.
// You can return a JavaScript object that will be passed to contentLoaded hook.
},
async contentLoaded({content, actions}) {
// contentLoaded hook is done after loadContent hook is done
// actions are set of functional API provided by Docusaurus. e.g: addRoute
// The contentLoaded hook is done after loadContent hook is done.
// `actions` are set of functional API provided by Docusaurus (e.g. addRoute)
},
async routesLoaded(routes) {
// The routesLoaded hook is done after contentLoaded hook is done.
// This can be useful if you need to change any route.
},
async postBuild(props) {
// after docusaurus <build> finish
// After docusaurus <build> finish.
},
// TODO
@ -405,7 +408,7 @@ module.exports = function (context, opts) {
},
getPathsToWatch() {
// Path to watch
// Paths to watch.
},
getThemePath() {
@ -420,11 +423,11 @@ module.exports = function (context, opts) {
},
extendCli(cli) {
// Register an extra command to enhance the CLI of docusaurus
// Register an extra command to enhance the CLI of Docusaurus
},
injectHtmlTags() {
// Inject head and/or body html tags
// Inject head and/or body HTML tags.
},
};
};

441
website/versioned_docs/version-2.0.0-alpha.43/markdown-features.mdx → website/versioned_docs/version-2.0.0-alpha.56/markdown-features.mdx
View File

@ -4,12 +4,6 @@ title: Markdown Features
description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown.
---
<!--
combining:
- assets
- markdown features
-->
Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.
Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
@ -17,7 +11,9 @@ Docusaurus 2 uses modern tooling to help you compose your interactive documentat
In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example.
:::important
All the following content assumes you are using `@docusaurus/preset-classic`.
All the following content assumes you are using `@docusaurus/preset-classic` or `@docusaurus/plugin-content-docs`.
:::
---
@ -38,7 +34,7 @@ website # root directory of your site
<!-- TODO: talk about where to put the docs, resolving docs outside of website directory, etc. -->
In the top of the file, specify `id` the `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.
At the top of the file, specify `id` and `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.
```yml
---
@ -72,6 +68,7 @@ This will render in the browser as follows:
import BrowserWindow from '@site/src/components/BrowserWindow';
<BrowserWindow url="http://localhost:3000">
<h2>Hello from Docusaurus</h2>
Are you ready to create the documentation site for your open source project?
@ -94,7 +91,7 @@ The headers are well-spaced so that the hierarchy is clear.
</BrowserWindow>
### Markdown Headers
## Markdown headers
Documents use the following markdown header fields that are enclosed by a line `---` on either side:
@ -124,15 +121,30 @@ keywords:
- docusaurus
image: https://i.imgur.com/mErPwqL.png
---
```
### Embedding React components
## Referencing other documents
Docusaurus has built-in support for [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown files and render them as React components.
If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`:
```md
I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md).
[Relative document](../doc2.md) referencing works as well.
```
One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.
## Embedding React components with MDX
Docusaurus has built-in support for [MDX](https://mdxjs.com/), which allows you to write JSX within your Markdown files and render them as React components.
**Note 1:** While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax. Let's rename the previous file to `greeting.mdx`.
**Note 2:** Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](./migrating-from-v1-to-v2.md#convert-style-attributes-to-style-objects-in-mdx).
**Note 2:** Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](migrating-from-v1-to-v2.md#convert-style-attributes-to-style-objects-in-mdx).
Try this block here:
@ -169,7 +181,9 @@ export const Highlight = ({children, color}) => (
);
<BrowserWindow minHeight={240} url="http://localhost:3000">
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
<Highlight color="#25c2a0">Docusaurus green</Highlight>
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
@ -179,18 +193,302 @@ I can write **Markdown** alongside my _JSX_!
You can also import your own components defined in other files or third-party components installed via npm! Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
### Referencing other documents
### Configuring plugins
If you want to reference another document file, you should use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
You can expand the MDX functionalities, using plugins. An MDX plugin is usually a npm package, so you install them like other npm packages using npm. Docusaurus supports both [Remark](https://github.com/remarkjs/remark) and [Rehype](https://github.com/rehypejs/rehype) plugins that work with MDX.
For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`:
First, install your [Remark](https://github.com/remarkjs/remark/blob/master/doc/plugins.md#list-of-plugins) and [Rehype](https://github.com/rehypejs/rehype/blob/master/doc/plugins.md#list-of-plugins) plugins.
```md
I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md)
[Relative document](../doc2.md) referencing works as well.
For example:
```bash npm2yarn
npm install --save remark-images
npm install --save rehype-truncate
```
One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.
Next, import the plugins:
```js
const remarkImages = require('remark-images');
const rehypeTruncate = require('rehype-truncate');
```
Finally, add them to the `@docusaurus/preset-classic` options in `docusaurus.config.js`:
```js {10,11} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
// ...
remarkPlugins: [remarkImages],
rehypePlugins: [rehypeTruncate],
},
},
],
],
};
```
### Configuring plugin options
Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like so:
```jsx {10-13} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
// ...
remarkPlugins: [
plugin1,
[plugin2, {option1: {...}}],
],
},
},
],
],
};
```
See more information in the [MDX documentation](https://mdxjs.com/advanced/plugins).
## Tabs
To show tabbed content within Markdown files, you can fall back on MDX. Docusaurus provides `<Tabs>` components out-of-the-box.
```jsx
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs
defaultValue="apple"
values={[
{label: 'Apple', value: 'apple'},
{label: 'Orange', value: 'orange'},
{label: 'Banana', value: 'banana'},
]}>
<TabItem value="apple">This is an apple 🍎</TabItem>
<TabItem value="orange">This is an orange 🍊</TabItem>
<TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs>;
```
will result in
<Tabs
defaultValue="apple"
values={[
{label: 'Apple', value: 'apple'},
{label: 'Orange', value: 'orange'},
{label: 'Banana', value: 'banana'},
]}>
<TabItem value="apple">This is an apple 🍎</TabItem>
<TabItem value="orange">This is an orange 🍊</TabItem>
<TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs>
### Syncing tab choices
You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and all `<Tab>` instances with the same `groupId` will update automatically when the value of one of them is changed. Not that `groupID` are globally-namespaced.
```jsx {2,14}
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]
}>
<TabItem value="win">Use Ctrl + C to copy.</TabItem>
<TabItem value="mac">Use Command + C to copy.</TabItem>
</Tabs>
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]
}>
<TabItem value="win">Use Ctrl + V to paste.</TabItem>
<TabItem value="mac">Use Command + V to paste.</TabItem>
</Tabs>
```
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]}>
<TabItem value="win">Use Ctrl + C to copy.</TabItem>
<TabItem value="mac">Use Command + C to copy.</TabItem>
</Tabs>
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]}>
<TabItem value="win">Use Ctrl + V to paste.</TabItem>
<TabItem value="mac">Use Command + V to paste.</TabItem>
</Tabs>
---
Tab choices with different `groupId`s will not interfere with each other:
```jsx {2,14}
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]
}>
<TabItem value="win">Windows in windows.</TabItem>
<TabItem value="mac">macOS is macOS.</TabItem>
</Tabs>
<Tabs
groupId="non-mac-operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'Unix', value: 'unix'},
]
}>
<TabItem value="win">Windows is windows.</TabItem>
<TabItem value="unix">Unix is unix.</TabItem>
</Tabs>
```
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]}>
<TabItem value="win">Windows in windows.</TabItem>
<TabItem value="mac">macOS is macOS.</TabItem>
</Tabs>
<Tabs
groupId="non-mac-operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'Unix', value: 'unix'},
]}>
<TabItem value="win">Windows is windows.</TabItem>
<TabItem value="unix">Unix is unix.</TabItem>
</Tabs>
## Callouts/admonitions
In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons.
Example:
:::note
The content and title *can* include markdown.
:::
:::tip You can specify an optional title
Heads up! Here's a pro-tip.
:::
:::info
Useful information.
:::
:::caution
Warning! You better pay attention!
:::
:::danger
Danger danger, mayday!
:::
:::note
The content and title _can_ include markdown.
:::
:::tip You can specify an optional title
Heads up! Here's a pro-tip.
:::
:::info
Useful information.
:::
:::caution
Warning! You better pay attention!
:::
:::danger
Danger danger, mayday!
:::
### Specifying title
You may also specify an optional title
:::note Your Title
The content and title *can* include markdown.
:::
:::note Your Title
The content and title _can_ include Markdown.
:::
## Code blocks
Code blocks within documentation are super-powered 💪.
### Code title
You can add a title to the code block by adding `title` key after the language (leave a space between them).
```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
```
```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
```
### Syntax highlighting
@ -212,8 +510,7 @@ By default, the Prism [syntax highlighting theme](https://github.com/FormidableL
For example, if you prefer to use the `dracula` highlighting theme:
```js {4}
// docusaurus.config.js
```js {4} title="docusaurus.config.js"
module.exports = {
themeConfig: {
prism: {
@ -225,15 +522,20 @@ module.exports = {
By default, Docusaurus comes with this subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js).
To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages), install the `prismjs` npm package, then swizzle the `CodeBlock` component and add the desired language(s) there.
To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages), define it in an array of additional languages.
For example, if you want to add highlighting for the `powershell` language:
```js
// src/theme/CodeBlock/index.js
import Prism from 'prism-react-renderer/prism';
(typeof global !== 'undefined' ? global : window).Prism = Prism;
require('prismjs/components/prism-powershell');
```js {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
prism: {
additionalLanguages: ['powershell'],
},
// ...
},
};
```
### Line highlighting
@ -262,8 +564,7 @@ function HighlightSomeText(highlight) {
To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.
```css
/* /src/css/custom.css */
```css title="/src/css/custom.css"
.docusaurus-highlight-code-line {
background-color: rgb(72, 77, 91);
display: block;
@ -273,7 +574,7 @@ To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class t
/* If you have a different syntax highlighting theme for dark mode. */
html[data-theme='dark'] .docusaurus-highlight-code-line {
background-color: /* Color which works with dark mode syntax highlighting theme */
background-color: ; /* Color which works with dark mode syntax highlighting theme */
}
```
@ -307,6 +608,61 @@ function MyComponent(props) {
export default MyComponent;
```
You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
```jsx
function HighlightSomeText(highlight) {
if (highlight) {
// highlight-next-line
return 'This text is highlighted!';
}
return 'Nothing highlighted';
}
function HighlightMoreText(highlight) {
// highlight-start
if (highlight) {
return 'This range is highlighted!';
}
// highlight-end
return 'Nothing highlighted';
}
```
```jsx
function HighlightSomeText(highlight) {
if (highlight) {
// highlight-next-line
return 'This text is highlighted!';
}
return 'Nothing highlighted';
}
function HighlightMoreText(highlight) {
// highlight-start
if (highlight) {
return 'This range is highlighted!';
}
// highlight-end
return 'Nothing highlighted';
}
```
Supported commenting syntax:
| Language | Syntax |
| ---------- | ------------------------ |
| JavaScript | `/* ... */` and `// ...` |
| JSX | `{/* ... */}` |
| Python | `# ...` |
| HTML | `<!-- ... -->` |
If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
### Interactive code editor
(Powered by [React Live](https://github.com/FormidableLabs/react-live))
@ -323,10 +679,10 @@ You will also need to add the plugin to your `docusaurus.config.js`.
```js {3}
module.exports = {
...
// ...
themes: ['@docusaurus/theme-live-codeblock'],
...
}
// ...
};
```
To use the plugin, create a code block with `live` attached to the language meta string.
@ -470,19 +826,4 @@ class HelloWorld {
You may want to implement your own `<MultiLanguageCode />` abstraction if you find the above approach too verbose. We might just implement one in future for convenience.
### Callouts/admonitions
In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions.
Admonitions are wrapped by a set of 3 colons.
Example:
```markdown
:::tip Title
The content and title *can* include markdown.
:::
```
:::tip Title
The content and title *can* include markdown.
:::
If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the [Syncing tab choices section](#syncing-tab-choices).

139
website/versioned_docs/version-2.0.0-alpha.43/migrating-from-v1-to-v2.md → website/versioned_docs/version-2.0.0-alpha.56/migrating-from-v1-to-v2.md
View File

@ -5,9 +5,13 @@ title: Migrating from v1 to v2
import ColorGenerator from '@site/src/components/ColorGenerator';
This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.
:::caution
**Note: This migration guide is targeted at Docusaurus users without translation and/or versioning features and assumes the following structure:**
This migration guide is targeted at Docusaurus users without translation and/or versioning features.
:::
This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2. Your Docusaurus 1 site should have the following structure:
```sh
├── docs
@ -36,38 +40,43 @@ This provides a clear distinction between Docusaurus' official packages and comm
Meanwhile, the default doc site functionalities provided by Docusaurus 1 are now provided by `@docusaurus/preset-classic`. Therefore, we need to add this dependency as well:
```json
// package.json
```diff title="package.json"
{
dependencies: {
- "docusaurus": "^1.x.x",
+ "@docusaurus/core": "^2.0.0-alpha.48",
+ "@docusaurus/preset-classic": "^2.0.0-alpha.48",
- "docusaurus": "^1.x.x",
+ "@docusaurus/core": "^2.0.0-alpha.48",
+ "@docusaurus/preset-classic": "^2.0.0-alpha.48",
}
}
```
:::tip
Please use the most recent Docusaurus 2 alpha version, which you can check out [here](https://www.npmjs.com/package/@docusaurus/core) (it's tagged `next`).
:::
#### CLI commands
Meanwhile, CLI commands are renamed to `docusaurus <command>` (instead of `docusaurus-command`).
The `"scripts"` section of your `package.json` should be updated as follows:
```json {3-6}
```json {3-6} title="package.json"
{
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy"
...
// ...
}
}
```
A typical Docusaurus 2 `package.json` may look like this:
```json
```json title="package.json"
{
"scripts": {
"start": "docusaurus start",
@ -103,7 +112,7 @@ If you are deploying to GitHub pages, make sure to run `yarn deploy` instead of
The `.gitignore` in your `website` should contain:
```
```bash title=".gitignore"
# dependencies
/node_modules
@ -134,8 +143,7 @@ Rename `siteConfig.js` to `docusaurus.config.js`. In Docusaurus 2, we split each
Add the following preset configuration to your `docusaurus.config.js`.
```jsx
// docusaurus.config.js
```jsx title="docusaurus.config.js"
module.exports = {
// ...
presets: [
@ -143,12 +151,12 @@ module.exports = {
'@docusaurus/preset-classic',
{
docs: {
// docs folder path relative to website dir.
// Docs folder path relative to website dir.
path: '../docs',
// sidebars file relative to website dir.
// Sidebars file relative to website dir.
sidebarPath: require.resolve('./sidebars.json'),
},
...
// ...
},
],
],
@ -169,8 +177,7 @@ No actions needed.
Deprecated. We wrote a custom CSS framework for Docusaurus 2 called Infima which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. `./src/css/custom.css`) and import it globally by passing it as an option to `@docusaurus/preset-classic`:
```js {8-10}
// docusaurus.config.js
```js {7-9} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
@ -188,9 +195,8 @@ module.exports = {
Infima uses 7 shades of each color.
```css
```css title="/src/css/custom.css"
/**
* /src/css/custom.css
* You can override the default Infima variables here.
* Note: this is not a complete list of --ifm- variables.
*/
@ -215,8 +221,7 @@ Alteratively, use the following tool to generate the different shades for your w
Site meta info such as assets, SEO, copyright info are now handled by themes. To customize them, use the `themeConfig` field in your `docusaurus.config.js`:
```jsx
// docusaurus.config.js
```jsx title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
@ -226,10 +231,10 @@ module.exports = {
src: 'https://docusaurus.io/img/oss_logo.png',
href: 'https://opensource.facebook.com/',
},
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here.
},
image: 'img/docusaurus.png',
// Equivalent to `docsSideNavCollapsible`
// Equivalent to `docsSideNavCollapsible`.
sidebarCollapsible: false,
// ...
},
@ -240,7 +245,7 @@ module.exports = {
In Docusaurus 1, header icon and header links were root fields in `siteConfig`:
```js
```js title="siteConfig.js"
headerIcon: 'img/docusaurus.svg',
headerLinks: [
{ doc: "doc1", label: "Getting Started" },
@ -252,8 +257,7 @@ headerLinks: [
Now, these two fields are both handled by the theme:
```jsx {7-20}
// docusaurus.config.js
```jsx {6-19} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
@ -281,15 +285,14 @@ module.exports = {
#### `algolia`
```jsx {5-9}
// docusaurus.config.js
```jsx {4-8} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
algolia: {
apiKey: '47ecd3b21be71c5822571b9f59e52544',
indexName: 'docusaurus-2',
algoliaOptions: { ... },
algoliaOptions: { //... },
},
// ...
},
@ -300,8 +303,7 @@ module.exports = {
Deprecated. Pass it as a blog option to `@docusaurus/preset-classic` instead:
```jsx {9}
// docusaurus.config.js
```jsx {8} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
@ -328,8 +330,7 @@ Deprecated. Create a `CNAME` file in your `static` folder instead with your cust
Deprecated. Pass it as an option to `@docusaurus/preset-classic` docs instead:
```jsx {9-22}
// docusaurus.config.js
```jsx {8-20} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
@ -339,7 +340,7 @@ module.exports = {
docs: {
// Equivalent to `customDocsPath`.
path: 'docs',
// Equivalent to `editUrl` but should point to `website` dir instead of `website/docs`
// Equivalent to `editUrl` but should point to `website` dir instead of `website/docs`.
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website',
// Equivalent to `docsUrl`.
routeBasePath: 'docs',
@ -360,8 +361,7 @@ module.exports = {
#### `gaTrackingId`
```jsx {6}
// docusaurus.config.js
```jsx {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
@ -375,8 +375,7 @@ module.exports = {
#### `gaGtag`
```jsx {6}
// docusaurus.config.js
```jsx {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
@ -425,11 +424,11 @@ We intend to implement many of the deprecated config fields as plugins in future
### Sidebar
In previous version, nested sidebar category is not allowed and sidebar category can only contain doc id. However, v2 allows infinite nested sidebar and we have many types of [Sidebar Item](sidebar.md#sidebar-item) other than document.
In previous version, nested sidebar category is not allowed and sidebar category can only contain doc id. However, v2 allows infinite nested sidebar and we have many types of [Sidebar Item](docs.md#sidebar-item) other than document.
You'll have to migrate your sidebar if it contains category type. Rename `subcategory` to `category` and `ids` to `items`.
```js
```diff title="sidebars.json"
{
- type: 'subcategory',
+ type: 'category',
@ -441,7 +440,7 @@ You'll have to migrate your sidebar if it contains category type. Rename `subcat
### Footer
`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it:
`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it:
```bash npm2yarn
npm run swizzle @docusaurus/theme-classic Footer
@ -455,9 +454,10 @@ Please refer to [creating pages](creating-pages.md) to learn how Docusaurus 2 pa
`CompLibrary` is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website or view https://facebookincubator.github.io/infima/ to see what styles are available).
- The following code could be helpful for migration of various pages
- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js),
- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js), [Flux](http://facebook.github.io/flux/support)
The following code could be helpful for migration of various pages:
- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js/) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js/), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js/)
- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js/), [Flux](http://facebook.github.io/flux/support)
## Content
@ -471,13 +471,13 @@ In Docusaurus 2, the markdown syntax has been changed to [MDX](https://mdxjs.com
**Tips**: You might want to use some online tools like [HTML to JSX](https://transform.tools/html-to-jsx) to make the migration easier.
### Language-specific Code Tabs
### Language-specific code tabs
Refer to the [multi-language support code blocks](markdown-features.mdx#multi-language-support-code-blocks) section.
### Frontmatter
### Front matter
The Docusaurus frontmatter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `author_image_url` field.
@ -502,7 +502,7 @@ my-project
└── static
```
Start the development server and fix any errors
Start the development server and fix any errors:
```bash
cd website
@ -519,19 +519,21 @@ For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord ch
## Versioned Site
> :warning: _This section is a work in progress._
:::caution
> ⚠️ Although we've implemented docs versioning since 2.0.0-alpha.37, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work.
The versioning feature is a work in progress! Although we've implemented docs versioning since `2.0.0-alpha.37`, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work.
:::
## Changes from v1
- Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for reasoning on v1's problem
Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.
### Migrate your versioned_docs frontmatter
### Migrate your `versioned_docs` front matter
- Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation.
Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation.
Example, you have a `docs/hello.md`.
For example, if you have a `docs/hello.md`.
```md
---
@ -542,9 +544,7 @@ title: Hello, World !
Hi, Endilie here :)
```
When you cut a new version 1.0.0
In Docusaurus v1, `website/versioned_docs/version-1.0.0/hello.md` looks like this
When you cut a new version 1.0.0, in Docusaurus v1, `website/versioned_docs/version-1.0.0/hello.md` looks like this:
```md
---
@ -571,7 +571,7 @@ Since we're going for snapshot and allow people to move (and edit) docs easily i
Essentially, here are the necessary changes in each versioned_docs file:
```yaml {2-3,5}
```diff {2-3,5}
---
- id: version-1.0.0-hello
+ id: hello
@ -581,13 +581,13 @@ title: Hello, World !
Hi, Endilie here :)
```
### Migrate your versioned_sidebars
### Migrate your `versioned_sidebars`
- Refer to versioned_docs id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1).
- Refer to `versioned_docs` id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1).
Because in v1 there is a good chance someone created a new file with front matter id `"version-${version}-${id}"` that can conflict with versioned_docs id.
Because in v1 there is a good chance someone created a new file with front matter id `"version-${version}-${id}"` that can conflict with `versioned_docs` id.
Example, Docusaurus 1 can't differentiate `docs/xxx.md`
For example, Docusaurus 1 can't differentiate `docs/xxx.md`
```md
---
@ -597,7 +597,7 @@ id: version-1.0.0-hello
Another content
```
and `website/versioned_docs/version-1.0.0/hello.md`
vs `website/versioned_docs/version-1.0.0/hello.md`
```md
---
@ -615,7 +615,7 @@ So v1 users need to migrate their versioned_sidebars file
Example `versioned_sidebars/version-1.0.0-sidebars.json`:
```json {2-3,5-6,9-10}
```diff {2-3,5-6,9-10} title="versioned_sidebars/version-1.0.0-sidebars.json"
{
+ "version-1.0.0/docs": {
- "version-1.0.0-docs": {
@ -631,14 +631,13 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`:
}
```
### Populate your versioned_sidebars & versioned_docs
### Populate your `versioned_sidebars` and `versioned_docs`
In v2, we use snapshot approach on documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality).
In v2, we use snapshot approach for documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality).
For example, if your `versions.json` looks like this in v1
```json
// versions.json
```json title="versions.json"
["1.1.0", "1.0.0"]
```
@ -657,7 +656,7 @@ website
│ └── version-1.0.0-sidebars.json
```
In v2, you have to populate the missing versioned_docs & versioned_sidebars (with the right frontmatter and id reference too).
In v2, you have to populate the missing `versioned_docs` and `versioned_sidebars` (with the right frontmatter and id reference too).
```shell {3-5,12}
website

49
website/versioned_docs/version-2.0.0-alpha.43/presets.md → website/versioned_docs/version-2.0.0-alpha.56/presets.md
View File

@ -5,7 +5,7 @@ title: Presets
Presets are collections of plugins and themes.
## Using Presets
## Using presets
A preset is usually a npm package, so you install them like other npm packages using npm.
@ -15,8 +15,7 @@ npm install --save docusaurus-preset-name
Then, add it in your site's `docusaurus.config.js`'s `presets` option:
```jsx {4}
// docusaurus.config.js
```jsx {3} title="docusaurus.config.js"
module.exports = {
// ...
presets: ['@docusaurus/preset-xxxx'],
@ -25,8 +24,7 @@ module.exports = {
To load presets from your local directory, specify how to resolve them:
```jsx {6}
// docusaurus.config.js
```jsx {5} title="docusaurus.config.js"
const path = require('path');
module.exports = {
@ -35,33 +33,34 @@ module.exports = {
};
```
## Presets -> Themes and Plugins
## Presets -> themes and plugins
Presets in some way are a shorthand function to add plugins and themes to your docusaurus config. For example, you can specify a preset that includes the following themes and plugins,
```js
module.exports = function preset(context, opts = {}) {
return {
themes: ['@docusaurus/themes-cool', '@docusaurus/themes-bootstrap'],
plugins: ['@docusaurus/plugin-blog'],
themes: [
require.resolve('@docusaurus/themes-cool'),
require.resolve('@docusaurus/themes-bootstrap'),
],
plugins: [require.resolve('@docusaurus/plugin-blog')],
};
};
```
then in your Docusaurus config, you may configure the preset instead:
```jsx {4}
// docusaurus.config.js
```jsx {3} title="docusaurus.config.js"
module.exports = {
// ...
presets: ['@docusaurus/preset-a'],
presets: ['@docusaurus/preset-my-own'],
};
```
This is equivalent of doing:
```jsx
// docusaurus.config.js
```jsx title="docusaurus.config.js"
module.exports = {
themes: ['@docusaurus/themes-cool', '@docusaurus/themes-bootstrap'],
plugins: ['@docusaurus/plugin-blog'],
@ -70,25 +69,24 @@ module.exports = {
This is especially useful when some plugins and themes are intended to be used together.
## Official Presets
## Official presets
### `@docusaurus/preset-classic`
The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.
| Themes | Plugins |
| -------------------------------- | ----------------------------------- |
| @docusaurus/theme-classic | @docusaurus/plugin-content-docs |
| @docusaurus/theme-search-algolia | @docusaurus/plugin-content-blog |
| | @docusaurus/plugin-content-pages |
| | @docusaurus/plugin-google-analytics |
| | @docusaurus/plugin-google-gtag |
| | @docusaurus/plugin-sitemap |
| Themes | Plugins |
| ---------------------------------- | ------------------------------------- |
| `@docusaurus/theme-classic` | `@docusaurus/plugin-content-docs` |
| `@docusaurus/theme-search-algolia` | `@docusaurus/plugin-content-blog` |
| | `@docusaurus/plugin-content-pages` |
| | `@docusaurus/plugin-google-analytics` |
| | `@docusaurus/plugin-google-gtag` |
| | `@docusaurus/plugin-sitemap` |
To specify plugin options individually, you can provide the necessary fields to certain plugins, i.e. `customCss` for `@docusaurus/theme-classic`, pass them in the preset field, like this:
```js
// docusaurus.config.js
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
@ -116,8 +114,7 @@ In addition to these plugins and themes, `@docusaurus/theme-classic` adds [`rema
The `admonitions` key will be passed as the [options](https://github.com/elviswolcott/remark-admonitions#options) to `remark-admonitions`. Passing `false` will prevent the plugin from being added to MDX.
```js
// docusaurus.config.js
```js title="docusaurus.config.js"
module.exports = {
presets: [
[

45
website/versioned_docs/version-2.0.0-alpha.56/resources.md Normal file
View File

@ -0,0 +1,45 @@
---
id: resources
title: Awesome Resources
---
A curated list of interesting Docusaurus community projects.
## Videos
- [F8 2019: Using Docusaurus to Create Open Source Websites](https://www.youtube.com/watch?v=QcGJsf6mgZE)
## Articles
- [Live code editing in Docusaurus](https://dev.to/mrmuhammadali/live-code-editing-in-docusaurus-28k)
## Showcase
See the <a href={require('@docusaurus/useBaseUrl').default('showcase')}>showcase</a>.
## Official plugins
- [@docusaurus/plugin-content-blog](using-plugins.md#docusaurusplugin-content-blog)
- [@docusaurus/plugin-content-docs](using-plugins.md#docusaurusplugin-content-docs)
- [@docusaurus/plugin-content-pages](using-plugins.md#docusaurusplugin-content-pages)
- [@docusaurus/plugin-google-analytics](using-plugins.md#docusaurusplugin-google-analytics)
- [@docusaurus/plugin-google-gtag](using-plugins.md#docusaurusplugin-google-gtag)
- [@docusaurus/plugin-sitemap](using-plugins.md#docusaurusplugin-sitemap)
- [@docusaurus/plugin-ideal-image](using-plugins.md#docusaurusplugin-ideal-image)
## Community plugins
- [docusaurus-plugin-lunr](https://github.com/daldridge/docusaurus-plugin-lunr) - Docusaurus v2 plugin to create a local search index for use with Lunr.js
- [docusaurus-lunr-search](https://github.com/lelouch77/docusurus-lunr-search) - Offline Search for Docusaurus v2
- [docusaurus-search-local](https://github.com/cmfcmf/docusaurus-search-local) - Offline/local search for Docusaurus v2
- [docusaurus-pdf](https://github.com/KohheePeace/docusaurus-pdf) - Generate documentation into PDF format
- [docusaurus-plugin-sass](https://github.com/rlamana/docusaurus-plugin-sass) - Sass/SCSS stylesheets support
- [docusaurus2-dotenv](https://github.com/jonnynabors/docusaurus2-dotenv) - A Docusaurus 2 plugin that supports dotenv and other environment variables
## Enterprise usage
- Facebook
- Google
- Stripe
- Algolia
- Callstack

18
website/versioned_docs/version-2.0.0-alpha.43/search.md → website/versioned_docs/version-2.0.0-alpha.56/search.md
View File

@ -6,7 +6,7 @@ keywords:
- search
---
Docusaurus's own `@docusaurus/preset-classic` supports a search integration.
Docusaurus' own `@docusaurus/preset-classic` supports a search integration.
There are two main options, you can use [Algolia DocSearch](https://community.algolia.com/docsearch/) or bring in your own `SearchBar` component.
@ -16,19 +16,23 @@ Algolia DocSearch works by crawling the content of your website every 24 hours a
### Connecting Algolia
To connect your docs with Algolia, add an `algolia` field in your `themeConfig`. Note that you will need algolia API key and algolia index. You can [apply for DocSearch here](https://community.algolia.com/docsearch/).
To connect your docs with Algolia, add an `algolia` field in your `themeConfig`. Note that you will need algolia API key and algolia index. You can [apply for DocSearch here](https://docsearch.algolia.com/apply/).
```jsx {4-9}
// docusaurus.config.js
themeConfig: {
// ....
```jsx title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
// ...
// highlight-start
algolia: {
appId: 'app-id',
apiKey: 'api-key',
indexName: 'index-name',
appId: 'app-id', // Optional, if you run the DocSearch crawler on your own
algoliaOptions: {}, // Optional, if provided by Algolia
},
// highlight-end
},
};
```
### Customizing the Algolia search bar

23
website/versioned_docs/version-2.0.0-alpha.43/static-assets.md → website/versioned_docs/version-2.0.0-alpha.56/static-assets.md
View File

@ -15,8 +15,7 @@ A better way would be to use the `useBaseUrl` utility function which appends the
### JSX example
```jsx
// MyComponent.js
```jsx title="MyComponent.js"
import useBaseUrl from '@docusaurus/useBaseUrl';
<img
@ -25,29 +24,35 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
/>;
```
You can also import SVG images, which will be transformed into React components.
```jsx title="MyComponent.js"
import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;
```
### Markdown example
Thanks to MDX, you can also use `useBaseUrl` utility function in Markdown files! You'd have to use `<img>` tags instead of the Markdown image syntax though. The syntax is exactly the same as in JSX.
```txt
// my-doc.mdx
```jsx title="my-doc.mdx"
---
id: my-doc
title: My Doc
---
import useBaseUrl from '@docusaurus/useBaseUrl'; // Add to the top of the file below the front matter.
// Add to the top of the file below the front matter.
import useBaseUrl from '@docusaurus/useBaseUrl';
...
<img alt="Docusaurus with Keytar" src={useBaseUrl('img/docusaurus_keytar.svg')} />;
<img alt="Docusaurus with Keytar" src={useBaseUrl('img/docusaurus_keytar.svg')} />
```
You could also just use Markdown image syntax, but you would have to manually maintain the image paths yourself and isn't recommended.
```md
// my-doc.md
```md title="my-doc.md"
![Docusaurus with Keytar](/img/docusaurus_keytar.png)
```

93
website/versioned_docs/version-2.0.0-alpha.43/styling-layout.md → website/versioned_docs/version-2.0.0-alpha.56/styling-layout.md
View File

@ -10,17 +10,18 @@ import ColorGenerator from '@site/src/components/ColorGenerator';
If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing it as an option into the preset.
```js {8-10}
// docusaurus.config.js
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
// highlight-start
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
// highlight-end
},
],
],
@ -33,11 +34,10 @@ Any CSS you write within that file will be available globally and can be referen
`@docusaurus/preset-classic` uses [Infima](https://facebookincubator.github.io/infima/) as the underlying styling framework. Infima provides flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). For more details, check out the [Infima website](https://facebookincubator.github.io/infima/).
When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `src/css/custom.css` file.
When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `/src/css/custom.css` file.
```css
```css title="/src/css/custom.css"
/**
* /src/css/custom.css
* You can override the default Infima variables here.
* Note: this is not a complete list of --ifm- variables.
*/
@ -55,7 +55,7 @@ When you `init` your Docusaurus 2 project, the website will be generated with ba
Infima uses 7 shades of each color. We recommend using [ColorBox](https://www.colorbox.io/) to find the different shades of colors for your chosen primary color.
Alternatively, use the following tool to generate the different shades for your website and copy the variables into `src/css/custom.css`.
Alternatively, use the following tool to generate the different shades for your website and copy the variables into `/src/css/custom.css`.
<ColorGenerator/>
@ -73,8 +73,7 @@ This is the most traditional way of styling that most developers (including non-
Assuming you are using `@docusaurus/preset-classic` and `/src/css/custom.css` was passed in to the preset config, styles inside that file would be available globally.
```css
/* /src/css/custom.css */
```css title="/src/css/custom.css"
.purple-text {
color: rebeccapurple;
}
@ -94,8 +93,7 @@ function MyComponent() {
To style your components using [CSS Modules](https://github.com/css-modules/css-modules), name your stylesheet files with the `.module.css` suffix (e.g. `welcome.module.css`). webpack will load such CSS files as CSS modules and you have to reference the class names from the imported CSS module (as opposed to using plain strings). This is similar to the convention used in [Create React App](https://facebook.github.io/create-react-app/docs/adding-a-css-modules-stylesheet).
```css
/* styles.module.css */
```css title="styles.module.css"
.main {
padding: 12px;
}
@ -126,4 +124,77 @@ The class names which will be processed by webpack into a globally unique class
### CSS-in-JS
> :warning: _This section is a work in progress._ [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640).\_
:::caution
This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640).
:::
### Sass/SCSS
To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus 2 plugin [`docusaurus-plugin-sass`](https://github.com/rlamana/docusaurus-plugin-sass). This plugin works for both global styles and the CSS modules approach:
1. Install [`docusaurus-plugin-sass`](https://github.com/rlamana/docusaurus-plugin-sass):
```bash npm2yarn
npm install --save docusaurus-plugin-sass
```
2. Include the plugin in your `docusaurus.config.js` file:
```jsx {3} title="docusaurus.config.js"
module.exports = {
// ...
plugins: ['docusaurus-plugin-sass'],
// ...
};
```
3. Write and import your stylesheets in Sass/SCSS as normal.
#### Global styles using Sass/SCSS
You can now set the `customCss` property of `@docusaurus/preset-classic` to point to your Sass/SCSS file:
```jsx {8} title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// ...
theme: {
customCss: require.resolve('./src/css/custom.scss'),
},
// ...
},
],
],
};
```
#### Modules using Sass/SCSS
Name your stylesheet files with the `.module.scss` suffix (e.g. `welcome.module.scss`) instead of `.css`. Webpack will use `sass-loader` to preprocess your stylesheets and load them as CSS modules.
```scss title="styles.module.scss"
.main {
padding: 12px;
article {
color: #ccc;
}
}
```
```jsx
import styles from './styles.module.scss';
function MyComponent() {
return (
<main className={styles.main}>
<article>Lorem Ipsum</article>
</main>
);
}
```

31
website/versioned_docs/version-2.0.0-alpha.56/support.md Normal file
View File

@ -0,0 +1,31 @@
---
id: support
title: Support
---
Docusaurus has a community of thousands of developers.
On this page we've listed some Docusaurus-related communities that you can be a part of; see the other pages in this section for additional online and in-person learning materials.
Before participating in Docusaurus' communities, [please read our Code of Conduct](https://engineering.fb.com/codeofconduct/). We have adopted the [Contributor Covenant](https://www.contributor-covenant.org/) and we expect that all community members adhere to the guidelines within.
## Stack Overflow
Stack Overflow is a popular forum to ask code-level questions or if you're stuck with a specific error. Read through the [existing questions](https://stackoverflow.com/questions/tagged/docusaurus) tagged with **docusaurus** or [ask your own](https://stackoverflow.com/questions/ask?tags=docusaurus)!
## Discussion forums
There are many online forums which are a great place for discussion about best practices and application architecture as well as the future of Docusaurus. If you have an answerable code-level question, Stack Overflow is usually a better fit.
- [Docusaurus online chat](https://discord.gg/docusaurus)
- [#docusaurus-2-dogfooding](https://discord.gg/7wjJ9yH) for user help
- [#docusaurus-2-dev](https://discord.gg/6g6ASPA) for contributing help
- [Reddit's Docusaurus community](https://www.reddit.com/r/docusaurus/)
## Feature requests
For new feature requests, you can create a post on our [Canny board](/feedback), which is a handy tool for roadmapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first!
## News
For the latest news about Docusaurus, [follow **@docusaurus** on Twitter](https://twitter.com/docusaurus) and the [official Docusaurus blog](/blog) on this website.

174
website/versioned_docs/version-2.0.0-alpha.56/team.md Normal file
View File

@ -0,0 +1,174 @@
---
id: team
title: Team
---
## Active Team
<div className="row">
<div className="col col--6 margin-bottom--lg">
<div className="card card--full-height">
<div className="card__header">
<div className="avatar avatar--vertical">
<img
className="avatar__photo avatar__photo--xl"
src="https://github.com/lex111.png"
/>
<div className="avatar__intro">
<h3 className="avatar__name">Alexey Pyltsyn</h3>
</div>
</div>
</div>
<div className="card__body">
Obsessed open-source enthusiast 👋 Eternal amateur at everything 🤷‍♂️ Maintainer of Russian docs on PHP, React, Kubernetes and much more 🧐
</div>
<div className="card__footer">
<div className="button-group button-group--block">
<a className="button button--secondary" href="https://github.com/lex111">GitHub</a>
</div>
</div>
</div>
</div>
<div className="col col--6 margin-bottom--lg">
<div className="card card--full-height">
<div className="card__header">
<div className="avatar avatar--vertical">
<img
className="avatar__photo avatar__photo--xl"
src="https://github.com/fanny.png"
/>
<div className="avatar__intro">
<h3 className="avatar__name">Fanny Vieira</h3>
</div>
</div>
</div>
<div className="card__body">
Fanny got started with web development in high school, building a project for the school kitchen. In her free time she loves contributing to Open Source, occasionally writing on <a href="https://dev.to/fannyvieira" target="_blank">her blog</a> about her experiences, cooking, and creating <a href="https://open.spotify.com/user/anotherfanny" target="_blank">Spotify playlists</a>.
</div>
<div className="card__footer">
<div className="button-group button-group--block">
<a className="button button--secondary" href="https://github.com/fanny">GitHub</a>
<a className="button button--secondary" href="https://twitter.com/fannyvieiira">Twitter</a>
</div>
</div>
</div>
</div>
<div className="col col--6 margin-bottom--lg">
<div className="card card--full-height">
<div className="card__header">
<div className="avatar avatar--vertical">
<img
className="avatar__photo avatar__photo--xl"
src="https://github.com/JoelMarcey.png"
/>
<div className="avatar__intro">
<h3 className="avatar__name">Joel Marcey</h3>
</div>
</div>
</div>
<div className="card__body">
Docusaurus founder and now ever grateful Docusaurus cheerleader to those who actually write code for it.
</div>
<div className="card__footer">
<div className="button-group button-group--block">
<a className="button button--secondary" href="https://github.com/JoelMarcey">GitHub</a>
<a className="button button--secondary" href="https://twitter.com/joelmarcey">Twitter</a>
</div>
</div>
</div>
</div>
<div className="col col--6 margin-bottom--lg">
<div className="card card--full-height">
<div className="card__header">
<div className="avatar avatar--vertical">
<img
className="avatar__photo avatar__photo--xl"
src="https://github.com/yangshun.png"
/>
<div className="avatar__intro">
<h3 className="avatar__name">Yangshun Tay</h3>
</div>
</div>
</div>
<div className="card__body">
Full Front End Stack developer who likes working on the Jamstack. Working on Docusaurus made him Facebook's unofficial part-time Open Source webmaster, which is an awesome role to be in.
</div>
<div className="card__footer">
<div className="button-group button-group--block">
<a className="button button--secondary" href="https://github.com/yangshun">GitHub</a>
<a className="button button--secondary" href="https://twitter.com/yangshunz">Twitter</a>
</div>
</div>
</div>
</div>
</div>
## Honorary Alumni
<div className="row">
<div className="col col--6 margin-bottom--lg">
<div className="card card--full-height">
<div className="card__header">
<div className="avatar avatar--vertical">
<img
className="avatar__photo avatar__photo--xl"
src="https://github.com/endiliey.png"
/>
<div className="avatar__intro">
<h3 className="avatar__name">Endilie Yacop Sucipto</h3>
</div>
</div>
</div>
<div className="card__body">
Maintainer @docusaurus · 🔥🔥🔥
</div>
<div className="card__footer">
<div className="button-group button-group--block">
<a className="button button--secondary" href="https://github.com/endiliey">GitHub</a>
<a className="button button--secondary" href="https://twitter.com/endiliey">Twitter</a>
</div>
</div>
</div>
</div>
<div className="col col--6 margin-bottom--lg">
<div className="card card--full-height">
<div className="card__header">
<div className="avatar avatar--vertical">
<img
className="avatar__photo avatar__photo--xl"
src="https://github.com/wgao19.png"
/>
<div className="avatar__intro">
<h3 className="avatar__name">Wei Gao</h3>
</div>
</div>
</div>
<div className="card__body">
👩🏻‍🌾 Work in progress React developer, maintains Docusaurus, writes docs and spams this world with many websites.
</div>
<div className="card__footer">
<div className="button-group button-group--block">
<a className="button button--secondary" href="https://github.com/wgao19">GitHub</a>
<a className="button button--secondary" href="https://twitter.com/wgao19">Twitter</a>
</div>
</div>
</div>
</div>
</div>
## Acknowledgements
Docusaurus was originally created by Joel Marcey. Today, Docusaurus has a few hundred open source contributors. We’d like to recognize a few people who have made significant contributions to Docusaurus and its documentation in the past and have helped maintain them over the years:
- [Amy Lam](https://github.com/amyrlam)
- [Cheng Lou](https://github.com/chenglou)
- [Christine Abernathy](https://github.com/caabernathy)
- [Christopher Chedeau](https://github.com/vjeux)
- [Elvis Wolcott](https://github.com/elviswolcott)
- [Eric Nakagawa](https://github.com/ericnakagawa)
- [Fienny Angelina](https://github.com/fiennyangeln)
- [Frank Li](https://github.com/deltice)
- [Héctor Ramos](https://github.com/hramos)
- [Ramón Lamana](https://github.com/rlamana)
- [Ricky Vetter](https://github.com/rickyvetter)
- [Sam Zhou](https://github.com/SamChou19815)

265
website/versioned_docs/version-2.0.0-alpha.56/theme-classic.md Normal file
View File

@ -0,0 +1,265 @@
---
id: theme-classic
title: '@docusaurus/theme-classic'
---
:::caution
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 {4} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
disableDarkMode: false,
// ...
},
};
```
With the enabled `defaultDarkMode` option you could set dark mode by default. However, in this case, the user's preference will not be taken into account until they manually sets the desired mode via toggle in the navbar.
```js {4} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
defaultDarkMode: true,
// ...
},
};
```
### Meta image
You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`.
```js {4-6} title="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',
// ...
},
};
```
### Announcement bar
Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and dismissable panel above the navbar.
```js {4-10} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
announcementBar: {
id: 'support_us', // Any value that will identify this message.
content:
'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
backgroundColor: '#fafbfc', // Defaults to `#fff`.
textColor: '#091E42', // Defaults to `#000`.
},
// ...
},
};
```
## Hooks
### `useThemeContext`
React hook to access theme context. This context contains functions for setting light and dark mode and boolean property, indicating which mode is currently in use.
Usage example:
```jsx
import React from 'react';
// highlight-next-line
import useThemeContext from '@theme/hooks/useThemeContext';
const Example = () => {
// highlight-next-line
const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
return <h1>Dark mode is now {isDarkTheme ? 'on' : 'off'}</h1>;
};
```
## 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. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab.
To improve dark mode support, you can also set a different logo for this mode.
```js {5-11} title="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`.
target: '_self', // By default, this value is calculated based on the `href` attribute (the external link will open in a new tab, all others in the current one).
},
},
// ...
},
};
```
### Navbar links
You can add links to the navbar via `themeConfig.navbar.links`:
```js {5-15} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
navbar: {
links: [
{
// Client-side routing, used for navigating within the website.
// The baseUrl will be automatically prepended to this value.
to: 'docs/introduction',
// A full-page navigation, used for navigating outside of the website.
// You should only use either `to` or `href`.
href: 'https://www.facebook.com',
// Prepends the baseUrl to href values.
prependBaseUrlToHref: true,
// The string to be shown.
label: 'Introduction',
// Left or right side of the navbar.
position: 'left', // or 'right'
// To apply the active class styling on all
// routes starting with this path.
// This usually isn't necessary
activeBasePath: 'docs',
// Alternative to activeBasePath if required.
activeBaseRegex: 'docs/(next|v8)',
// Custom CSS class (for styling any item).
className: '',
},
// ... other links
],
},
// ...
},
};
```
React Router should automatically apply active link styling to links, but you can use `activeBasePath` in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use `activeBaseRegex`. `activeBaseRegex` is a more flexible alternative to `activeBasePath` and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.
Outbound (external) links automatically get `target="_blank" rel="noopener noreferrer"` attributes.
### Navbar dropdown
Navbar items can also be dropdown items by specifying the `items`, an inner array of navbar links.
```js {9-19} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
navbar: {
links: [
{
label: 'Community',
position: 'left', // or 'right'
items: [
{
label: 'Facebook',
href: '...',
},
{
label: 'GitHub',
href: '...',
},
// ... more items
],
},
],
},
// ...
},
};
```
### 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 {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
navbar: {
hideOnScroll: true,
},
// ...
},
};
```
<!--
## Footer
TODO.
-->
## 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} title="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 {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
prism: {
defaultLanguage: 'javascript',
},
// ...
},
};
```

157
website/versioned_docs/version-2.0.0-alpha.43/using-plugins.md → website/versioned_docs/version-2.0.0-alpha.56/using-plugins.md
View File

@ -15,8 +15,7 @@ npm install --save docusaurus-plugin-name
Then you add it in your site's `docusaurus.config.js`'s `plugins` option:
```jsx {4}
// docusaurus.config.js
```jsx {3} title="docusaurus.config.js"
module.exports = {
// ...
plugins: ['@docusaurus/plugin-content-pages'],
@ -25,8 +24,7 @@ module.exports = {
Docusaurus can also load plugins from your local directory, you can do something like the following:
```jsx {6}
// docusaurus.config.js
```jsx {5} title="docusaurus.config.js"
const path = require('path');
module.exports = {
@ -41,8 +39,7 @@ For the most basic usage of plugins, you can provide just the plugin name or the
However, plugins can have options specified by wrapping the name and an options object in an array inside your config. This style is usually called `Babel Style`.
```js {5-10}
// docusaurus.config.js
```js {4-9} title="docusaurus.config.js"
module.exports = {
// ...
plugins: [
@ -58,8 +55,7 @@ module.exports = {
Example:
```js
// docusaurus.config.js
```js title="docusaurus.config.js"
module.exports = {
plugins: [
// Basic usage.
@ -88,15 +84,14 @@ A plugin is a module which exports a function that takes two parameters and retu
The exported modules for plugins are called with two parameters: `context` and `options` and returns a JavaScript object with defining the [lifecycle APIs](./lifecycle-apis.md).
```js
// my-docusaurus-plugin.js
```js title="docusaurus.config.js"
module.exports = function(context, options) {
// ...
return {
name: 'my-docusaurus-plugin',
async loadContent() { ... },
async contentLoaded({content, actions}) { ... },
/* other lifecycle api */
/* other lifecycle API */
};
};
```
@ -121,7 +116,7 @@ interface LoadContext {
#### Return value
The returned object value should implement the [lifecycle APIs](./lifecycle-apis.md).
The returned object value should implement the [lifecycle APIs](lifecycle-apis.md).
## Official plugins
@ -137,54 +132,74 @@ Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaur
npm install --save @docusaurus/plugin-content-blog
```
> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::tip
```js
// docusaurus.config.js
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-blog',
{
/**
* Path to data on filesystem
* relative to site dir
* Path to data on filesystem relative to site dir.
*/
path: 'blog',
/**
* URL route for the blog section of your site
* do not include trailing slash
* URL for editing a blog post.
* Example: 'https://github.com/facebook/docusaurus/edit/master/website/blog/'
*/
editUrl:
'https://github.com/facebook/docusaurus/edit/master/website/blog/',
/**
* URL route for the blog section of your site.
* *DO NOT* include a trailing slash.
*/
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
postsPerPage: 10,
/**
* Theme components used by the blog pages
* Theme components used by the blog pages.
*/
blogListComponent: '@theme/BlogListPage',
blogPostComponent: '@theme/BlogPostPage',
blogTagsListComponent: '@theme/BlogTagsListPage',
blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
/**
* Remark and Rehype plugins passed to MDX
* Remark and Rehype plugins passed to MDX.
*/
remarkPlugins: [],
remarkPlugins: [
/* require('remark-math') */
],
rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
/**
* Truncate marker, can be a regex or string.
*/
truncateMarker: /<!--\s*(truncate)\s*-->/
/**
* Blog feed
* If feedOptions is undefined, no rss feed will be generated
truncateMarker: /<!--\s*(truncate)\s*-->/,
/**
* Show estimated reading time for the blog post.
*/
showReadingTime: true,
/**
* Blog feed.
* If feedOptions is undefined, no rss feed will be generated.
*/
feedOptions: {
type: '', // required. 'rss' | 'feed' | 'all'
title: '', // default to siteConfig.title
description: '', // default to `${siteConfig.title} Blog`
copyright: '',
language: undefined; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
};
language: undefined, // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
},
},
],
],
@ -201,29 +216,33 @@ Provides the [Docs](markdown-features.mdx) functionality and is the default docs
npm install --save @docusaurus/plugin-content-docs
```
> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::tip
```js
// docusaurus.config.js
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
/**
* Path to data on filesystem
* relative to site dir
* Path to data on filesystem relative to site dir.
*/
path: 'docs',
/**
* URL for editing website repo, example: 'https://github.com/facebook/docusaurus/edit/master/website/'
* URL for editing a doc in the website repo.
* Example: 'https://github.com/facebook/docusaurus/edit/master/website/'
*/
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
/**
* URL route for the blog section of your site
* do not include trailing slash
* URL route for the blog section of your site.
* *DO NOT* include a trailing slash.
*/
routeBasePath: 'docs',
homePageId: '_index', // Document id for docs home page.
include: ['**/*.md', '**/*.mdx'], // Extensions to include.
/**
* Path to sidebar configuration for showing a list of markdown pages.
@ -238,8 +257,16 @@ module.exports = {
/**
* Remark and Rehype plugins passed to MDX
*/
remarkPlugins: [],
remarkPlugins: [
/* require('remark-math') */
],
rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
/**
* Whether to display the author who last updated the doc.
*/
@ -264,10 +291,13 @@ The default pages plugin for Docusaurus. The classic template ships with this pl
npm install --save @docusaurus/plugin-content-pages
```
> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::tip
```js
// docusaurus.config.js
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
@ -301,12 +331,15 @@ The default [Google Analytics](https://developers.google.com/analytics/devguides
npm install --save @docusaurus/plugin-google-analytics
```
> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::
**Configuration**
```js
// docusaurus.config.js
```js title="docusaurus.config.js"
module.exports = {
plugins: ['@docusaurus/plugin-google-analytics'],
themeConfig: {
@ -329,12 +362,15 @@ The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/
npm install --save @docusaurus/plugin-google-gtag
```
> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::
**Configuration**
```js
// docusaurus.config.js
```js title="docusaurus.config.js"
module.exports = {
plugins: ['@docusaurus/plugin-google-gtag'],
themeConfig: {
@ -357,25 +393,30 @@ This plugin creates sitemap for your site so that search engine crawlers can cra
npm install --save @docusaurus/plugin-sitemap
```
> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::tip
```js
// docusaurus.config.js
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::
```js title="docusaurus.config.js"
module.exports = {
plugins: [
'@docusaurus/plugin-sitemap',
{
cacheTime: 600 * 1000, // 600 sec - cache purge period
changefreq: 'weekly',
priority: 0.5,
},
[
'@docusaurus/plugin-sitemap',
{
cacheTime: 600 * 1000, // 600 sec - cache purge period
changefreq: 'weekly',
priority: 0.5,
},
],
],
};
```
### `@docusaurus/plugin-ideal-image`
Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder)
Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder) **in the production builds**.
```bash npm2yarn
npm install --save @docusaurus/plugin-ideal-image
@ -393,13 +434,13 @@ module.exports = {
#### Usage
This plugin supports png, gif and jpg only
This plugin supports the PNG, GIF and JPG formats only.
```jsx
import Image from '@theme/IdealImage';
import thumbnail from './path/to/img.png';
// your react code
// your React code
<Image img={thumbnail} />
// or

43
website/versioned_docs/version-2.0.0-alpha.43/using-themes.md → website/versioned_docs/version-2.0.0-alpha.56/using-themes.md
View File

@ -9,8 +9,7 @@ Like plugins, themes are designed to add functionality to your Docusaurus site.
To use themes, specify the themes in your `docusaurus.config.js`. You may use multiple themes:
```js {4}
// docusaurus.config.js
```js {3} title="docusaurus.config.js"
module.exports = {
// ...
themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
@ -52,18 +51,16 @@ website
For example, a Docusaurus blog consists of a blog plugin and a blog theme.
```js
// docusaurus.config.js
```js title="docusaurus.config.js"
{
theme: ['theme-blog'],
plugins: ['plugin-content-blog'],
}
```
and if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (fictitious non-existing theme):
And if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (fictitious non-existing theme):
```js
// docusaurus.config.js
```js title="docusaurus.config.js"
{
theme: ['theme-blog-bootstrap'],
plugins: ['plugin-content-blog'],
@ -74,7 +71,11 @@ The content plugin remains the same and the only thing you need to change is the
## Swizzling theme components
> ⚠️ 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.
:::caution
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.
:::
Docusaurus Themes' components are designed to be replaceable. To make it easier for you, we created a command for you to replace theme components called `swizzle`.
@ -92,7 +93,13 @@ npm run swizzle @docusaurus/theme-classic Footer
This will copy the current `<Footer />` component used by the theme to a `src/theme/Footer` directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use swizzled component in place of the original one from the theme.
**Note**: You need to restart your dev server for Docusaurus to pick up the new component.
Although we highly discourage swizzling of all components, if you wish to do that, run:
```bash npm2yarn
npm run swizzle @docusaurus/theme-classic
```
**Note**: You need to restart your webpack dev server in order for Docusaurus to know about the new component.
## Official themes by Docusaurus
@ -104,7 +111,11 @@ The classic theme for Docusaurus. You can refer to [classic theme configuration]
npm install --save @docusaurus/theme-classic
```
> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::
### `@docusaurus/theme-search-algolia`
@ -114,7 +125,13 @@ This theme provides a `@theme/SearchBar` component that integrates with Algolia
npm install --save @docusaurus/theme-search-algolia
```
> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
This theme also adds search page available at `/search` path with OpenSearch support.
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::
### `@docusaurus/theme-live-codeblock`
@ -152,8 +169,8 @@ website
There are two lifecycle methods that are essential to theme implementation:
- [getThemePath](lifecycle-apis.md#getthemepath)
- [getClientModules](lifecycle-apis.md#getclientmodules)
- [`getThemePath()`](lifecycle-apis.md#getthemepath)
- [`getClientModules()`](lifecycle-apis.md#getclientmodules)
<!--

21
website/versioned_docs/version-2.0.0-alpha.43/versioning.md → website/versioned_docs/version-2.0.0-alpha.56/versioning.md
View File

@ -1,16 +1,19 @@
---
id: versioning
title: Versioning
---
You can use the version script to cut a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward.
You can use the version script to create a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward.
## :warning: Disclaimer
:::caution
> Consider it really well before starting to version your documentation.
Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!
Most of the times, you don't need versioning and it will just increase your build time and introduces complexity to your codebase. Versioning is **best suited for website with high-traffic and rapid changes in documentation between version**. If your documentation rarely changes, don't version.
:::
To better understand how versioning works and see if it suits your needs, you can read up below.
Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is **best suited for websites with high-traffic and rapid changes to documentation between versions**. If your documentation rarely changes, don't add versioning to your documentation.
To better understand how versioning works and see if it suits your needs, you can read on below.
## Directory structure
@ -58,8 +61,8 @@ npm run docusaurus docs:version 1.1.0
When tagging a new version, the document versioning mechanism will:
- Copy the full `docs/` folder contents into a new `versioned_docs/version-<version>/` folder.
- Create a versioned sidebars file based from your current [sidebar](sidebar.md) configuration (if it exists). Saved it as `versioned_sidebars/version-<version>-sidebars.json`.
- Append the new version number into `versions.json`.
- Create a versioned sidebars file based from your current [sidebar](sidebar.md) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`.
- Append the new version number to `versions.json`.
## Files
@ -106,13 +109,13 @@ Each directory in `versioned_docs/` will represent a documentation version.
### Updating an existing version
You can update multiple docs versions at the same time. Because each directory in `versioned_docs/` represents specific routes when published.
You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published.
1. Edit any file.
1. Commit and push changes.
1. It will be published to the version.
**Example:** When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`.
Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`.
### Deleting an existing version

132
website/versioned_sidebars/version-2.0.0-alpha.43-sidebars.json
View File

@ -1,132 +0,0 @@
{
"version-2.0.0-alpha.43/docs": [
{
"type": "category",
"label": "Docusaurus",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.43/introduction"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/design-principles"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/contributing"
}
]
},
{
"type": "category",
"label": "Getting Started",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.43/installation"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/configuration"
}
]
},
{
"type": "category",
"label": "Guides",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.43/creating-pages"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/styling-layout"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/static-assets"
},
{
"type": "category",
"label": "Docs",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.43/markdown-features"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/sidebar"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/versioning"
}
]
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/blog"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/search"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/deployment"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/migrating-from-v1-to-v2"
}
]
},
{
"type": "category",
"label": "Advanced Guides",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.43/using-plugins"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/using-themes"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/presets"
}
]
},
{
"type": "category",
"label": "API Reference",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.43/cli"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/docusaurus-core"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/docusaurus.config.js"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/lifecycle-apis"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.43/theme-classic"
}
]
}
]
}

156
website/versioned_sidebars/version-2.0.0-alpha.56-sidebars.json Normal file
View File

@ -0,0 +1,156 @@
{
"version-2.0.0-alpha.56/docs": [
{
"type": "category",
"label": "Docusaurus",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.56/introduction"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/design-principles"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/contributing"
}
]
},
{
"type": "category",
"label": "Getting Started",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.56/installation"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/configuration"
}
]
},
{
"type": "category",
"label": "Guides",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.56/creating-pages"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/styling-layout"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/static-assets"
},
{
"type": "category",
"label": "Docs",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.56/docs-introduction"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/markdown-features"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/versioning"
}
]
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/blog"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/search"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/deployment"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/migrating-from-v1-to-v2"
}
]
},
{
"type": "category",
"label": "Advanced Guides",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.56/using-plugins"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/using-themes"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/presets"
}
]
},
{
"type": "category",
"label": "API Reference",
"items": [
{
"type": "doc",
"id": "version-2.0.0-alpha.56/cli"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/docusaurus-core"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/docusaurus.config.js"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/lifecycle-apis"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/theme-classic"
}
]
}
],
"version-2.0.0-alpha.56/community": [
{
"type": "doc",
"id": "version-2.0.0-alpha.56/support"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/team"
},
{
"type": "doc",
"id": "version-2.0.0-alpha.56/resources"
},
{
"type": "link",
"href": "/showcase",
"label": "Showcase"
},
{
"type": "link",
"href": "/feedback",
"label": "Feedback"
}
]
}

4
website/versions.json
View File

@ -1,7 +1,7 @@
[
"2.0.0-alpha.56",
"2.0.0-alpha.55",
"2.0.0-alpha.54",
"2.0.0-alpha.50",
"2.0.0-alpha.48",
"2.0.0-alpha.43"
"2.0.0-alpha.48"
]

8
yarn.lock
View File

@ -9071,10 +9071,10 @@ infer-owner@^1.0.3, infer-owner@^1.0.4:
resolved "https://registry.yarnpkg.com/infer-owner/-/infer-owner-1.0.4.tgz#c4cefcaa8e51051c2a40ba2ce8a3d27295af9467"
integrity sha512-IClj+Xz94+d7irH5qRyfJonOdfTzuDaifE6ZPWfx0N0+/ATZCbuTPq2prFl526urkQd90WyUKIh1DfBQ2hMz9A==
infima@0.2.0-alpha.11:
version "0.2.0-alpha.11"
resolved "https://registry.yarnpkg.com/infima/-/infima-0.2.0-alpha.11.tgz#62a7ce699684fb9106506370037b48a58608eb0a"
integrity sha512-k2roW8kzF9e7wQo8KTALY7lJRgU6bARSej5/ujA8fvJKyiDPTnzW/MgnDAelFWp6ZvCaEsBLkcv+n3FbjZnsZQ==
infima@0.2.0-alpha.12:
version "0.2.0-alpha.12"
resolved "https://registry.yarnpkg.com/infima/-/infima-0.2.0-alpha.12.tgz#6b4a0ba9756262e4f1af2c60feb4bc0ffd9b9e21"
integrity sha512-in5n36oE2sdiB/1rzuzdmKyuNRMVUO9P+qUidUG8leHeDU+WMQ7oTP7MXSqtAAxduiPb7HHi0/ptQLLUr/ge4w==
inflight@^1.0.4:
version "1.0.6"