Thanh bên

We have introduced three types of item types in the example in the previous section: doc, category, and link, whose usages are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: autogenerated, which we will explain in detail later.

• Doc: link to a doc page, associating it with the sidebar
• Link: link to any internal or external page
• Category: creates a dropdown of sidebar items
• Autogenerated: generate a sidebar slice automatically
• HTML: renders pure HTML in the item's position
• *Ref: link to a doc page, without making the item take part in navigation generation

Doc: link to a doc​

Use the doc type to link to a doc page and assign that doc to a sidebar:

type SidebarItemDoc =
  // Normal syntax
  | {
      type: 'doc';
      id: string;
      label: string; // Sidebar label text
      className?: string; // Class name for sidebar label
      customProps?: Record<string, unknown>; // Custom props
    }

  // Shorthand syntax
  | string; // docId shortcut

Example:

sidebars.js

export default {
  mySidebar: [
    // Normal syntax:
    {
      type: 'doc',
      id: 'doc1', // document ID
      label: 'Getting started', // sidebar label
    },

    // Shorthand syntax:
    'doc2', // document ID
  ],
};

If you use the doc shorthand or autogenerated sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the sidebar_label Markdown front matter within that doc, which has higher precedence over the label key in the sidebar item. Similarly, you can use sidebar_custom_props to declare custom metadata for a doc page.

note

A doc item sets an implicit sidebar association. Don't assign the same doc to multiple sidebars: change the type to ref instead.

tip

Sidebar custom props is a useful way to propagate arbitrary doc metadata to the client side, so you can get additional information when using any doc-related hook that fetches a doc object.

Link: link to any page​

Chúng tôi đã giới thiệu ba loại mục trong ví dụ trong phần trước: , và , có cách sử dụng khá trực quan. Chúng tôi sẽ chính thức giới thiệu API của họ. Ngoài ra còn có một loại thứ tư: , mà chúng tôi sẽ giải thích chi tiết sau.doc``category``link``autogenerated

• Tài liệu: liên kết đến trang tài liệu, liên kết trang đó với thanh bên
• Liên kết: liên kết đến bất kỳ trang nội bộ hoặc bên ngoài nào
• Danh mục: tạo danh sách thả xuống các mục thanh bên
• Tự động tạo: tự động tạo lát cắt thanh bên
• HTML: hiển thị HTML thuần túy ở vị trí của mục
• *Tham chiếu: liên kết đến trang tài liệu, mà không làm cho mục tham gia vào việc tạo điều hướng

Tài liệu: liên kết đến tài liệu

Sử dụng loại để liên kết đến trang tài liệu và gán tài liệu đó vào thanh bên:doc

type SidebarItemDoc =
  // Normal syntax
  | {
      type: 'doc';
      id: string;
      label: string; // Sidebar label text
      className?: string; // Class name for sidebar label
      customProps?: Record<string, unknown>; // Custom props
    }

  // Shorthand syntax
  | string; // docId shortcut

Ví dụ:

sidebars.js

export default {
  mySidebar: [
    // Normal syntax:
    {
      type: 'doc',
      id: 'doc1', // document ID
      label: 'Getting started', // sidebar label
    },

    // Shorthand syntax:
    'doc2', // document ID
  ],
};

Nếu bạn sử dụng tốc ký doc hoặc thanh bên được tạo tự động, bạn sẽ mất khả năng tùy chỉnh nhãn thanh bên thông qua định nghĩa mục. Tuy nhiên, bạn có thể sử dụng mặt trước Markdown trong tài liệu đó, có mức ưu tiên cao hơn phím trong mục thanh bên. Tương tự, bạn có thể sử dụng để khai báo siêu dữ liệu tùy chỉnh cho một trang doc.sidebar_label``label``sidebar_custom_props

ghi

Một mục đặt một liên kết thanh bên ngầm. Không gán cùng một tài liệu cho nhiều thanh bên: thay đổi loại thành thay thế.doc``ref

mẹo

Đạo cụ tùy chỉnh thanh bên là một cách hữu ích để truyền siêu dữ liệu doc tùy ý sang phía máy khách, vì vậy bạn có thể nhận thêm thông tin khi sử dụng bất kỳ hook nào liên quan đến doc tìm nạp đối tượng doc.

Liên kết: liên kết đến bất kỳ trang nào

Sử dụng loại để liên kết đến bất kỳ trang nào (nội bộ hoặc bên ngoài) không phải là tài liệu.link

type SidebarItemLink = {
  type: 'link';
  label: string;
  href: string;
  className?: string;
  description?: string;
};

Ví dụ:

sidebars.js

export default {
  myLinksSidebar: [
    // External link
    {
      type: 'link',
      label: 'Facebook', // The link label
      href: 'https://facebook.com', // The external URL
    },

    // Internal link
    {
      type: 'link',
      label: 'Home', // The link label
      href: '/', // The internal path
    },
  ],
};

HTML: hiển thị đánh dấu tùy chỉnh

Sử dụng kiểu để hiển thị HTML tùy chỉnh trong thẻ của mục.html``<li>

Điều này có thể hữu ích để chèn các mục tùy chỉnh như dải phân cách, tiêu đề phần, quảng cáo và hình ảnh.

type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean; // Use default menu item styles
  className?: string;
};

Ví dụ:

sidebars.js

export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
      defaultStyle: true, // Use the default menu item styling
    },
  ],
};

mẹo

Mục menu đã được gói trong thẻ, vì vậy nếu mục tùy chỉnh của bạn đơn giản, chẳng hạn như tiêu đề, chỉ cần cung cấp một chuỗi làm giá trị và sử dụng thuộc tính để tạo kiểu cho nó:<li>``className

sidebars.js

export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: 'Core concepts',
      className: 'sidebar-title',
    },
  ],
};

Thể loại: tạo cấu trúc phân cấp

Sử dụng loại này để tạo cấu trúc phân cấp các mục trong thanh bên.category

type SidebarItemCategory = {
  type: 'category';
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
  className?: string;
  description?: string;

  // Category options:
  collapsible: boolean; // Set the category to be collapsible
  collapsed: boolean; // Set the category to be initially collapsed or open by default
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

Ví dụ:

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      collapsed: false,
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

mẹo

Sử dụng cú pháp tốc ký khi bạn không cần tùy chỉnh:

sidebars.js

export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
      },
    ],
  },
};

Liên kết danh mục

Với các liên kết danh mục, nhấp vào một danh mục có thể điều hướng bạn đến một trang khác.

mẹo

Sử dụng liên kết danh mục để giới thiệu một thể loại tài liệu.

Các danh mục được tạo tự động có thể sử dụng tệp _category_.yml để khai báo liên kết.

Trang chỉ mục đã tạo

Bạn có thể tự động tạo một trang chỉ mục hiển thị tất cả các trang con trực tiếp của thể loại này. Cho phép bạn tùy chỉnh tuyến đường của trang được tạo, mặc định là .slug``/category/[categoryName]

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {
        type: 'generated-index',
        title: 'Docusaurus Guides',
        description: 'Learn about the most important Docusaurus concepts!',
        slug: '/category/docusaurus-guides',
        keywords: ['guides'],
        image: '/img/docusaurus.png',
      },
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

Xem nó hoạt động trên trang Hướng dẫn Docusaurus.

mẹo

Sử dụng các liên kết như một cách nhanh chóng để có được một tài liệu giới thiệu.generated-index

Liên kết tài liệu

Một thể loại có thể liên kết đến một tài liệu hiện có.

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {type: 'doc', id: 'introduction'},
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

Xem nó hoạt động trên trang giới thiệu i18n.

Nhúng chỉ mục đã tạo vào trang tài liệu

Bạn cũng có thể nhúng danh sách thẻ đã tạo vào trang tài liệu bình thường với thành phần. Nó sẽ hiển thị tất cả các mục thanh bên của danh mục mẹ của tài liệu hiện tại.DocCardList

docs/sidebar/index.md

import DocCardList from '@theme/DocCardList';

<DocCardList />

http://localhost:3000

[

📄️ 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)

Danh mục có thể thu gọn

Chúng tôi hỗ trợ tùy chọn mở rộng/thu gọn danh mục. Danh mục có thể thu gọn theo mặc định, nhưng bạn có thể tắt tính năng thu gọn bằng .collapsible: false

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      items: [
        'creating-pages',
        {
          type: 'category',
          collapsible: false,
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

Để làm cho tất cả các danh mục không thể thu gọn theo mặc định, hãy đặt tùy chọn thành :sidebarCollapsible``plugin-content-docs``false

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsible: false,
        },
      },
    ],
  ],
};

ghi

Tùy chọn trong được ưu tiên hơn cấu hình plugin, vì vậy có thể làm cho một số danh mục nhất định có thể thu gọn khi được đặt thành toàn cầu.sidebars.js``sidebarCollapsible``false

Danh mục mở rộng theo mặc định

Danh mục có thể thu gọn được thu gọn theo mặc định. Nếu bạn muốn chúng được mở rộng trên kết xuất đầu tiên, bạn có thể đặt thành :collapsed``false

sidebars.js

export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        type: 'category',
        label: 'Docs',
        collapsed: false,
        items: ['markdown-features', 'sidebar', 'versioning'],
      },
    ],
  },
};

Tương tự như , bạn cũng có thể đặt cấu hình chung thành . Các tùy chọn riêng lẻ trong sẽ vẫn được ưu tiên hơn cấu hình này.collapsible``options.sidebarCollapsed``false``collapsed``sidebars.js

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsed: false,
        },
      },
    ],
  ],
};

cảnh báo

Khi một danh mục có nhưng (thông qua hoặc thông qua cấu hình plugin), danh mục sau sẽ được ưu tiên và danh mục vẫn được hiển thị dưới dạng mở rộng.collapsed: true``collapsible: false``sidebars.js

Sử dụng tốc ký

Bạn có thể thể hiện các mục thanh bên điển hình mà không cần tùy chỉnh nhiều chính xác hơn với cú pháp tốc ký. Có hai phần cho điều này: tốc ký doc và tốc ký danh mục.

Doc viết tắt

Một mục có loại có thể chỉ đơn giản là một chuỗi đại diện cho ID của nó:doc

• Tay dài
• Viết tắt

sidebars.js

export default {
  sidebar: [
    {
      type: 'doc',
      id: 'myDoc',
    },
  ],
};

Vì vậy, có thể đơn giản hóa ví dụ trên thành:

sidebars.js

export default {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        'doc1',
      ],
    },
    {
      type: 'category',
      label: 'Docusaurus',
      items: [
        'doc2',
        'doc3',
      ],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

Viết tắt thể loại

Một mục thể loại có thể được biểu diễn bằng một đối tượng có khóa là nhãn của nó và giá trị là một mảng các mục con.

• Tay dài
• Viết tắt

sidebars.js

export default {
  sidebar: [
    {
      type: 'category',
      label: 'Getting started',
      items: ['doc1', 'doc2'],
    },
  ],
};

Điều này cho phép chúng tôi đơn giản hóa ví dụ đó thành:

sidebars.js

export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
    },
    {
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

Mỗi đối tượng tốc ký sau khi chuyển đổi này sẽ chứa chính xác một mục. Bây giờ hãy xem xét ví dụ đơn giản hơn dưới đây:

sidebars.js

export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

Lưu ý cách hai tốc ký danh mục liên tiếp được nén thành một đối tượng với hai mục. Cú pháp này tạo ra một lát cắt thanh bên: bạn sẽ không thấy đối tượng đó là một mục hàng loạt — đối tượng này được mở ra, với mỗi mục nhập trở thành một mục riêng biệt và chúng được ghép với các mục còn lại (trong trường hợp này là liên kết "Tìm hiểu thêm") để tạo thành mức thanh bên cuối cùng. Các lát thanh bên cũng rất quan trọng khi thảo luận về các thanh bên được tạo tự động.

Bất cứ nơi nào bạn có một mảng các mục được giảm xuống thành một tốc ký danh mục, bạn cũng có thể bỏ qua mảng kèm theo đó.

• Trước
• Sau

sidebars.js

export default {
  sidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: [
        {
          'Basic guides': ['doc2', 'doc3'],
          'Advanced guides': ['doc4', 'doc5'],
        },
      ],
    },
  ],
};