Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(v2): Move sidebar content to its own page #3899

Merged
merged 4 commits into from
Dec 11, 2020
Merged

docs(v2): Move sidebar content to its own page #3899

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1ebfb0e
Move sidebar content to its own page
ArtFlag Dec 9, 2020
44f9cb9
Update website/docs/sidebar.md
slorber Dec 10, 2020
5382dd8
Fix merge conflict
ArtFlag Dec 11, 2020
51b74f7
Fix note
ArtFlag Dec 11, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
276 changes: 0 additions & 276 deletions website/docs/docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,282 +60,6 @@ slug: /
Lorem ipsum
```

## 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 {8-9} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// Sidebars filepath relative to the site dir.
sidebarPath: require.resolve('./sidebars.js'),
},
// ...
},
],
],
};
```

### Hideable sidebar

Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets).

```js {4} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
hideableSidebar: true,
// ...
},
};
```

### Sidebar object

A sidebar object is defined like this:

```typescript
type Sidebar = {
[sidebarId: string]:
| {
[sidebarCategory: string]: SidebarItem[];
}
| SidebarItem[];
};
```

Below is an example of a sidebar object. The key `docs` is the id of the sidebar (can be renamed to something else) and `Getting Started` is a category within the sidebar. `greeting` and `doc1` are both [sidebar item](#sidebar-item).

```js title="sidebars.js"
module.exports = {
docs: {
'Getting started': ['greeting'],
Docusaurus: ['doc1'],
},
};
```

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 title="sidebars.js"
module.exports = {
docs: [
{
type: 'category',
label: 'Getting Started',
items: ['greeting'],
},
{
type: 'category',
label: 'Docusaurus',
items: ['doc1'],
},
],
};
```

You can also have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.

Example:

```js title="sidebars.js"
module.exports = {
firstSidebar: {
'Category A': ['doc1'],
},
secondSidebar: {
'Category A': ['doc2'],
'Category B': ['doc3'],
},
};
```

#### Sidebar item

As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a few types we support:

- [Doc](#doc)
- [Link](#link)
- [Ref](#ref)
- [Category](#category)

#### Doc

```typescript
type SidebarItemDoc =
| string
| {
type: 'doc';
id: string;
};
```

Sidebar item type that links to a doc page. Example:

```js
{
type: 'doc',
id: 'doc1', // string - document id
}
```

Using just the [Document ID](#document-id) is perfectly valid as well, the following is equivalent to the above:

```js
'doc1'; // string - document id
```

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 title="sidebars.js"
module.exports = {
firstSidebar: {
'Category A': ['doc1'],
},
secondSidebar: {
'Category A': ['doc2'],
'Category B': ['doc3'],
},
};
```

#### Link

```typescript
type SidebarItemLink = {
type: 'link';
label: string;
href: string;
};
```

Sidebar item type that links to a non-document page. Example:

```js
{
type: 'link',
label: 'Custom Label', // The label that should be displayed (string).
href: 'https://example.com' // The target URL (string).
}
```

#### Ref

```typescript
type SidebarItemRef = {
type: 'ref';
id: string;
};
```

Sidebar item type that links to doc without bounding it to the sidebar. Example:

```js
{
type: 'ref',
id: 'doc1', // Document id (string).
}
```

#### Category

This is used to add hierarchies to the sidebar:

```typescript
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
};
```

As an example, here's how we created the subcategory for "Docs" under "Guides" in this site:

```js title="sidebars.js"
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};
```

**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'],
},
],
},
};
```

#### Custom Props

If you would like to pass in custom props to a swizzled sidebar item, an optional object called `customProps` can be added to any of the items:

```js
{
type: 'doc';
id: 'doc1';
customProps: {
/* props */
}
}
```

#### 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 {4} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
sidebarCollapsible: false,
// ...
},
};
```

#### 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 only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.
Expand Down
Loading