Skip to main content

Markdown 特性

原文 - Markdown Features

Markdown headers​

文档可以使用以下markdown头字段, 使用---包裹:

  • id: 文档唯一标识, 如果没有提供此字段, 默认使用文件名(不包含扩展名)作为文档id.
  • title: 文档标题, 如果没有提供此字段，默认使用文档id
  • hide_title: 是否在文档顶部隐藏标题，默认为 false
  • hide_table_of_contents: 是否隐藏文档右边的目录，默认为 false
  • sidebar_label: 用来控制本文档出现在文档侧边栏及底部上一篇或下一篇文档时显示的文本，默认为 title
  • custom_edit_url: 文档的编辑地址, 如果没有提供, 默认使用 docusauru-plugin-content-docs 中的 editUrl
  • keywords: 文档对应的meta关键词, 用于SEO
  • description: 文档的描述信息 在 <head> 中的 <meta name="description" content="..."/> 和 <meta property="og:description" content="..."/> 使用, 用于SEO。如果没有提供，默认使用文档第一行的内容
  • image: 文章的封面或缩略图

比如:

---
id: doc-markdown
title: Markdown Features
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown :)
custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
description: How do I find you when I cannot solve this problem
keywords:
  - docs
  - docusaurus
image: https://i.imgur.com/mErPwqL.png
---

使用 MDX 嵌入 React 组件​

Docusaurus 内置了对 MDX 的支持，它允许你在Markdown文件中书写JSX，并渲染成React组件。

虽然.md和.mdx文件都使用MDX解析，但是其中有一些细微的不同，为了最准确的解析和更好地编辑器支持，我们建议对包含MDX语法的文件使用.mdx扩展名。 因为所有的文档都是用MDX解析，所以任何HTML都被当做JSX。因此如果你需要对一个组件使用内联样式，请使用JSX语法提供样式对象。

示例: 

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!

也可以导入自己在其他文件中定义的组件，或者通过npm安装第三方组件。

Tabs​

如果想在Markdown文件中显示tab内容，可以使用MDX。Docusaurus也提供了开箱即用的Tabs组件:

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

然后你就能看到以下效果:

This is an apple 🍎

默认情况下tab是立即渲染，可以通过向Tabs组件传递lazy属性延迟渲染。

同步选中tab​

通过groupId属性，可以同步多个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>
Use Ctrl + C to copy.
Use Ctrl + V to paste.

内置目录​

默认情况下每个Markdown文档的右上角都会显示文档目录。下面借助 MDX 实现在文档中插入目录。

全部文档目录​

toc是在所有的MDX文档中都存在的变量, 它包含了MDX文档所有顶层目录:

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />;

自定义文档目录​

toc属性是一个文档目录的列表:

type TOCItem = {
  value: string;
  id: string;
  children: TOCItem[];
};

你可以手写TOC目录树，或者从toc变量中转换:

import TOCInline from '@theme/TOCInline';

<TOCInline
  toc={
    // Only show 4th and 5th top-level heading
    [toc[3], toc[4]]
  }
/>;
note

THe content

Callouts/admonitions​

我们提供额外的Markdown语法 remark-admonitions ，警告信息又一组3个冒号包裹，比如:

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

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 Your Title
The content and title *can* include markdown.
:::
Your Title

The content and title can include markdown.

代码块​

文档中的代码块是非常强大的

代码标题​

可以通过在代码块语言标记后添加title关键词(注意语言标识和title之间需要加空格)指定标题:

/src/components/HelloCodeTitle.js
function HelloCodeTitle(props) {
  return <h1>Hello, {props.name}</h1>;
}

交互式代码编辑​

安装插件: npm install --save @docusaurus/theme-live-codeblock，示例如下：

function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    var timerID = setInterval(() => tick(), 1000);

    return function cleanup() {
      clearInterval(timerID);
    };
  });

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}