Jetbrains Writerside 使用教程

系列文章目录

---

前言

---

一、入门

Writerside 是基于 IntelliJ 平台的 JetBrains 集成开发环境。使用它可以编写、构建、测试和发布技术文档。

如果你想将 Writerside 作为另一个 JetBrains IDE 的插件，请参阅 Writerside 作为插件。

1.1 安装 Writerside

下载 Writerside 安装程序。

运行安装程序。

观看视频，了解 Writerside 的用户界面和主要功能：

1.2 创建新文档项目

从主菜单中选择文件 | 新建 | 项目。

在 "新建项目 "向导中，选择 "启动项目"，然后单击 "下一步"。

指定新项目的名称和位置，然后单击完成。

一旦有了带有帮助实例的文档项目，就可以添加主题并开始编写内容。单击左侧工具窗口栏中的 Writerside 工具窗口图标，打开 Writerside 工具窗口并开始添加内容。

?1.3 创建主题

1.3.1 从头开始创建主题

1. 在 Writerside 工具窗口的 "目录 "部分，单击 "添加"，然后选择 "空 MD 主题 "来添加 Markdown 主题，或选择 "空 XML 主题 "来添加语义标记主题。有关主题的更多信息，请参阅主题格式。
2. 为主题指定标题和文件名。

1.3.2 从模板创建主题

Writerside 为不同类型的内容提供了内置模板，这些模板包含一些模板结构，可以让你开始使用。

1. 在 Writerside 工具窗口的 "目录 "部分，单击 "添加"，然后在 "从模板创建主题 "下选择一个模板。
2. 为主题指定标题和文件名。

1.4 预览主题

使用 Writerside 预览工具窗口，以准确的方式预览正在编写的主题。

1.4.1 打开 Writerside 预览工具窗口

第一次在编辑器中打开任何主题时，Writerside 会打开 Writerside 预览工具窗口。如果关闭预览后想再次打开，请执行以下操作之一：

单击 Writerside 预览工具窗口按钮 Writerside 预览工具窗口图标。

从主菜单中选择查看 | 工具窗口 | Writerside 预览。

右键单击目录中的任意主题，然后选择预览主题。

1.5. 更改目录

在 Writerside 工具窗口的目录部分，拖动主题来更改它们的顺序和层次结构。

您还可以编辑 .tree 文件来更改目录。为此，请右键单击帮助实例并选择打开 TOC 文件。

更多信息，请参阅目录。

1.6 创建帮助实例

在 Writerside 工具窗口中，单击生成网站 生成网站，然后选择另存为 ZIP 压缩包。

有关更多信息，请参阅在本地构建帮助。

如果你想使用 CI/CD 构建和发布文档，我们有关于 GitHub、GitLab 和 TeamCity Cloud 的说明。

如果您想使用其他 CI/CD 构建文档，请发送邮件至 writerside@jetbrains.com，我们将为您提供 Docker 镜像。

1.7 反馈与支持

报告问题
向我们的 YouTrack 项目报告任何问题、可用性改进或功能请求（您需要注册）。

获取支持并分享反馈
加入 JetBrains Writerside Slack 工作区。

在加入之前，请阅读我们的行为准则。我们假定您在加入前已阅读并确认该守则。

您也可以发送电子邮件至 writerside@jetbrains.com。

二、项目

文档项目包含文档所需的所有配置和内容文件。

2.1 创建新文档项目

1. 从主菜单中选择文件 | 新建 | 项目。
2. 在新建项目向导中，选择启动项目，然后单击下一步。
3. 指定新项目的名称和位置，然后单击完成。

默认情况下，文档项目包含一个实例，可生成一个帮助网站。每个实例都定义了一组主题，编排在目录中。

单击左侧工具窗口栏中的 Writerside 工具窗口图标，打开 Writerside 工具窗口。

使用 Project 工具窗口可以浏览 Writerside 工具窗口无法访问的各种配置文件和资源。

要打开项目工具窗口，请执行以下操作之一：

• 从主菜单中选择查看 | 工具窗口 | 项目。
• 单击左侧工具窗口工具栏上的 Project 工具窗口 Project。
• 按 Alt + 1.

下面是一个典型的 Writerside 启动项目结构示例：

2.2 帮助模块

每个文档项目至少包含一个帮助模块。这是文档项目所有配置和内容文件所在的位置。在前面的例子中，它是 Writerside 目录。你可以给它起任何你喜欢的名字，比如 docs。

在大多数情况下，你只需要一个帮助模块目录。如果项目专门用于文档，则不需要单独的帮助模块目录。在示例启动项目中，可以将 Writerside 目录中的所有内容都放到项目根目录 awesome-docs 中。

不过，最好将与文档源相关的所有内容都放在一个专门的目录中，与集成开发环境特定的项目配置文件分开，尤其是当文档与源代码位于同一个项目中时。如果需要管理多个文档集（每个文档集都有自己的配置文件、实例和主题），甚至可以将多个帮助模块放在不同的目录中。

当我们谈到 Writerside 文档项目的项目根目录时，实际上指的是相应的帮助模块根目录，它包含以下文件和目录：

writerside.cfg

主配置文件定义了 Writerside 项目的基本设置和实例。通过该文件，Writerside 可以知道帮助模块的根目录在哪里。

在旧版本的 Writerside 中，该文件的名称是 project.ihp。如果你的项目中使用的是旧版本的名称，则无需重命名，因为它们是等同的。

topics/

主题文件目录包含 .md 和 .topic 文件。您可以在 writerside.cfg 中为主题注册不同的目录。

images/

媒体目录包含项目中使用的图片、GIF 动画和视频。您可以在 writerside.cfg 中为图片注册不同的目录。

hi.tree

树文件定义了目录：实例中主题的顺序和层次。在树文件中，还指定了该实例的名称和唯一 ID。名称在输出中用作主标题，ID 必须与树文件的名称相同，但不带扩展名。例如，aa.tree 可以定义一个 id="aa" 和 name="Awesome App" 的实例。

每个实例都必须通过在 <instance> 元素中指定其树文件在 writerside.cfg 中注册。

v.list

全局项目变量及其默认值的列表。

请在 writerside.cfg 中的 <vars> 元素中注册此文件。

c.list

类别列表定义了主题 "另请参见 "部分的相关部件链接组。

请在 writerside.cfg 中的 <categories> 元素中注册此文件。

以下文件和目录是可选的：

redirection-rules.xml

重定向规则的配置文件。

code-snippets/

代码片段目录包含代码片段文件，可以作为示例插入代码块中。请在 writerside.cfg 中的 <snippets> 元素中注册此目录。

cfg/

构建配置文件的目录。

编译配置目录可包含以下文件：

• buildprofiles.xml 用于配置最终输出。
• build-script.xml 用于配置联编过程。
• glossary.xml 用于定义术语及其描述，以便在工具提示中使用。

三、实例

?实例是一组内容文件（主题），以树形文件的形式组织成具有唯一 ID 的分层结构（目录）。你可以将一个实例构建成一个帮助网站、用户指南或其他输出内容。

默认情况下，一个典型的 Writerside 文档项目包含一个实例。如果你需要制作多个帮助输出，例如为多个产品或一个产品的多个版本提供文档，为不同的受众、用户类型或输出格式制作文档，可以添加更多实例。你可以跨实例重复使用文档项目中的任何内容。如需了解更多信息，请参阅单一来源和内容重用。

3.1 添加帮助实例

1. 在 Writerside 工具窗口中，右键单击当前帮助实例名称，选择 "新建实例"，然后单击 "新建"。

   

   如果您有使用 Markdown 编写的现有文档，请单击 "从本地 Markdown 文件 "将其导入新实例。?

2. 指定一个名称，该名称将作为输出结果的主标题。如有必要，请修改建议的实例 ID。

   ?确保每个实例的 ID 都是唯一且具有描述性的。它将作为 .tree 文件的名称，您将使用此 ID 过滤可重复使用的内容。

3. 如有必要，请为实例指定网络路径和版本。网络路径用于在发布时将帮助网站上传到适当的位置。版本将显示在帮助主标题旁边。

4. 如果不希望内容被搜索引擎索引，请清除允许搜索引擎索引复选框。有关更多信息，请参阅允许搜索引擎索引。

5. 单击 "确定"。

   这样，Writerside 就会创建一个新的树文件（如 web.tree 或你指定的任何 ID），并在 writerside.cfg 中将其注册为 <instance src="web.tree"/> 。你将在 Writerside 工具窗口中看到新实例。

3.2 更改实例图标颜色

为了在 Writerside 工具窗口中清晰地区分实例，您可能需要指定不同颜色的图标。

右键单击实例，在 "更改颜色 "下选择想要的颜色。

3.3 重命名实例

在 Writerside 工具窗口中，右键单击实例并选择 "编辑"。

为实例指定一个新名称，然后单击 "确定"。

如果没有必要，请不要更改 ID。如果更改了 ID，Writerside 会找到对该实例 ID 的所有引用，并建议运行重命名重构以正确更新所有用法。它还会重命名相应的 .tree 文件。不过，它不会更新任何发布脚本，因此请确保使用新的实例 ID 正确配置它们。

3.4 树形文件

树形文件定义实例中主题的层次结构。下面是一个树形文件示例，它定义了一个 ID 为 aug、名称为 App User Guide 的实例：?

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">

<instance-profile id="aug" name="App User Guide"
                  start-page="introduction.topic">

    <toc-element topic="introduction.topic"/>

    <toc-element topic="settings.topic">
        <toc-element topic="settings_general.topic"/>
        <toc-element topic="settings_advanced.topic"/>
    </toc-element>

    <include from="lib.tree" element-id="reference"/>
</instance-profile>

?树形文件可包含以下元素和属性：

3.4.1 <include>

重复使用另一个树文件的一部分。

<include from="lib.tree" element-id="intro"/>

父元素

<instance-profile> <toc-element>

属性：

element-id

指定元素 ID。

from

指定要包含内容的树文件。

instance

指定元素的条件。例如，你可以定义该元素适用的帮助实例，这样其他帮助实例就不会出现该元素。也可以用 ! 来否定，以指定排除此元素的帮助实例：

<include from="lib.tree" element-id="reference" instance="!foo,bar"/>

origin

如果要在另一个帮助模块中包含树文件中的内容，请将其指定为 origin。

use-filter

使用条件插入内容：只包含用逗号分隔的指定自定义过滤器标记的内容。

3.4.2 <instance-profile>

这是树状文件的根元素。

子元素

<include> <snippet> <toc-element> 子元素

属性：

id

指定此实例的唯一 ID。

is-library

指定这是否是一个可重复使用的 TOC 片段库，而不是一个普通的实例树文件。

name

指定此实例的名称，作为输出的主标题。

start-page

指定当读者导航到帮助网站的根 URL 时默认打开的主题。

status

指定实例的状态

• release 是产生常规输出的默认状态。
• deprecated 用于过时的文档。此状态下的输出将在每个页面上都有一个横幅，警告读者该文档已过期或描述的是产品的旧版本。
• eap 用于仍在开发中的文档。此状态下的输出将在每一页上都有一个横幅，警告读者文档可能会有更改。这可能是因为文档本身尚未完成，或者它所描述的产品还不是最终版本，如早期访问构建版或测试版。

3.4.3 <snippet>

使用 <include> 元素定义树形文件层次结构的一个片段，以便在其他实例中重复使用。

<snippet id="intro">
    <toc-element topic="getting_started.topic"/>
    <toc-element topic="installation_guide.topic"/>
    <toc-element topic="first_run.topic"/>
</snippet>

建议将所有可重复使用的树块保存在一个专用的树文件中，该文件不是已发布的实例。

父元素

<instance-profile> <snippet> <toc-element>?

子元素

<include> <snippet> <toc-element>

属性：

filter

为元素指定自定义过滤器。定义 <snippet> 时，可根据某些标准筛选出内容，然后在 <include> 上指定 use-filter 属性，以便在不同上下文中重复使用此片段。

id

指定片段的标识符。

instance

指定元素的条件。例如，你可以定义该元素适用的实例，这样其他实例就不会出现该元素。也可以用 ! 来否定，以指定排除该元素的帮助实例。

3.4.4 <toc-element>

在 TOC 中添加一个条目。

这通常是一个主题：

<toc-element topic="getting_started.topic"/>

父元素

<instance-profile> <snippet> <toc-element> 父元素

子元素

<include> <snippet> <toc-element> 子元素

属性：

accepts-web-file-names

指定一个 HTML 页面，以便从中创建一个重定向到此 TOC 条目。例如，如果您从发布的输出中删除了一个产生 some-topic.html 的主题，您可能希望添加一个指向其他相关主题的重定向，这样有直接部件链接的读者就不会只看到一个 404 错误。

<toc-element topic="related.topic" accepts-web-file-names="some-topic.html"/>
您可以用逗号分隔指定多个 HTML 页面。

accepts-web-file-names-ref

从 redirection-rules.xml 中指定重定向规则 ID。

filter

为元素指定自定义过滤器。定义 <snippet> 时，可根据某些标准筛选出内容，然后在 <include> 上指定 use-filter 属性，以便在不同上下文中重复使用此片段。

hidden

从 TOC 中隐藏该条目。读者仍能通过一个部件访问相关联的主题，但它在 TOC 中将没有条目。

<toc-element topic="reference.topic" hidden="true"/> 

href

指定一个 URL，以创建一个 TOC 条目，打开该 URL 而不是主题。

id

指定 TOC 元素的标识符。

in

指定另一个实例，以创建对该实例中主题的引用。与 <ref> 一起使用。

<toc-element ref="some.topic" in="ug"/>

instance

指定可重复使用的 TOC 块的条件。例如，您可以定义该元素适用的实例，这样其他实例就不会出现该元素。或者，您也可以用 ! 来否定，以指定排除此元素的帮助实例。

origin

如果您想包含另一个帮助模块中的主题，请指定该模块为原点。

ref

创建对另一个帮助模块中主题的引用

<toc-element ref="some.topic" in="ug"/>

target-for-accept-web-file-names

指定一个 URL，以便从指定为 accepts-web-file-names 的 HTML 页面创建重定向。

toc-title

如果主题标题本身过长，则指定 TOC 条目的标题。

topic

指定与此 TOC 元素相关联的主题。

四、目录

?目录 (TOC) 表示实例的结构。它是使用 <toc-element> 标记在树形文件中定义的。

读者可以在已发布的帮助网站左侧看到目录，并使用它来浏览章节和主题。默认情况下，每个主题都有一个页面内 TOC，它呈现在主题页面的右侧，并显示一级章节标题。

作为作者，您可以使用 Writerside 工具窗口查看当前实例中包含的所有内容，添加、删除和移动主题。TOC 使用各种图标和字体来区分不同类型的 TOC 元素。

Writerside TOC	Generated help TOC

直接引用主题文件的常规 TOC 元素不带任何图标，以常规字体显示。将鼠标悬停在该元素上，可以看到相关的主题文件名称。

如果隐藏 TOC 元素，Writerside 将以灰色字体显示。Writerside 将为该实例建立相关联的主题，但读者无法从 TOC 导航到该主题，只能通过搜索或直接部件链接。

Writerside 工具窗口使用以下图标来表示各种 TOC 元素类型：

	该 TOC 元素包含在另一个实例中。将鼠标悬停在 TOC 元素上，可以查看它是从哪里包含的。 更多信息，请参阅同时重复使用多个主题。
	这是当前实例的主页。当读者打开帮助网站根目录的 URL 时，就会进入该页面。 更多信息，请参阅定义主页。
	该 TOC 元素是一个包装器--一个没有关联主题文件的空 TOC 元素，用于将其他主题归入一个章节。 有关更多信息，请参阅将主题合并为一节。
	此 TOC 元素引用的是外部 URL，而不是主题文件。将鼠标悬停在 TOC 元素上可查看 URL。 更多信息，请参阅将 TOC 部件链接到外部 URL。

?在 TOC 中，您看到的是将要发布的主题标题，而不是主题文件名或主题 ID。如有必要，您可以指定仅限 TOC 的标题或特定于实例的标题。如果需要更改主题标题，请右键单击 TOC 中的主题并选择编辑标题。

4.1 打开主题文件

双击 TOC 中的任意项目，即可在编辑器中打开相应的主题文件。

如果它是一个空的包装，Writerside 将为您导航到相应树文件中的相关 <toc-element> 。

或者，您也可以单击 Writerside 工具窗口工具栏中的同步 TOC 和编辑器 Synchronize TOC and Editor（同步 TOC 和编辑器），在编辑器中打开当前选定的主题。这也可以反过来操作：如果焦点在打开了主题文件的编辑器上，单击 "同步 TOC 和编辑器"（Synchronize TOC and Editor）可在 TOC 中选择相关项目。

4.2 更改主题顺序和层次结构

在 Writerside 工具窗口中拖动项目。

也可以直接编辑树形文件。

4.3 直接编辑树形文件

右键单击 Writerside 工具窗口中的必要实例，然后选择打开 TOC 文件。

或者，右键单击 TOC 中的任意项目，然后选择转到 TOC 元素。

在树形文件中，更改 <toc-element> 标记的顺序和层次。为方便起见，按 CtrlShiftHome 键可上移一行，按 CtrlShiftEnd 键可下移一行。

你还可以删除或添加新的 <toc-element> 标记，并将它们相互嵌套以创建层次结构：

<toc-element topic="Manage_a_documentation_project.topic">
    <toc-element topic="Create_a_project.topic"/>
</toc-element>

4.4 将现有主题文件添加到 TOC

1. 在 Writerside 工具窗口中，选择要添加主题的位置，然后单击新建主题 New Topic 并选择将主题文件部件链接到 TOC。Writerside 会显示项目中存在但尚未添加到当前实例的主题文件列表。
2. 从现有的主题文件列表中选择所需的主题。你可以开始键入名称来筛选列表。

有关内容重用的更多信息，请参阅重用单个主题。

4.5 定义主页

每个帮助网站都必须有一个主题被指定为首页。默认情况下，当你在一个空实例中添加第一个主题时，或者当你从 Markdown 源导入一个项目时，Writerside 会将第一个主题设置为首页。

• 在 Writerside 工具窗口中，右键单击任意一个主题，选择设置为主页。

????????主页由树文件中根 <instance-profile> 元素的 start-page 属性定义。

4.6 从 TOC 隐藏主题

你可以在实例中包含一个主题，使其可以通过直接部件链接访问，但从 TOC 结构中为读者隐藏它。这对于与其他内容没有直接关系的参考主题或法律文件很有用。您不希望它们出现在 TOC 中，但仍希望读者可以搜索到这些信息。另一个例子可能是一些仍在开发或不再支持的功能。

• 打开树形文件，在相应的 <toc-element> 中添加 hidden="true" 属性。

<toc-element topic="legal_info.topic" hidden="true"/>

4.7 将 TOC 部件链接到外部 URL

您可以添加一个 TOC 条目，该条目与主题无关，但指向一个外部 URL，如贵公司的博客、支持门户或付费计划比较。如果某个主题的信息已经在其他地方有记录，那么就没有必要在帮助中将其作为主题进行复制：只需在 TOC 中添加一个指向该主题的部件链接即可。

打开树文件，添加一个没有关联主题的 <toc-element>，但带有指定外部 URL 的 href 属性。

默认情况下，Writerside 会使用 URL 作为 TOC 条目的标题，但你也可以通过 toc-title 属性给它一个更易读的标题。

<toc-element toc-title="JetBrains Writerside"
? ? href="https://www.jetbrains.com/writerside"/>
将主题合并为一节
包装器是没有关联主题文件的空 TOC 元素。一般来说，最好始终为所有主题和章节提供引言。因此，如果您有一组关于特定主题的主题，请将它们合并到某个介绍性主题下。您可以使用章节起始页来创建章节概览。

但是，如果不想为一组主题设置任何介绍，可以将它们嵌套在一个包装 TOC 元素下。当读者点击一个空的封装器时，它只会展开 TOC 的相应部分，而不会打开任何主题。

要制作一个分组了几个主题但没有内容的包装器，请执行以下操作

打开树形文件，添加一个没有关联主题但带有 toc-title 属性的 <toc-element> 。

在包装器 <toc-element> 中添加与该部分相关的主题。

<toc-element toc-title="Getting started">
? ? <toc-element topic="Installation.md"/>
? ? <toc-element topic="Configuration.md"/>
</toc-element>
由于包装器没有相关联的主题文件，也不会产生任何 URL 引用，因此不接受 accepts-web-file-names 等属性。

按字母顺序排序子主题
将多个主题添加到节后，您可能需要对它们进行排序。例如，如果章节中有各种命令或选项的主题，通常按字母顺序排序会更方便。

在 Writerside 工具窗口中，右键单击任何带有子主题的 TOC 元素，然后选择按字母顺序排列子主题。