文档编辑指南

添加 Markdown 文件

在 `contents/en/`（中文文章）或 `contents/en/`（英文文章）目录下添加 markdown 文件，最多支持三级目录。在 `contents/en/posts.yml` 或 `contents/en/posts.yml` 中更新路径和标题信息。在 `components/helper/contributors.ts` 中添加相应的贡献者信息。（注意，该文件中 `en` 和 `zh` 是分开列出的。）

Markdown 文件名请使用小写。

使用 Prettier 自动格式化代码

在开始之前，我们建议安装 prettier VSCode 插件，它会在你保存时自动格式化代码。

如果你觉得自动格式化破坏了你的代码块，可以添加以下注释来阻止 prettier 格式化该代码块内部的代码

<!-- prettier-ignore-start -->
<!-- prettier-ignore-end -->

如果发现代码块没有被格式化，请先检查代码中是否存在语法错误。

内置变量

• optionPath：例如，xAxis.type 的源代码是

  [xAxis.type](${optionPath}xAxis.type)

• apiPath：例如，echarts.init 的源代码是

  [echarts.init](${apiPath}echarts.init)

• mainSitePath：例如，echarts.init 的源代码是

  [echarts.init](${mainSitePath}api.html#echarts.init)

• exampleEditorPath：例如，line-simple 的源代码是

  [line-simple](${exampleEditorPath}line-simple&edit=1&reset=1)

• exampleViewPath：例如，line-simple 的源代码是

  [line-simple](${exampleViewPath}scatter-exponential-regression&edit=1&reset=1)

• lang：例如，快速上手 的源代码是

  [Get Started](${lang}/get-started)

标题

语法

## Some Heading [[[#a-unique-id-for-link]]]

id 用于从外部链接到该标题。强烈建议在每个标题中声明 id（例如，[[[#a-unique-id-for-link]]]）并确保其保持不变。否则，将根据标题文本自动生成 id，这可能不稳定（当标题文本更改时会发生变化），并且在不同语言之间会有所不同。

注意：无需为文章的主标题声明 id，因为文章的链接是文件路径（在 posts.yml 中声明）。

链接到其他文章

语法为

[Get Apache ECharts](${lang}/basics/download)

效果为：获取 Apache ECharts

嵌入代码

基本用法

语法为

```js
option = {
    series: [{
        type: 'bar',
        data: [23, 24, 18, 25, 27, 28, 25]
    }]
};
```

效果为

option = {
  series: [
    {
      type: 'bar',
      data: [23, 24, 18, 25, 27, 28, 25]
    }
  ]
};

推荐的代码书写方式

为了让工具能够帮助我们格式化代码，我们应该尽量避免语法有问题的书写风格。

例如，注释 ...

option = {
  series: [
    {
      type: 'bar'
      // ...
    }
  ]
};

实时预览和编辑

目前仅支持 ECharts 配置项（option）代码的预览（渲染图表）

语法为

```js live
option = {
  xAxis: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis: {},
  series: [
    {
      type: 'bar',
      data: [23, 24, 18, 25, 27, 28, 25]
    }
  ]
};
```

效果为

option = {
  xAxis: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis: {},
  series: [
    {
      type: 'bar',
      data: [23, 24, 18, 25, 27, 28, 25]
    }
  ]
};

更多预览布局

从左到右

语法为

```js live {layout: 'lr'}
option = {
  ...
};
```

效果为

option = {
  xAxis: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis: {},
  series: [
    {
      type: 'bar',
      data: [23, 24, 18, 25, 27, 28, 25]
    }
  ]
};

从右到左

语法为

```js live {layout: 'rl'}
option = {
  ...
};
```

效果为

option = {
  xAxis: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis: {},
  series: [
    {
      type: 'bar',
      data: [23, 24, 18, 25, 27, 28, 25]
    }
  ]
};

从下到上

语法为

```js live {layout: 'bt'}
option = {
  ...
};

效果为

option = {
  xAxis: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis: {},
  series: [
    {
      type: 'bar',
      data: [23, 24, 18, 25, 27, 28, 25]
    }
  ]
};

高亮代码行并添加文件名

语法为

```js{1,3-5}[option.js]
option = {
  series: [
    {
      type: 'bar',
      data: [23, 24, 18, 25, 27, 28, 25]
    }
  ]
};
```

效果为

option = {
  series: [
    {
      type: 'bar',
      data: [23, 24, 18, 25, 27, 28, 25]
    }
  ]
};

嵌入图片

源图片存储在 static/images/ 下。

语法为

![image description](images/demo.png)

设置图片的高度和宽度

对于当前页面的临时样式，可以直接编写 html。

<img data-src="images/demo.png" style="width: 50px" />

嵌入示例 (Iframe)

语法为

<md-example src="doc-example/getting-started" width="100%" height="300"></md-example>

src 是 https://echarts.org.cn/examples/en/editor.html?c=line-simple 地址中 ?c= 之后的字符串。

效果为

链接到示例

语法为

[line-simple](${exampleEditorPath}line-simple&edit=1&reset=1)

效果为：line-simple

链接到 ECharts 配置项

语法为

[xAxis.type](${optionPath}xAxis.type)

效果为：xAxis.type

语法为

[echarts.init](${apiPath}echarts.init)

效果为：echarts.init

更多组件用法

文档支持使用全局注册的 markdown 组件。除了刚才介绍的 md-example 组件外，还有以下组件可用

md-alert

提示组件

<md-alert type="info">
This is an info alert.
</md-alert>

这是一条信息提示。

<md-alert type="success">
This is a success alert.
</md-alert>

这是一条成功提示。

<md-alert type="warning">
This is a warning alert.
</md-alert>

这是一条警告提示。

<md-alert type="danger">
This is a danger alert.
</md-alert>

这是一条危险提示。