Writerside Help

Projects

A documentation project contains all the configuration and content files necessary for your documentation.

Create new documentation project

  1. From the main menu, select File | New | Project.

  2. In the New Project wizard, select Starter Project and click Next.

  3. Specify the name and location for your new project and click Finish.

By default, a documentation project contains one instance that produces a single help website. Each instance defines a set of topics organized into a table of contents.

Click The Writerside tool window icon in the left-side tool window bar to open the Writerside tool window.

Use the Project tool window to browse various configuration files and resources not accessible from the Writerside tool window.

To open the Project tool window, do one of the following:

  • From the main menu, select View | Tool Windows | Project.

  • Click Project tool window Project on the left-side tool window toolbar.

  • Press Alt+1.

Here is an example of a typical Writerside starter project structure:

Typical project structure

Help module

Every documentation project contains at least one help module. This is where all configuration and content files of your documentation project are located. In the previous example, it is the directory Writerside. You can name it anything you like, for example docs.

In most cases, you will need just one help module directory. If the project is dedicated exclusively to documentation, you do not need a separate directory for the help module. In the example starter project, you can put everything from the Writerside directory into the project root awesome-docs directory.

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 help modules in separate directories if you need to manage several documentation sets, each with its own configuration file, instances, and topics.

Whenever we talk about the project root of a Writerside documentation project, we actually mean the corresponding help module root, which has 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.

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.

resources/

The directory for resources contains files that readers can download. You can register a different directory for downloadable resources in writerside.cfg.

hi.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" and name="Awesome App".

Every instance must be registered in writerside.cfg by specifying its tree file in the <instance> element.

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.

The following files and directories are optional:

redirection-rules.xml

The configuration file for redirection rules.

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.

Last modified: 13 June 2024