Jetbrains Writerside 使用教程-编程知识

系列文章目录

前言

一、入门

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

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

1.1 安装 Writerside

下载 Writerside 安装程序。

运行安装程序。

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

1.2 创建新文档项目

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

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

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

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

1.3 创建主题

1.3.1 从头开始创建主题

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

1.3.2 从模板创建主题

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

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

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 创建新文档项目

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

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

单击左侧工具窗口栏中的 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 添加帮助实例

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

如果您有使用 Markdown 编写的现有文档，请单击 "从本地 Markdown 文件 "将其导入新实例。
指定一个名称，该名称将作为输出结果的主标题。如有必要，请修改建议的实例 ID。

确保每个实例的 ID 都是唯一且具有描述性的。它将作为 .tree 文件的名称，您将使用此 ID 过滤可重复使用的内容。
如有必要，请为实例指定网络路径和版本。网络路径用于在发布时将帮助网站上传到适当的位置。版本将显示在帮助主标题旁边。
如果不希望内容被搜索引擎索引，请清除允许搜索引擎索引复选框。有关更多信息，请参阅允许搜索引擎索引。
单击 "确定"。

这样，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>

子元素

属性：

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

Table of contents in the Writerside tool window

Table of contents in the built output

直接引用主题文件的常规 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

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

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

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 元素，然后选择按字母顺序排列子主题。

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