Cấu hình Sidebar
Tạo thanh bên rất hữu ích để:
- Nhóm nhiều tài liệu liên quan
- Hiển thị thanh bên trên mỗi tài liệu đó
- Cung cấp điều hướng phân trang, với nút tiếp theo / trước đó
Để sử dụng thanh bên trên trang Docusaurus của bạn:
- Xác định tệp xuất từ điển các đối tượng thanh bên.
- Truyền đối tượng này vào plugin trực tiếp hoặc thông qua .
@docusaurus/plugin-docs``@docusaurus/preset-classic
docusaurus.config.js
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
},
],
],
};
Phần này đóng vai trò là tổng quan về các tính năng khác của thanh bên doc. Trong các phần sau, chúng tôi sẽ giới thiệu một cách có hệ thống hơn các khái niệm sau:
[
📄️ Các mục trong thanh bên
Chúng tôi đã giới thiệu ba loại mục trong ví dụ trong phần trước được tạo tự động, chúng tôi sẽ giải thích chi tiết sau.
](https://docusaurus.io/docs/sidebar/items)
[
📄️ Tự động tạo
Docusaurus có thể tạo thanh bên tự động từ cấu trúc hệ thống tệp của bạn: mỗi thư mục tạo một danh mục thanh bên và mỗi tệp tạo một liên kết doc.
](https://docusaurus.io/docs/sidebar/autogenerated)
[
📄️ Sử dụng nhiều thanh bên
Bạn có thể tạo một thanh bên cho mỗi bộ tệp Markdown mà bạn muốn nhóm lại với nhau.
](https://docusaurus.io/docs/sidebar/multiple-sidebars)
Thanh bên mặc định
Nếu không xác định, Docusaurus sẽ tự động tạo thanh bên cho bạn, bằng cách sử dụng cấu trúc hệ thống tệp của thư mục:sidebarPath``docs
sidebars.js
export default {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
},
],
};
Bạn cũng có thể xác định thanh bên của mình một cách rõ ràng.
Đối tượng thanh bên
Một thanh bên ở mấu chốt của nó là một hệ thống phân cấp các danh mục, liên kết tài liệu và các siêu liên kết khác.
// Normal syntax
| SidebarItem[]
// Shorthand syntax
| {[categoryLabel: string]: SidebarItem[]};
Chẳng hạn:
sidebars.js
export default {
mySidebar: [
{
type: 'category',
label: 'Getting Started',
items: [
{
type: 'doc',
id: 'doc1',
},
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
{
type: 'doc',
id: 'doc2',
},
{
type: 'doc',
id: 'doc3',
},
],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
Đây là tệp thanh bên xuất một thanh bên, được gọi là . Nó có ba mục cấp cao nhất: hai danh mục và một liên kết bên ngoài. Trong mỗi danh mục, có một vài liên kết tài liệu.mySidebar
Tệp thanh bên có thể chứa nhiều đối tượng thanh bên, được xác định bằng khóa đối tượng của chúng.
type SidebarsFile = {
[sidebarID: string]: Sidebar;
};
Cấu hình chủ đề
Thanh bên có thể ẩn
Bằng cách bật tùy chọn, bạn có thể ẩn toàn bộ thanh bên, cho phép người dùng tập trung tốt hơn vào nội dung. Điều này đặc biệt hữu ích khi nội dung được tiêu thụ trên màn hình cỡ trung bình (ví dụ: máy tính bảng).themeConfig.docs.sidebar.hideable
docusaurus.config.js
export default {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};
Tự động thu gọn danh mục thanh bên
Tùy chọn sẽ thu gọn tất cả các danh mục anh chị em khi mở rộng một danh mục. Điều này giúp người dùng không phải mở quá nhiều danh mục và giúp họ tập trung vào phần đã chọn.themeConfig.docs.sidebar.autoCollapseCategories
docusaurus.config.js
export default {
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
},
};
Chuyển đạo cụ tùy chỉnh
Để chuyển đạo cụ tùy chỉnh vào một mục thanh bên, hãy thêm đối tượng tùy chọn vào bất kỳ mục nào. Điều này rất hữu ích để áp dụng các tùy chỉnh trang web bằng cách xoay các thành phần React hiển thị các mục thanh bên.customProps
{
type: 'doc',
id: 'doc1',
customProps: {
badges: ['new', 'green'],
featured: true,
},
};
Breadcrumbs thanh bên
Theo mặc định, breadcrumbs được hiển thị ở trên cùng, sử dụng "đường dẫn thanh bên" của trang hiện tại.
Hành vi này có thể bị vô hiệu hóa với các tùy chọn plugin:
docusaurus.config.js
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};
Ví dụ về thanh bên phức tạp
Một ví dụ thực tế từ trang Docusaurus:
sidebars.js
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
docs: [
'introduction',
{
type: 'category',
label: 'Getting Started',
link: {
type: 'generated-index',
},
collapsed: false,
items: [
'installation',
'configuration',
'playground',
'typescript-support',
],
},
{
type: 'category',
label: 'Guides',
link: {
type: 'generated-index',
title: 'Docusaurus Guides',
description:
"Let's learn about the most important Docusaurus concepts!",
keywords: ['guides'],
image: '/img/docusaurus.png',
},
items: [
'guides/creating-pages',
{
type: 'category',
label: 'Docs',
link: {
type: 'doc',
id: 'guides/docs/introduction',
},
items: [
'guides/docs/create-doc',
{
type: 'category',
label: 'Sidebar',
link: {
type: 'doc',
id: 'guides/docs/sidebar/index',
},
items: [
'guides/docs/sidebar/items',
'guides/docs/sidebar/autogenerated',
'guides/docs/sidebar/multiple-sidebars',
],
},
'guides/docs/versioning',
'guides/docs/multi-instance',
],
},
'blog',
{
type: 'category',
label: 'Markdown Features',
link: {
type: 'doc',
id: 'guides/markdown-features/introduction',
},
items: [
'guides/markdown-features/react',
'guides/markdown-features/tabs',
'guides/markdown-features/code-blocks',
'guides/markdown-features/admonitions',
'guides/markdown-features/toc',
'guides/markdown-features/assets',
'guides/markdown-features/links',
'guides/markdown-features/plugins',
'guides/markdown-features/math-equations',
'guides/markdown-features/diagrams',
'guides/markdown-features/head-metadata',
],
},
'styling-layout',
'swizzling',
'static-assets',
'search',
'browser-support',
'seo',
'using-plugins',
'deployment',
{
type: 'category',
label: 'Internationalization',
link: {type: 'doc', id: 'i18n/introduction'},
items: [
{
type: 'doc',
id: 'i18n/tutorial',
label: 'Tutorial',
},
{
type: 'doc',
id: 'i18n/git',
label: 'Using Git',
},
{
type: 'doc',
id: 'i18n/crowdin',
label: 'Using Crowdin',
},
],
},
'guides/whats-next',
],
},
{
type: 'category',
label: 'Advanced Guides',
link: {type: 'doc', id: 'advanced/index'},
items: [
'advanced/architecture',
'advanced/plugins',
'advanced/routing',
'advanced/ssg',
'advanced/client',
],
},
{
type: 'category',
label: 'Upgrading',
link: {
type: 'doc',
id: 'migration/index',
},
items: [
'migration/v3',
{
type: 'category',
label: 'To Docusaurus v2',
items: [
'migration/v2/migration-overview',
'migration/v2/migration-automated',
'migration/v2/migration-manual',
'migration/v2/migration-versioned-sites',
'migration/v2/migration-translated-sites',
],
},
],
},
],
api: [
'cli',
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
export default sidebars;