Modules
Every documentation project contains at least one help module. This is the directory where all configuration and content files of your Writerside project are located.
If the whole project is dedicated exclusively to documentation, you do not need a separate directory for the help module. You can put everything directly in the project root.
However, it is better to keep everything related to your documentation sources in a dedicated directory, separate from the IDE-specific project configuration files, and especially so if your documentation is in the same project as the source code. You can even have multiple Writerside modules in separate directories in the project if you need to manage several documentation sets, each with its own configuration files, instances, topics, and images. It is still possible to share content between instances in different modules.
Module structure
Every help module should have the following files and directories:
- writerside.cfg
The main configuration file defines the basic Writerside project settings and instances. This file is how Writerside knows where the root directory of your help module is.
For more information, see writerside.cfg.
- topics/
The directory for topic files contains .md and .topic files. You can register a different directory for topics in writerside.cfg.
- images/
The directory for media contains images, animated GIFs, and videos used in your project. You can register a different directory for images in writerside.cfg.
- *.tree
The tree file defines the table of contents: the order and hierarchy of topics in an instance. In the tree file, you also specify the name and unique ID for this instance.
The name is used as the main title in the output, and the ID must be the same as the name of the tree file without the extension. For example, aa.tree might define an instance with
id="aa"andname="Awesome App".Every instance must be registered in writerside.cfg by specifying its tree file in the <instance> element.
The following files and directories are optional:
- v.list
The list of global project variables with their default values.
Register this file in the
<vars>element in writerside.cfg.- c.list
The list of categories defines groups of related links for the See also section of a topic.
Register this file in the
<categories>element in writerside.cfg.- redirection-rules.xml
The configuration file for redirection rules.
- resources/
The directory for resources contains files that readers can download. You can register a different directory for downloadable resources in writerside.cfg.
- code-snippets/
The directory for code snippets contains files with pieces of code that you can insert as samples in code blocks. Register this directory in the
<snippets>element in writerside.cfg.- cfg/
The directory for build configuration files.
The build configuration directory can contain the following files:
buildprofiles.xml is used to configure the final output.
build-script.xml is used to configure the build process.
glossary.xml is used to define terms and their descriptions that you can use in tooltips.
Writerside project with multiple modules
Let's say you have a Writerside project with one module and two instances: an Installation Guide and an Administration Guide.
Both instances are in the same module – the default Writerside directory.
Rename module
In the Project tool window, right-click the Writerside directory, select Refactor, then click Rename.
Specify a different name for the directory (for example, main-docs) and click Refactor.
Create module
In the Project tool window, right-click the project root, select New, then click Directory.
Type the name for the new module directory (for example, supplementary) and press Enter.
Right-click the new module directory, select New, then click File.
Type the name of the main configuration file: writerside.cfg and press Enter.
Add some boilerplate markup to writerside.cfg:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/writerside/1.0/ihp.dtd"> <ihp version="2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/writerside-cfg.xsd"> </ihp>
When you restart the project, it will show the new module in the Writerside tool window.
Add instances to the new module. Add and configure the topics directory, images directory that will hold content specific for documentation in this module. If you need to re-use a topic, snippet, or image from another module, use the origin attribute. For example: