页面
创建一个React page src/pages/helloReact.js
import React from 'react';
import Layout from '@theme/Layout';
export default function Hello() {
return (
<Layout title="Hello" description="Hello React Page">
<div
style={{
display: 'flex',
justifyContent: 'center',
alignItems: 'center',
height: '50vh',
fontSize: '20px',
}}>
<p>
Edit <code>pages/helloReact.js</code> and save to reload.
</p>
</div>
</Layout>
);
}
访问地址 http://localhost:3000/helloReact
创建一个markDown 页面
---
title: 我的问候页面标题
description: 我的问候页面描述
hide_table_of_contents: true
---
# 你好
今天过得怎么样？
访问地址:http://localhost:3000/helloMarkdown
Markdown 不如 React 页面灵活，因为它总是会用主题布局
路由方式 如下:
- /src/pages/index.js → [baseUrl]
- /src/pages/foo.js → [baseUrl]/foo
- /src/pages/foo/test.js → [baseUrl]/foo/test
- /src/pages/foo/index.js → [baseUrl]/foo/
举个例子,你可以在下面两种方式中选择一种：
Add a /src/pages/support.js file
Create a /src/pages/support/ directory and a /src/pages/support/index.js file.
我们推荐后者，这样你可以把和页面相关的文件都放在这个文件夹里。 For example, a CSS module file (styles.module.css) with styles meant to only be used on the “Support” page.
- 注意任务文件 _ 开头的文件都会被忽略
文档
创建文档
创建一个markdown文件,并且放在docs目录下
website # 你的网站的根目录
├── docs
│ └── greeting.md
├── src
│ └── pages
├── docusaurus.config.js
├── …
文档标记
可以内联定义标签，也可以引用 tags 文件中声明的预定义标签（可选，通常为 docs/tags.yml）
如下:
- docusaurus 存在docs/tags.yml （内联标签）
- Releases 不存在docs/tags.yml (外联标签)
---
tags:
- Releases
- docusaurus
---
# Title
Content
docusaurus:
label: 'Docusaurus'
permalink: '/docusaurus'
description: 'Docs related to the Docusaurus framework'
组织文件夹结构
Document ID
任何文档都有一个唯一id,这个唯一id是相对于更目录的名字
可以在文档中指定id名字
---
id: part1
---
Doc Urls
默认情况下，文档的 URL 位置是其相对于 docs 文件夹的文件路径，但有一些例外。也就是说，如果文件命名为以下名称之一，则文件名不会包含在 URL 中
可以使用slug去改变URL
侧边栏
要在你的 Docusaurus 网站上使用侧边栏，只需两步：
- 定义一个 sidebars 文件，用于导出 sidebar 对象的字典。
- 将其路径直接或通过 @docusaurus/preset-classic 传递给 @docusaurus/plugin-docs 插件。
默认侧边栏
export default {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', //从 docs 文件夹（或 versioned_docs/）生成侧边栏<version>
},
],
};
自定义侧边栏
type Sidebar =
// 普通语法
| SidebarItem[]
// 简写语法
| {[categoryLabel: string]: SidebarItem[]};
如下
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',
},
],
};
隐藏侧边栏
export default {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};
自动折叠侧边栏
export default {
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
},
};
传递自定义 props
这对于通过混合 React 组件呈现侧边栏项来应用网站自定义功能非常有用。
{
type: 'doc',
id: 'doc1',
customProps: {
badges: ['new', 'green'],
featured: true,
},
};
侧边栏痕迹导航
面包屑导航默认会在页面顶端渲染。它用的是当前页面的「侧边栏路径」。
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};
案例
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;
侧边栏项目
Doc: link to a doc
Link: link to any page
HTML: render custom markup
export default {
myHtmlSidebar: [
{
type: 'html',
value: 'Core concepts',
className: 'sidebar-title',
},
],
};
Category: create a hierarchy (创建层次结构)
export default {
docs: [
{
type: 'category',
label: 'Guides',
collapsible: true,
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
# 不需要定制化简写
export default {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};
Category links
使用类别链接，让点击类别标签可以跳转到另一个页面。
- 自动生成的类别可以使用 category.yml 文件来声明链接。
列出所有标签
import DocCardList from '@theme/DocCardList';
<DocCardList />
Collapsible categories (展开/折叠分类)
- 全局设置默认是否折叠 可以编辑docusaurus.config.js => presets => docs => sidebarCollapsible: false
- sidebars.js 优先级高于docusaurus.config.js配置
Expanded categories by default（可折叠菜单默认被折叠）
- global properties options.sidebarCollapsed to false
collapsible 优先级高于collapsed
使用简写
export default {
sidebar: [
'myDoc',
],
};
-- 分类侧边栏
export default {
sidebar:[
'Getting started': ['doc1','doc2']
]
}
只要你有一个项目数组最终被缩减到了一个类别简写，你都可以略去外面的数组方括号。
export default {
sidebar: {
'Getting started': ['doc1'],
Docusaurus: {
'Basic guides': ['doc2', 'doc3'],
'Advanced guides': ['doc4', 'doc5'],
},
},
};
自动生成侧边栏
export default {
myAutogeneratedSidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' 即当前 docs 文件夹
},
],
};
类别索引文档的文件名符合下列条件之一：
- Named as index (case-insensitive): docs/Guides/index.md
- Named as README (case-insensitive): docs/Guides/README.mdx
- Same name as parent folder: docs/Guides/Guides.md
- 如果一个文件夹只有一个索引页，它会变成一个链接，而不是一个类别。 This is useful for asset collocation:
Autogenerated sidebar metadata
对于手写的边栏定义，您可以通过 sidebars.js 向边栏项目提供元数据;对于自动生成的 Docusaurus 来说，Docusaurus 会从项目的相应文件中读取它们。此外，您可能希望调整每个项目的相对位置，因为默认情况下，侧边栏切片中的项目将按字母顺序生成（使用文件和文件夹名称）
Doc item metadata
label、className 和 customProps 属性在 front matter 中分别声明为 sidebar_label、sidebar_class_name 和 sidebar_custom_props。可以通过 front matter 以相同的方式指定位置sidebar_position。
Category item metadata
添加一个_category_.json或者_category_.yml 文件.您可以指定任何类别元数据以及位置元数据。label、className、position 和 customProps 将默认为该类别的关联文档的相应值（如果有的话）。
position: 2.5 # float position is supported
label: 'Tutorial'
collapsible: true # make the category collapsible
collapsed: false # keep the category open by default
className: red
link:
type: generated-index
title: Tutorial overview
customProps:
description: This description can be used in the swizzled DocCard
Using number prefixes
可以在每个文档和文件夹添加一个数字前缀,这会让文件系统按文件排序时也是有序的.
默认情况下，Docusaurus 会从文档 ID、标题、标签和 URL 路径中删除数字前缀。
customize the sidebar items generator
你可以在 docs 插件（或预设）配置中提供自定义的 sidebarItemsGenerator 函数：
docusaurus.config.js
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
async sidebarItemsGenerator({
defaultSidebarItemsGenerator,
numberPrefixParser,
item,
version,
docs,
categoriesMetadata,
isCategoryIndex,
}) {
// 示例：返回一列硬编码的静态侧边栏项目
return [
{type: 'doc', id: 'doc1'},
{type: 'doc', id: 'doc2'},
];
},
},
],
],
};
使用多个侧边栏
displayed_sidebar 强制使用侧边栏关联
---
displayed_sidebar: apiSidebar
---
如果设置 displayed_sidebar: null 则不会显示任何侧边栏
Generating pagination
会用侧边栏信息，在每一页文档的末尾生成「下一页」和「上一页」的导航链接。 它严格地使用当前显示的侧边栏：如果没有绑定的侧边栏，它也不会生成分页导航.
自定义侧边栏
pagination_next and pagination_prev.
---
pagination_next: 上手
---
# Windows 安装
评论区