This is an automated email from the ASF dual-hosted git repository. sushuang pushed a commit to branch geo-base-map in repository https://gitbox.apache.org/repos/asf/echarts-handbook.git
commit 51c314e156c4e6b7385bce5a33747cc53303354a Author: 100pah <[email protected]> AuthorDate: Sat Aug 23 19:26:38 2025 +0800 Enhance edit guide. --- contents/en/meta/edit-guide.md | 210 ++++++++++++++++++++++++----------------- contents/zh/meta/edit-guide.md | 197 +++++++++++++++++++++++--------------- 2 files changed, 242 insertions(+), 165 deletions(-) diff --git a/contents/en/meta/edit-guide.md b/contents/en/meta/edit-guide.md index 7331147..62d540c 100644 --- a/contents/en/meta/edit-guide.md +++ b/contents/en/meta/edit-guide.md @@ -1,12 +1,12 @@ # Document Editing Guidelines -## Adding a Markdown File +## Adding a Markdown File [[[#adding-a-markdown-file]]] Add a markdown file to the `contents/zh/` (Chinese posts) or `contents/en/` (English posts) directories, up to three levels. Update the path and title information in `contents/zh/posts.yml` or `contents/en/posts.yml`. Lowercase markdown file names. -## Using Prettier to Automatically Format Code +## Using Prettier to Automatically Format Code [[[#using-prettier-to-automatically-format-code]]] Before you start, we recommend installing the [prettier VSCode plugin](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode), which will automatically format the code for you when you save it. @@ -19,47 +19,72 @@ If you feel that the automatic formatting is breaking your code block, you can a If you find blocks of code that are not formatted, check first for syntax errors in the code. -## Built-in Variables +## Built-in Variables [[[#built-in-variables]]] -- `optionPath` -- `mainSitePath` -- `exampleViewPath` -- `exampleEditorPath` -- `lang` +- `optionPath`: For example, the source code of [xAxis.type](${optionPath}xAxis.type) is: -Usage: + <pre>[xAxis.type](${optionPath}xAxis.type)</pre> +- `apiPath`: For example, the source code of [echarts.init](${apiPath}echarts.init) is: -``` -${xxxxx} -``` + <pre>[echarts.init](${apiPath}echarts.init)</pre> +- `mainSitePath`: For example, the source code of [echarts.init](${mainSitePath}api.html#echarts.init) is: -## Link to Other Articles + <pre>[echarts.init](${mainSitePath}api.html#echarts.init)</pre> +- `exampleEditorPath`: For example, the source code of [line-simple](${exampleEditorPath}line-simple&edit=1&reset=1) is: -```markdown -[Get Apache ECharts](${lang}/basics/download) -``` + <pre>[line-simple](${exampleEditorPath}line-simple&edit=1&reset=1)</pre> +- `exampleViewPath`: For example, the source code of [line-simple](${exampleViewPath}line-simple&edit=1&reset=1) is: -[Get Apache ECharts](${lang}/basics/download) + <pre>[line-simple](${exampleViewPath}scatter-exponential-regression&edit=1&reset=1)</pre> +- `lang`: For example, the source code of [Get Started](${lang}/get-started) is: + + <pre>[Get Started](${lang}/get-started)</pre> -## Embedding Code -### Basic Usage +## Headings [[[#headings]]] +The syntax: <!-- prettier-ignore-start --> +<pre> +## Some Heading [[[#a-unique-id-for-link]]] +</pre> +<!-- prettier-ignore-end --> -```markdown -```js +<md-alert type="danger"> +The id is used to link this heading from outside. +It's strongly recommended to declare the id in each heading (e.g., [[[#a-unique-id-for-link]]]) and ensure it remains unchanged. Otherwise an id is auto-generated base on the title text, which may be unstable (changed when the heading text is changed), and varies across different languages. +</md-alert> + +Note: No need to declare id for the main title of an article, as the link for an article is the file path (declared in `posts.yml`). + +## Link to Other Articles [[[#link-to-other-articles]]] + +The syntax is: +<pre> +[Get Apache ECharts](${lang}/basics/download) +</pre> +The effect is: +[Get Apache ECharts](${lang}/basics/download) + +## Embedding Code [[[#embedding-code]]] + +### Basic Usage [[[#embedding-code-basic-usage]]] + +The syntax is: +<!-- prettier-ignore-start --> +<pre> +```js option = { series: [{ type: 'bar', data: [23, 24, 18, 25, 27, 28, 25] }] }; -\``` -``` - +``` +</pre> <!-- prettier-ignore-end --> +The effect is: ```js option = { series: [ @@ -71,7 +96,7 @@ option = { }; ``` -### Recommended Way of Writing Code +### Recommended Way of Writing Code [[[#embedding-code-recommended-way-of-writing-code]]] In order to allow the tool to help us format the code, we should try to avoid syntactically problematic writing styles. @@ -88,13 +113,14 @@ option = { }; ``` -### Live Preview and Editing +### Live Preview and Editing [[[#embedding-code-live-preview-and-editing]]] -> Currently only preview of Option code is supported +> Currently only preview (render the charts) of ECharts option code is supported +The syntax is: <!-- prettier-ignore-start --> -```markdown -\```js live +<pre> +```js live option = { xAxis: { data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] @@ -107,11 +133,11 @@ option = { } ] }; -\``` -``` - +``` +</pre> <!-- prettier-ignore-end --> +The effect is: ```js live option = { xAxis: { @@ -127,22 +153,22 @@ option = { }; ``` -### More Preview Layouts +### More Preview Layouts [[[#embedding-code-more-preview-layouts]]] -#### Left to Right +#### Left to Right [[[#embedding-code-more-preview-layouts-left-to-right]]] +The syntax is: <!-- prettier-ignore-start --> - -```markdown -```js live {layout: 'lr'} +<pre> +```js live {layout: 'lr'} option = { ... }; -\``` -``` - +``` +</pre> <!-- prettier-ignore-end --> +The effect is: ```js live {layout: 'lr'} option = { xAxis: { @@ -158,20 +184,20 @@ option = { }; ``` -#### Right to left +#### Right to left [[[#embedding-code-more-preview-layouts-right-to-left]]] +The syntax is: <!-- prettier-ignore-start --> - -```markdown -```js live {layout: 'rl'} +<pre> +```js live {layout: 'rl'} option = { ... }; -\``` -``` - +``` +</pre> <!-- prettier-ignore-end --> +The effect is: ```js live {layout: 'rl'} option = { xAxis: { @@ -187,20 +213,19 @@ option = { }; ``` -#### Down to Up +#### Down to Up [[[#embedding-code-more-preview-layouts-down-to-up]]] +The syntax is: <!-- prettier-ignore-start --> - -```markdown -```js live {layout: 'bt'} +<pre> +```js live {layout: 'bt'} option = { ... }; -\``` -``` - +</pre> <!-- prettier-ignore-end --> +The effect is: ```js live {layout: 'bt'} option = { xAxis: { @@ -216,14 +241,12 @@ option = { }; ``` -### Highlighting Lines of Code and Adding Filenames - -Use. +### Highlighting Lines of Code and Adding Filenames [[[#embedding-code-highlighting-lines-of-code-and-adding-filenames]]] +The syntax is: <!-- prettier-ignore-start --> - -```markdown -```js{1,3-5}[option.js] +<pre> +```js{1,3-5}[option.js] option = { series: [ { @@ -232,13 +255,11 @@ option = { } ] }; -\``` -``` - +``` +</pre> <!-- prettier-ignore-end --> -Effects. - +The effect is: ```js{1,3-5}[option.js] option = { series: [ @@ -250,55 +271,68 @@ option = { }; ``` -## Embedding Images +## Embedding Images [[[#embedding-images]]] Source images are stored under `static/images/`. -```markdown +The syntax is: +```  ``` -### Set the Image Height and Width +### Set the Image Height and Width [[[#embedding-images-set-width-height]]] For the temporary style of the current page, you can just write html. -```markdown +``` <img data-src="images/demo.png" style="width: 50px" /> ``` -## Add Example Iframe +## Embedding Examples (Iframe) [[[#embedding-examples]]] -`src` is the string after `?c=` in the https://echarts.apache.org/examples/en/editor.html?c=line-simple address -Use: - -```markdown +The syntax is: +``` <md-example src="doc-example/getting-started" width="100%" height="300"></md-example> ``` +`src` is the string after `?c=` in the https://echarts.apache.org/examples/en/editor.html?c=line-simple address. -Result: +The effect is: <md-example src="doc-example/getting-started" width="100%" height="300"></md-example> -## Add Link to Option Item +## Link to Examples [[[#link-to-examples]]] -Use: +The syntax is: +<pre>[line-simple](${exampleEditorPath}line-simple&edit=1&reset=1)</pre> -```markdown -<md-option link="series-bar.itemStyle.color"></md-option> -``` +The effect is: +[line-simple](${exampleEditorPath}line-simple&edit=1&reset=1) + + +## Link to ECharts Option Items [[[#link-to-echarts-option-items]]] + +The syntax is: +<pre>[xAxis.type](${optionPath}xAxis.type)</pre> + +The effect is: +[xAxis.type](${optionPath}xAxis.type) + +The syntax is: +<pre>[echarts.init](${apiPath}echarts.init)</pre> + +The effect is: +[echarts.init](${apiPath}echarts.init) -Result: -<md-option link="series-bar.itemStyle.color"></md-option> -## More Component Usage +## More Component Usage [[[#more-component-usage]]] The documentation supports the use of globally registered `markdown` components. In addition to the `md-example` component just described, the following components are also available -### md-alert +### md-alert [[[#more-component-usage-md-alert]]] Prompt components -```markdown +``` <md-alert type="info"> This is an info alert. </md-alert> @@ -308,7 +342,7 @@ This is an info alert. This is an info alert. </md-alert> -```markdown +``` <md-alert type="success"> This is a success alert. </md-alert> @@ -318,7 +352,7 @@ This is a success alert. This is a success alert. </md-alert> -```markdown +``` <md-alert type="warning"> This is a warning alert. </md-alert> @@ -328,7 +362,7 @@ This is a warning alert. This is a warning alert. </md-alert> -```markdown +``` <md-alert type="danger"> This is a danger alert. </md-alert> diff --git a/contents/zh/meta/edit-guide.md b/contents/zh/meta/edit-guide.md index 134f9d9..34eaab2 100644 --- a/contents/zh/meta/edit-guide.md +++ b/contents/zh/meta/edit-guide.md @@ -1,12 +1,12 @@ # 文档编辑指南 -## 新增一个 markdown 文件 +## 新增一个 markdown 文件 [[[#adding-a-markdown-file]]] 在 `contents/zh/`（中文文章）或 `contents/en/`（英文文章）目录下新增一个 markdown 文件，最多支持三级目录。将路径及标题信息更新在 `contents/zh/posts.yml` 或 `contents/en/posts.yml`。 markdown 文件名称小写。 -## 使用 prettier 来自动格式化代码 +## 使用 prettier 来自动格式化代码 [[[#using-prettier-to-automatically-format-code]]] 在开始之前，我们推荐安装`prettier`的 [VSCode 插件](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)，该插件可以在你保存的时候自动帮你格式化代码。 @@ -19,45 +19,72 @@ markdown 文件名称小写。 如果你发现有的代码块并没有被格式化，请先检查该代码是否存在语法上的错误。 -## 内置变量 +## 内置变量 [[[#built-in-variables]]] -- `optionPath` -- `mainSitePath` -- `exampleViewPath` -- `exampleEditorPath` -- `lang` -使用方式: +- `optionPath`: 例如，链接 [xAxis.type](${optionPath}xAxis.type) 能这么写而得到： -``` -${xxxxx} -``` + <pre>[xAxis.type](${optionPath}xAxis.type)</pre> +- `apiPath`: 例如，链接 [echarts.init](${apiPath}echarts.init) 能这么写而得到： -## 引用其它文章 + <pre>[echarts.init](${apiPath}echarts.init)</pre> +- `mainSitePath`: 例如，链接 [echarts.init](${mainSitePath}api.html#echarts.init) 能这么写而得到： -```markdown -[获取 Apache ECharts](${lang}/basics/download) -``` + <pre>[echarts.init](${mainSitePath}api.html#echarts.init)</pre> +- `exampleEditorPath`: 例如，链接 [line-simple](${exampleEditorPath}line-simple&edit=1&reset=1) 能这么写而得到： + + <pre>[line-simple](${exampleEditorPath}line-simple&edit=1&reset=1)</pre> +- `exampleViewPath`: 例如，链接 [line-simple](${exampleViewPath}line-simple&edit=1&reset=1) 能这么写而得到： + + <pre>[line-simple](${exampleViewPath}scatter-exponential-regression&edit=1&reset=1)</pre> +- `lang`: 例如，链接 [Get Started](${lang}/get-started) 能这么写而得到： + + <pre>[Get Started](${lang}/get-started)</pre> + + +## 段落标题/子标题 [[[#headings]]] + +The syntax: +<!-- prettier-ignore-start --> +<pre> +## 某段落标题 [[[#a-unique-id-for-link]]] +</pre> +<!-- prettier-ignore-end --> + +<md-alert type="danger"> +id 用于外链到此段落。强烈建议为每个段落标题声明唯一 id ，并且保持不变。否则，会自动根据段落标题文字生成一个 id ，但是当标题修改时，生成的 id 也会变，导致外链失效。并且，不同语言的文档中生成的 id 也不同，很不方便引用。 +</md-alert> + +注：文章主标题不必声明 id ，因为文章的链接就是文件路径（在 `posts.yml` 中定义）。 + +## 引用其它文章 [[[#link-to-other-articles]]] +<pre> +[获取 Apache ECharts](${lang}/basics/download) +</pre> + +效果为： [获取 Apache ECharts](${lang}/basics/download) -## 引用代码 +## 嵌入代码 [[[#embedding-code]]] -### 基础使用 +### 基础使用 [[[#embedding-code-basic-usage]]] +写法为： <!-- prettier-ignore-start --> -```markdown -```js +<pre> +```js option = { series: [{ type: 'bar', data: [23, 24, 18, 25, 27, 28, 25] }] }; -\``` -``` +``` +</pre> <!-- prettier-ignore-end --> +效果为： ```js option = { series: [ @@ -69,7 +96,7 @@ option = { }; ``` -### 代码推荐写法 +### 代码推荐写法 [[[#embedding-code-recommended-way-of-writing-code]]] 为了可以让工具帮助我们对代码进行格式化，我们应该尽量避免有语法问题的写法。 @@ -86,13 +113,14 @@ option = { }; ``` -### 实时预览和编辑 +### 实时预览和编辑 [[[#embedding-code-live-preview-and-editing]]] -> 目前只支持对 Option 代码的预览 +> 目前只支持对 ECharts option 代码的预览（执行代码绘制图表） +写法为： <!-- prettier-ignore-start --> -```markdown -\```js live +<pre> +```js live option = { xAxis: { data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] @@ -105,10 +133,11 @@ option = { } ] }; -\``` -``` +``` +</pre> <!-- prettier-ignore-end --> +效果为： ```js live option = { xAxis: { @@ -124,20 +153,22 @@ option = { }; ``` -### 更多预览布局 +### 更多预览布局 [[[#embedding-code-more-preview-layouts]]] -#### 左右 +#### 左右 [[[#embedding-code-more-preview-layouts-left-to-right]]] +写法为： <!-- prettier-ignore-start --> -```markdown -\```js live {layout: 'lr'} +<pre> +```js live {layout: 'lr'} option = { ... }; -\``` -``` +``` +</pre> <!-- prettier-ignore-end --> +效果为： ```js live {layout: 'lr'} option = { xAxis: { @@ -153,18 +184,20 @@ option = { }; ``` -#### 右左 +#### 右左 [[[#embedding-code-more-preview-layouts-right-to-left]]] +写法为： <!-- prettier-ignore-start --> -```markdown -\```js live {layout: 'rl'} +<pre> +```js live {layout: 'rl'} option = { ... }; -\``` -``` +``` +</pre> <!-- prettier-ignore-end --> +效果为： ```js live {layout: 'rl'} option = { xAxis: { @@ -180,18 +213,19 @@ option = { }; ``` -#### 下上 +#### 下上 [[[#embedding-code-more-preview-layouts-down-to-up]]] +写法为： <!-- prettier-ignore-start --> -```markdown -\```js live {layout: 'bt'} +<pre> +```js live {layout: 'bt'} option = { ... }; -\``` -``` +</pre> <!-- prettier-ignore-end --> +效果为： ```js live {layout: 'bt'} option = { xAxis: { @@ -207,13 +241,12 @@ option = { }; ``` -### 高亮代码行 - -使用： +### 高亮指定代码行以及设置文件名[[[#embedding-code-highlighting-lines-of-code-and-adding-filenames]]] +写法为： <!-- prettier-ignore-start --> -```markdown -\```js {1,3-5} +<pre> +```js {1,3-5}[option.js] option = { series: [ { @@ -222,12 +255,11 @@ option = { } ] }; -\``` -``` +``` +</pre> <!-- prettier-ignore-end --> -效果： - +效果为： ```js {1,3-5} option = { series: [ @@ -239,55 +271,66 @@ option = { }; ``` -## 引用图片 +## 嵌入图片 [[[#embedding-images]]] 图片实际存放地址在 `static/images/` 下。 -```markdown +写法为： +```  ``` -### 设置图片高宽 +### 设置图片高宽 [[[#embedding-images-set-width-height]]] 对于当前页面的临时样式，可以直接写 html： -```markdown +``` <img data-src="images/demo.png" style="width: 50px" /> ``` -## 添加示例 iframe - -`src`为 https://echarts.apache.org/examples/zh/editor.html?c=line-simple 地址中`?c=`后面这一串 +## 嵌入示例（iframe） [[[#embedding-examples]]] -使用： -```markdown +写法为： +``` <md-example src="doc-example/getting-started" width="100%" height="300" /> ``` +其中，`src` 为 https://echarts.apache.org/examples/zh/editor.html?c=line-simple 地址中 `?c=` 后面这一串。 -效果： +效果为： <md-example src="doc-example/getting-started" width="100%" height="300" /> -## 添加配置项链接 +## 添加示例链接 [[[#link-to-examples]]] -使用： +写法为： +<pre>[line-simple](${exampleEditorPath}line-simple&edit=1&reset=1)</pre> -```markdown -<md-option link="series-bar.itemStyle.color" /> -``` +效果为：[line-simple](${exampleEditorPath}line-simple&edit=1&reset=1) + +## 添加 ECharts 配置项链接 [[[#link-to-echarts-option-items]]] + +写法为： +<pre>[xAxis.type](${optionPath}xAxis.type)</pre> + +效果为： +[xAxis.type](${optionPath}xAxis.type) -效果: -<md-option link="series-bar.itemStyle.color" /> +写法为： +<pre>[echarts.init](${apiPath}echarts.init)</pre> -## 更多组件使用 +效果为： +[echarts.init](${apiPath}echarts.init) + + +## 更多组件使用 [[[#more-component-usage]]] 文档支持使用全局注册的`markdown`组件，除了刚才介绍的`md-example`组件，还有下面几种组件 -### md-alert +### md-alert [[[#more-component-usage-md-alert]]] 提示组件 -```markdown +``` <md-alert type="info"> This is an info alert. </md-alert> @@ -297,7 +340,7 @@ This is an info alert. This is an info alert. </md-alert> -```markdown +``` <md-alert type="success"> This is a success alert. </md-alert> @@ -307,7 +350,7 @@ This is a success alert. This is a success alert. </md-alert> -```markdown +``` <md-alert type="warning"> This is a warning alert. </md-alert> @@ -317,7 +360,7 @@ This is a warning alert. This is a warning alert. </md-alert> -```markdown +``` <md-alert type="danger"> This is a danger alert. </md-alert> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
