From 1b0a9ddc615094bf0dffa03558d6dd5cf3c993a8 Mon Sep 17 00:00:00 2001 From: XGHeaven Date: Fri, 15 Nov 2024 08:50:48 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20ice-lab/?= =?UTF-8?q?icepkg@073a6cb27a02db9eb73771dd8fe49232c4d439f6=20=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- guide/preview/index.html | 56 ++++++++++++++++++++-------------------- search-index.json | 2 +- 2 files changed, 29 insertions(+), 29 deletions(-) diff --git a/guide/preview/index.html b/guide/preview/index.html index 1eb2d4e3..01069224 100644 --- a/guide/preview/index.html +++ b/guide/preview/index.html @@ -9,20 +9,20 @@
-
跳到主要内容

文档预览

使用 @ice/pkg-plugin-docusaurus 插件，依托 Docusaurus 提供的能力，支持编写组件/库文档和预览组件。所有文档默认存放至 docs 文件夹下。支持以 .md 及 .mdx 为后缀的文档。

在使用文档预览功能前，你需要先手动安装 @ice/pkg-plugin-docusaurus 插件：

$ npm install @ice/pkg-plugin-docusaurus --save-dev

并在配置文件中配置插件：

build.config.mts
import { defineConfig } from '@ice/pkg';

export default defineConfig({
  plugins: [
    [
      '@ice/pkg-plugin-docusaurus', 
      {
        title: '标题'
      },
    ],
  ],
});

大功告成。你可以通过以下命令启动预览：

# 若存在 docs 文件夹，则默认启动本地文档预览服务
$ npm start

# 若存在 docs 文件夹，则默认构建预览产物
$ npm run build

关闭文档预览​

@ice/pkg-plugin-docusaurus 插件接受 enable 配置以决定是否启用文档预览，该值默认为 true。如果需要关闭文档预览，可以配置如下：

build.config.mts
import { defineConfig } from '@ice/pkg';

export default defineConfig({
  plugins: [
    [
      '@ice/pkg-plugin-docusaurus', 
      {
        enable: false
      },
    ],
  ],
});

你也可以根据启动的命令来配置是否开启文档预览构建：

build.config.mts
import { defineConfig } from '@ice/pkg';

export default defineConfig({
  plugins: [
    [
      '@ice/pkg-plugin-docusaurus', 
      {
        // start 命令时启用文档预览，build 命令时关闭文档预览产物构建
        enable: {
          start: true,
          build: false
        }
      },
    ],
  ],
});

如何书写文档​

文档以 .md 或 .mdx 为后缀，采用 yaml 和 markdown 语法。

index.md
---
title: 简单的用法
sidebar_position: 1
---

## 本 Demo 演示一行文字的用法

```tsx
import * as React from 'react';
import MyButton from 'my-button';
import './my-button.css';

const App = () => {
  return (
    <main>
      <div>Hello World</div>
      <MyButton />
    </main>
  )
}

export default App;
```

文档结构​

扁平结构​

扁平结构的意思是可以将文档平铺在 docs 文件夹下：

.
├── index.md
└── intro.md

嵌套结构​

此外还支持嵌套结构，如：

.
├── Foo
│   ├── Basic.md
│   └── Complex.md
├── index.md
└── intro.md

文档排序​

文档默认按照文件（或文件夹）的字母顺序进行排列。若要修改排列顺序，可通过下面两种方式。

  • 使用 sidebar_position

可以在文档头部使用 YAML 标记顺序，比如想要将 index.md 设置为：

---
sidebar_position: 0
---

# 这是首页，同时也是标题

在此处描述首页说明信息
  • 文档添加数字前缀
.
├── 01-intro.md
├── 02-Foo
│   ├── 01-Basic.md
│   └── 02-Complex.md
└── index.md

文档标题​

文档会默认使用第一个 markdown 标题，作为文档的 title。此外，可以通过 yaml 语法来修改文档标题：

---
sidebar_label: 这是标题
---

# 这里不再是默认标题了

在此处描述文档内容...

代码块​

将代码渲染成组件​

若想要预览组件，需要给代码块添加 preview 属性。

```tsx preview
import * as React from 'react';
import AddCount from './Button';

const App = () => {
  return (
    <AddCount />
  )
}

export default App;
```

下面展示的就是给上述代码块添加 preview 的效果。

需要注意的是，在 preview 的代码块中引入的样式会 污染 全局，因此建议使用 CSS Modules 或 css-in-js 等方式引入样式。

仅支持 React 组件和 Rax 组件

目前只支持为 jsx、tsx 代码块添加 preview 属性。

提示

在 Markdown 代码块中编写代码会失去类型提示和类型校验。

推荐使用 VSCode 插件 TS in Markdown 以获得类型提示。

推荐使用 tsx 代码块以获得类型校验，并需要确保在 tsconfig.json 中指定以下内容：

{
  "paths": {
    // 假设 my-component 是你的组件名称
    "my-component": ["./src"],
    "my-component/*": ["./src/*"]
  }
}

将代码块渲染成移动端预览的样式​

通过配置 mobilePreview: true 开启将预览方式设置成移动端预览的样式：

import { defineConfig } from '@ice/pkg';

export default defineConfig({
  plugins: [
    [
      '@ice/pkg-plugin-docusaurus', 
      {
        mobilePreview: true,
      },
    ],
  ],
});

同理，所有添加了 preview: true 的代码块会渲染成下面的样式：

引入当前包的包名​

直接引入正在开发的包名 (package.json 中的 name 字段值)，像真实的用户一样在文档中导入你这在开发的包。比如你正在开发一个包名为 my-button 的组件：

import * as React from 'react';
// 假设 'my-button' 是你正在开发的包名
import MyButton from 'my-button';

export default function App() {
  return (
    <MyButton />
  );
}

给代码块定制自定义标题​

若想要给代码块定制自定义标题，可以使用 title 属性：

```tsx title=/src/components/index.jsx
import * as React from 'react';
import MyButton from 'my-button';

export default function Index() {
  return (
    <MyButton />
  );
}
```

文档渲染效果如下：

需要注意的是，在 preview 的代码块中引入的样式会 污染 全局，因此建议使用 CSS Modules 或 css-in-js 等方式引入样式。

仅支持 React 组件和 Rax 组件

目前只支持为 jsx、tsx 代码块添加 preview 属性。

提示

在 Markdown 代码块中编写代码会失去类型提示和类型校验。

推荐使用 VSCode 插件 TS in Markdown 以获得类型提示。

推荐使用 tsx 代码块以获得类型校验，并需要确保在 tsconfig.json 中指定以下内容：

{
  "paths": {
    // 假设 my-component 是你的组件名称
    "my-component": ["./src"],
    "my-component/*": ["./src/*"]
  }
}

将代码块渲染成移动端预览的样式​

通过配置 mobilePreview: true 开启将预览方式设置成移动端预览的样式：

import { defineConfig } from '@ice/pkg';

export default defineConfig({
  plugins: [
    [
      '@ice/pkg-plugin-docusaurus', 
      {
        mobilePreview: true,
      },
    ],
  ],
});

同理，所有添加了 preview: true 的代码块会渲染成下面的样式：

引入当前包的包名​

直接引入正在开发的包名 (package.json 中的 name 字段值)，像真实的用户一样在文档中导入你这在开发的包。比如你正在开发一个包名为 my-button 的组件：

import * as React from 'react';
// 假设 'my-button' 是你正在开发的包名
import MyButton from 'my-button';

export default function App() {
  return (
    <MyButton />
  );
}

给代码块定制自定义标题​

若想要给代码块定制自定义标题，可以使用 title 属性：

```tsx title=/src/components/index.jsx
import * as React from 'react';
import MyButton from 'my-button';

export default function Index() {
  return (
    <MyButton />
  );
}
```

文档渲染效果如下：