eclipse/che-docs

Eclipse Che文档概述

Eclipse Che文档（che-docs）使用Jekyll将.asciidoc文件转换为HTML页面，生成的文档发布于https://www.eclipse.org/che/docs/，并与Eclipse Che的发布周期同步更新。该工具支持文档的构建、预览、版本化管理及贡献，是维护Eclipse Che官方文档的核心工具。

核心功能与特性

• 文档转换：将AsciiDoc（.adoc）文件转换为HTML页面
• 本地预览：支持实时监控文件变化并重新生成资源，提供本地预览（localhost:4000）
• 版本化管理：支持Che 6和Che 7两个主要版本的文档内容分离存储
• 内容组织：提供标准化的页面头配置、关键词和标签管理，优化文档结构和搜索
• 多构建方式：支持Docker容器化构建和本地原生构建两种模式

使用场景

• Eclipse Che文档维护者生成、更新官方文档
• 开发者贡献Eclipse Che文档内容（新增页面、修正错误、补充说明）
• 文档审阅者本地预览文档效果 before 提交变更

详细使用方法

构建与预览

使用Docker方式

仓库根目录提供run.sh脚本，用于启动Docker容器、挂载源码并运行Jekyll：

bash
# 执行脚本启动Docker容器构建并预览
./run.sh

本地预览地址：localhost:4000，Jekyll会监控.asciidoc文件变化并实时重新生成内容。

本地原生构建

无需Docker时，先安装Jekyll依赖（以CentOS为例）：

bash
# 安装依赖包
yum install maven ruby ruby-devel @development-tools

直接运行Maven命令构建：

bash
# 原生构建文档
mvn clean install -Pnative

添加新页面

文件路径

在src/main/pages/che-<MAJOR-VERSION>/${subdir}目录下创建.asciidoc文件，其中<MAJOR-VERSION>替换为6或7，对应Che 6或Che 7版本的文档。若没有合适的子目录，可创建新目录。

页面头配置

参考现有页面头信息，确保生成的HTML页面具有正确的名称、标题和关键词。示例配置：

yaml
---
title: "在Docker上安装单用户Che"
keywords: docker, 安装
tags: [installation, docker]
sidebar: che_6_docs
permalink: docker-single-user.html
folder: setup
---

命名规范

• 页面名称（permalink）使用短名称，采用短横线（-）分隔
• 标题简洁明了，避免过长

关键词与标签

• 关键词：用于搜索功能，需与页面内容相关，在页面头的keywords字段配置
• 标签：需在src/main/pages/che-<MAJOR-VERSION>/tags目录中创建对应标签页，并在src/main/_data/tags.yml中注册标签

格式与AsciiDoc语法

参考文档

AsciiDoc语法参考https://asciidoctor.org/docs/asciidoc-writers-guide/。

链接格式

• 内部页面链接：使用link:file_name.html[链接文本]，文件名无需.adoc后缀，且需在src/main/_data/sidebars/目录的侧边栏定义文件中引用该页面

  示例：

  这是一个link:docker-single-user.html[Docker单用户安装指南]的链接
  

• 内部页面锚点链接：link:file_name.html#anchor[链接文本]

  示例：

  链接到link:docker-single-user.html#prerequisites[前提条件]部分
  

• 外部页面链接：link:https://example.com[链接文本]

  示例：

  访问link:https://github.com/eclipse/che[Eclipse Che GitHub仓库]
  

图片处理

• 存放位置：图片需放在src/main/che/docs/images/目录下的子目录中（不要直接放在images根目录）
• 引用语法：

  image:docker.xuanyuan.run/:directory/img.png[替代文本]
  

• 带链接的图片：

  .点击查看大图
  [link=che/docs/images/devel/js_flow.png]
  image:docker.xuanyuan.run/:devel/js_flow.png[替代文本]
  

• 建议：优先使用动画.gif图片展示复杂UI操作，避免过多图片

特殊字符处理

使用pass-through宏避免特殊字符（如下划线、星号、反引号）被解析为格式标记：

pass:[VARIABLE_NAME__WITH__UNDERSCORES]

获取支持

• GitHub Issue：在https://github.com/eclipse/che-docs/issues/new提交issue
• 公共聊天：加入https://mattermost.eclipse.org/eclipse/channels/eclipse-che与社区及贡献者交流

贡献指南

欢迎通过Pull Request贡献文档改进。具体贡献流程参见https://github.com/eclipse/che#contributing。建议保持文档简洁、准确，遵循现有格式规范。