Topics
In Writerside, content is organized in topic files. Each topic corresponds to a single web page. It is usually an article covering a specific subject.
Topic files are stored in the topics directory.
The same topic can be used in several instances. For example, if you create content applicable to multiple documentation outputs, you can author it once and reuse it in different tree files.
Topic formats
Writerside supports two topic types: Markdown and XML.
- Markdown topics
Use .md files to author docs in Markdown. You can use everything supported by the CommonMark Spec and extend it with semantic markup.
Markdown is a good choice for small documentation sets that do not rely on a lot of reusable content and complex elements. It is also a good choice if you have internal or external contributors who are not comfortable with XML.
- XML topics
Use .topic files to author docs in semantic XML markup.
This is a good choice for a team of professional writers who rely on extensive content reuse and need to have complex elements, such as large tables, tabs, and collapsible chapters. XML can provide more semantic structure and powerful assistance at the expense of readability for other contributors.
You do not have to stick to only one format and can have a mix of both topic types in your project. For more information, see Markup.
Topic file name and ID
Use the name of the file to reference the topic.
In a tree file:
As a link:
Include:
The ID is the name of the topic file without the extension, such as getting-started. You cannot have multiple topics with the same ID in a help module.
Change topic file name
You may want to change the name of the topic file to ensure that it properly reflects the contents. Authors rely on relevant file names for navigation in a documentation project.
The topic file name is also used as the web page name by default. Your readers and search engines may rely on this name in the URL.
Select a topic in the Writerside tool window and press Shift+F6.
In the Rename dialog, specify the new name for the topic file.
Click Refactor to automatically update all references to this topic in your project.
You can also click Preview to first review all changes that will happen in a dedicated tool window, and click Do Refactor if they look good.
The Rename refactoring will also update the topic ID, which must be the same as the topic file name.
Add a redirect from the previous topic URL to this topic to prevent 404 errors in links that point to the old URL.
Topic title and TOC title
The topic title should reflect the contents of the topic. It is what your readers see as the top-level header of the web page built from the topic file. It is also used as the title of the corresponding entry in the table of contents.
In an XML topic, you specify the title in the root <topic> tag as title="Getting started with My Awesome App".
In an MD topic, the title is the first-level header: # Getting started with My Awesome App.
Change topic title
As your content evolves, you may want to change the topic title to better reflect its current content.
Right-click a topic in the Writerside tool window and select Edit Title.
Specify the topic title and click OK.
Override topic title for a help instance
If you reuse the same topic in multiple outputs, you may want to adjust the title for a specific instance. For example, add a related technology name or some important keywords to make it more discoverable.
Right-click a topic in the Writerside tool window and select Edit Title.
Under Advanced Settings, specify a title for the current instance and click OK.
This will add the following line to the topic:
Override TOC title
If the topic title is long and contains many important keywords, you can set a shorter title to use for the corresponding entry in the table of contents. The main topic title will remain the same.
Right-click a topic in the Writerside tool window and select Edit Title.
Under Advanced Settings, specify a TOC title and click OK.
This will add the toc-title attribute to the corresponding <toc-element> in the tree file file of the current instance:
Web file name
By default, the name of the HTML file generated from a topic is the name of the topic file with all letters converted to lowercase and special symbols replaced with dashes.
For example, Document_everything.topic will become document-everything.html.
Specify custom web file name
It is important both for your readers and SEO that the URL reflects the contents of the HTML web page. If the contents of a topic change, you can either rename the topic file or specify a custom web file name for it.
Use the
<web-file-name>element to set a custom name of the web page for the topic:<web-file-name>Document_almost_everything.html</web-file-name>Add a redirect from the previous topic URL to this topic to prevent 404 errors in links that point to the old URL.