# avalonia-docs

**Repository Path**: wendq/avalonia-docs

## Basic Information

- **Project Name**: avalonia-docs
- **Description**: Avalonia12中文文档，不定期更新
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://avalonia.czyb.vip/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-11-02
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img alt="Avalonia UI logo" src="static/img/purple-border-gradient-icon.png" width="75px" />
  <h1 align="center">Avalonia UI 中文文档</h1>
</p>

> ## 重要说明
> 此项目是官方 12 版本文档的汉化版本。

本仓库包含 Avalonia UI 文档网站的代码和 Markdown 汉化源文件。

## 目录
- [目录](#目录)
- [反馈](#反馈)
- [文档问题](#文档问题)
- [参与贡献](#参与贡献)
  - [工作流程](#工作流程)
  - [约定规范](#约定规范)
- [本地环境搭建](#本地环境搭建)
  - [环境要求](#环境要求)
  - [安装](#安装)
  - [启动](#启动)
  - [API 参考生成](#api-参考生成)
- [致谢 💜](#致谢-)

## 反馈
欢迎你对文档提出宝贵反馈！你可以加入我们的 [Telegram 社区](https://t.me/Avalonia) 并向我们发送消息。我们非常乐意听取你的意见，并帮助你解决任何疑问或顾虑。

## 文档问题
如果你在文档中发现任何问题，或有与文档直接相关的功能请求，欢迎创建新的 [GitHub issue](https://github.com/AvaloniaUI/avalonia-docs/issues/new)。在创建新 issue 之前，也请先检查是否已有相同问题，以避免重复。

## 参与贡献
如果你想为 Avalonia UI 文档做贡献，需要先 fork 本仓库，然后针对你提出的 Markdown 和/或图片修改提交 pull request。

### 工作流程
推荐采用以下两种工作流程：

- 对于小改动，可以使用每个页面上的 “Edit this page” 按钮，直接在 GitHub 上编辑 Markdown 文件。
- 如果你计划进行较大修改，或者希望在本地预览变更，请将仓库克隆到本地，并按照[本地环境搭建](#本地环境搭建)中的安装与本地开发步骤进行操作。

### 约定规范

- 每个 Markdown 文件的 front matter 都应包含 `id` 和 `title`。其中，`id` 将用于在 `sidebar.js` 或特定版本对应的 `version-x.x.x-sidebars.json` 中引用该文件。
  ```yaml
  ---
  id: platform-support
  title: Supported Platforms
  ---
  ```

- 文件名和文件夹名请使用 `kebab-case`。
  例如：
  - `/docs/getting-started/ide-extensions.md`
  - `/docs/how-to/use-google-fonts.md`

- 图片对于增强产品表现力以及帮助说明文字内容非常重要。对于新增到仓库中的图片，请将其存放在 `static` 文件夹下的 `img` 子目录中。每个主题都需要在 `\static\img\` 下拥有对应文件夹，例如：`static\img\how-to\use-google-fonts\download-font.png`。
  
  在引用图片时，路径和文件名区分大小写，命名规范为 `kebab-case`。建议使用 `import` 来帮助检测失效图片，并将其放在文档顶部附近，以便维护。

  > 在 Markdown 文件中插入图片的示例代码：
  ```markdown
  import ButtonGroup from '/img/button-group.png';
  <img className="screenshot-full" src={ButtonGroup} alt="Button group" />
  ```
  
  不要给 `src` 属性值加引号。  

## 本地环境搭建

### 环境要求

- **Node version >= 18**

### 安装

```bash
npm install
```

### 启动

```bash
npx docusaurus start
```

### API 参考生成

API 参考页面通过 `dotnet-apiref` 工具以及 `apiref.json` 中的配置生成。生成后的内容已经提交到仓库，因此 CI 和其他贡献者在构建站点时不需要额外安装该工具。

#### 手动运行

如果你想在本地重新生成 API 参考内容，请先安装 `dotnet-apiref` 工具，然后执行：

```bash
npm run apiref:materialise
```

该命令会执行 `dotnet-apiref materialise --site .`，读取 `apiref.json`，拉取 NuGet 包，并将 API 文档文件写入站点中。

#### 自动重新生成（可选）

如果你希望在每次本地执行 `build` 或 `start` 之前自动重新生成 API 参考内容，可以将以下生命周期钩子添加到 `package.json` 的 `scripts` 部分：

```json
"prestart": "npm run apiref:materialise",
"prebuild": "npm run apiref:materialise"
```

不要提交这些钩子，因为 CI 环境中没有安装 `dotnet-apiref`，提交后会导致构建失败。生成好的 API 参考文件已经提交到仓库中。

## 致谢 💜

感谢你为改进 Avalonia UI 文档所做的所有贡献与努力。感谢你成为我们 ✨ 社区 ✨ 的一员！