Manage topics

In Writerside, content is organized in topic files. Each topic corresponds to a single web page.

Topic files are stored in the /topics directory of your doc project or module.

The same topic can be used in several instances. For example, if you create content that's applicable to multiple documentation outputs, you can author it once and reuse it in different contexts.

Topic formats

Writerside supports two topic types:

.md files: you can use these to author docs in Markdown. If you need to use elements that are not supported by the basic Markdown syntax, you can extend it with semantic attributes or inject entire semantic elements.
.topic files: you can use these to author docs using the semantic markup that contains elements for various types of content.

You don't have to stick to any of these formats and can have a mix of both file types in your project. See Markup reference for details.

How do I decide which format to use?

.topic

If you are used to structured XML-based authoring and already know that your content needs to have complex elements such as tabs, collapsible content blocks, complex tables with merged cells, definition lists and the like, you may choose to use .topic files.

This also makes sense if you have a team of professional technical writers and no one else contributes to documentation.

.md

If you are just starting to write content around your product and want to stay light, you can stick to .md files. You can inject semantic attributes whenever you need to enrich Markdown, or inject entire semantic elements as your content grows and becomes more complex. Writerside provides completion and validation for such injections, so you don't need to learn the markup.

Note that you don't need to do any migration or change files format from .md to .topic even if at some point you end up with more semantic markup than Markdown in your files.

It also makes sense to choose .md as your primary format if you have multiple contributors to your documentation inside your product team, or need to accept external pull requests.

Last modified: 19 October 2023