如何参与文档贡献

我们的文档底层基于 Nextra 实现，通过 _meta.json 来定义文件顺序、页面标题、页面布局等配置。

能力介绍

TOC(Table-Of-Content) 可以快速的让你的读者索引到特定的内容。你只需要设计好恰当的标题和层级结构，读者就可以通过页面右侧的 TOC 选单来实现文件内容的快速跳转。当然，你在书写文档时也可以时刻通过 TOC 来检查自己文档的层级结构设计的是否合理。

MDX

MDX 是一种基于 .md 的新的文档格式，它支持你在其中引入 React 组件来丰富文档的内容。新的官网也同时提供了一些内置 React 组件供你使用

example.mdx

some doc content that you write before...
 
<Callout>
You could write some additional information in that place. You also could use mardown syntax in it such as [link](#) or `code`
</Callout>

你当然可以继续使用 .md 来编写文档！不过可以尝试使用 .mdx 来为读者提供更好的阅读体验

Callout

<Callout type="info">
your text...
</Callout>

Callout 组件与你在 markdown 中使用的引言语法 > some text 类似，不过它会以高亮块的方式来突出显示内容，从而更直观的传递一些信息。 Callout 组件提供了四种类型: info，warning，positive 以及 negative，用来适配不同的是用场景。

例如，对于一般性的额外信息来说，我们可以使用 info 类型：

这是一条需要额外说明的信息，可以使用加粗语法或者 代码块 语法。触控回调 依赖物理引擎 ，使用此功能前请确保物理引擎已初始化完毕。

对于一些可能对性能有影响的操作，可以使用 warning 类型增加醒目的提示：

需要注意的是，图片追踪在添加功能时就需要指定追踪的图片，并且在 WebXR 中，同张图片只会被追踪一次。

对于一些推荐操作来说，或者最佳实践来说，可以使用 positive 类型：

点击精灵图集资产，通过调整 打包设置 的 纹理最大宽度 与 纹理最大高度，同时调用 打包对象 中的 打包并预览 ，可以保证图集利用率在一个较高的水平。

最后，对于 breaking change，或者某些非常不推荐的用法，可以使用 negative 类型：

注意，如果你没有把脚本资产绑定到实体的脚本组件上，则脚本不会运行

Comparison

<Comparison
  leftSrc="https://mdn.alipayobjects.com/huamei_rbbfv7/afts/img/A*AxpMSqxO5-IAAAAAAAAAAAAADknZAQ/original"
  leftText="offset: 15.3"
  rightSrc="https://mdn.alipayobjects.com/huamei_rbbfv7/afts/img/A*-Q8FS7vQhkkAAAAAAAAAAAAADknZAQ/original"
  rightText="offset: 20.4"
/>

offset: 15.3

offset: 20.4

图片缩放

新版官网引入了 react-medium-image-zoom 来实现了图片点击放大的功能。你可以使用下面的方式来实现：

your-doc.mdx

import { Image } from '@/mdx'
 
<Image src="https://gw.alipayobjects.com/zos/OasisHub/334d8ca3-639f-4cd9-8aaa-93c1da7acdc3/image-20240318173506046.png" figcaption="This is an embedded image using the Image component" />

This is an embedded image using the Image component

由于我们之前文档中的图片是 markdown 语法和 img 标签混用的，新版在解析时无法正确区分这两种情况。导致无法直接将此功能应用到所有图片中。
举例来说，我们在文档中有时候会在一行内显示某个按钮截图，这时候就不应该使用缩放组件了。所以需要等老文档的图片语法更新后才可以全量使用

代码高亮

新版的代码高亮功能十分强大，你不仅可以在行内代码和独立代码块中实现代码高亮，对于独立代码块，还新增了 行显示，文件名指定，行高亮，区间高亮，关键词高亮 等特色功能。

行内高亮

`let x = 1{:ts}`

比如，这是一段嵌入到文字中的代码 let x = 1, 可以看到 TypeScript 代码有了高亮的效果。

文件名

下面的示例包括了如何显示文件名，以及如何显示行指示器。

script-component.mdx

```ts showLineNumbers filename="example.ts"
class CustomScript extends Script {
  @ignoreClone
  a:boolean = false;
  @assignmentClone
  b:number = 1;
  @shallowClone
  c:Vector3[] = [new Vector3(0,0,0)];
}
```

上面的语法产生的效果如下：

example.ts

class CustomScript extends Script{
  @ignoreClone
  a:boolean = false;
  @assignmentClone
  b:number = 1;
  @shallowClone
  c:Vector3[] = [new Vector3(0,0,0)];
}

使用文件名的场景可能并不常见，但某些情况下显示文件名是有必要的。譬如，对于 project.json 或 Scene.json 这种文件内容，增加文件名的显示可以更直观的传递信息。

行高亮

Markdown

```ts {1,4-5}
async function setupDefaultScene(scene: Scene){
  const root = scene.createRootEntity();
  const cameraEntity = root.createChild();
  cameraEntity.transform.setPosition(0, 0, 10);
  cameraEntity.addComponent(Camera);
  cameraEntity.addComponent(OrbitControl);
}
```

通过 {1,4-5} 这样的语法，我们可以同时实现单行高亮和多行高亮的功能。

async function setupDefaultScene(scene: Scene) {
  const root = scene.createRootEntity();
  const cameraEntity = root.createChild();
  cameraEntity.transform.setPosition(0, 0, 10);
  cameraEntity.addComponent(Camera);
  cameraEntity.addComponent(OrbitControl);
}

指定代码高亮

在某些情况下，你可能需要用户关注某一个关键方法，或某一个类的名称。这时候就可以使用 ```ts /specularTexture/ 语法来实现指定代码高亮的功能。

Markdown

```ts /specularTexture/
  engine.resourceManager
    .load<AmbientLight>({
      type: AssetType.Env,
      url: "https://gw.alipayobjects.com/os/bmw-prod/6470ea5e-094b-4a77-a05f-4945bf81e318.bin",
    })
    .then((ambientLight) => {
      scene.ambientLight = ambientLight;
      skyMaterial.texture = ambientLight.specularTexture;
      skyMaterial.textureDecodeRGBM = true;
      openDebug(ambientLight.specularTexture);
      engine.run();
    });
```

上面的语法产生的效果如下：

engine.resourceManager
  .load<AmbientLight>({
    type: AssetType.Env,
    url: "https://gw.alipayobjects.com/os/bmw-prod/6470ea5e-094b-4a77-a05f-4945bf81e318.bin",
  })
  .then((ambientLight) => {
    scene.ambientLight = ambientLight;
    skyMaterial.texture = ambientLight.specularTexture;
    skyMaterial.textureDecodeRGBM = true;
    openDebug(ambientLight.specularTexture);
    engine.run();
  });

示例

编写示例代码

我们现在提供两种方式让你组织示例代码：

在 examples/ 文件夹下新建 .ts 示例文件来组织示例代码
在 examples/ 文件夹下新建一个 示例文件夹，最后通过 示例文件夹/index.ts 来暴露示例代码

嵌入示例

light.mdx

...
 
Ambient light emits from all directions and enters the eye, as shown in the example below:
 
<playground href="/embed/ambient-light" />
 
...

新增文档

新增文档相较于之前可能多了一些步骤（在某些情况下）。需要提前说明的是，在新的官网中，文件路径即是路由。同时文档的顺序以及标题需要使用 _meta.json 进行配置。

以新增动画系统的文档 joint 来说：

新增文档 docs/animation/joint.mdx
为文档新增 frontMatter。目前支持的字段有:
1. title 文档标题
2. group 文档子标题
3. banner 头图
编写文档内容
修改 animation/_meta.json 来定义文档的顺序和侧边栏中的标题

对于文档国际化而言，则同步在 /docs/en 文件夹中做上述操作

新增博客

新增博客与新增文档的过程类似，只是 frontMatter 多了一些支持的字段。

新增博客文档 blog/new_blog.mdx
为博客增加 frontMatter, 支持的字段有：
1. title 博客标题
2. group 博客分类，可使用英文 , 隔开多个 group 名称
3. banner 头图
4. published 发布时间。年月日格式，例如 2024-03-14
5. author 博客作者定义。包含 name avatar website 三个字段
6. searchable 需要配置为 searchable: false 从而避免被内置的搜索引擎搜索到
7. summary 博客的摘要，会显示在博客列表页中

新增 Changelog

和新增博客的过程一样，只不过文件位于 /changelog 中。

新增示例

除了以往的单文件示例开发外，我们许你将一个大的示例进行拆分。比如将资产文件列表拆分成一个 json，或者将 dat-gui 的配置拆分到 gui-config.ts 中等等。

要实现文件拆分，你只需要在 examples 文件中新建示例文件夹，确保文件夹中包含一个 index.ts 即可。在示例页面生成时，会自动检测代码中所依赖的其他文件，并注入到工作区中。

这篇文档对您有帮助吗？

On this page

能力介绍
TOC
MDX
Callout
Comparison
图片缩放
代码高亮
行内高亮
文件名
行高亮
指定代码高亮
示例
编写示例代码
嵌入示例
新增文档
新增博客
新增 Changelog
新增示例