# 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](help-modules.html#topics-dir) .
The same topic can be used in several [instances](instances.html). For example, if you create content applicable to multiple documentation outputs, you can author it once and [reuse it](single-sourcing.html) in different [tree files](instances.html#tree-file).
## 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](https://spec.commonmark.org/current/) and extend it with [semantic markup](markup-reference.html#semantic).
:
:
:
: 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](markup-reference.html).
Example MD topic:
```
# Getting started with My Awesome App
A paragraph
```
Example XML topic:
```XML
A paragraph.
```
## Topic file name and ID
Use the name of the file to reference the topic.
In a [tree file](help-modules.html#tree-file) :
```XML
```
As a [link](links-and-references.html):
```XML
```
```
[](getting-started.md)
```
[Include](reuse-pieces-of-content.html#reuse-single-elements):
```XML
```
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](projects.html#help_module).
> **Note:**
> For an XML topic, you must specify the ID explicitly in the root `` tag as `id="getting-started"`.
Procedure: 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](#web_file_name) by default. Your readers and search engines may rely on this name in the URL.
1. Select a topic in the Writerside tool window and press `Shift+F6` (Windows), `⇧ F6` (macOS), `⇧ F6` (IntelliJ IDEA Classic (macOS)), `⌘ ⌥ R` (macOS System Shortcuts), `Shift+F6` (XWin), `Shift+F6` (GNOME), `Shift+F6` (KDE), `Shift+F6` (Emacs), `Shift+F6` (Sublime Text), `⇧ F6` (Sublime Text (macOS)), `Ctrl+R` (NetBeans), `Ctrl+R, R` (Visual Studio), `⌘ R, R` (Visual Studio (macOS)), `Alt+Shift+R` (Eclipse), `⇧ F6` (Eclipse (macOS)).
2. In the Rename dialog, specify the new name for the topic file.
> **Note:**
> Make sure that the topic file name is unique within a help instance and does not conflict with any [custom web page names](#web_file_name).
3. 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.
4. [Add a redirect](redirects.html) 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](table-of-contents.html).
In an XML topic, you specify the title in the root `` 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`.
Procedure: Change topic title
As your content evolves, you may want to change the topic title to better reflect its current content.
1. Right-click a topic in the Writerside tool window and select Edit Title.
2. Specify the topic title and click OK.
> **Note:**
> This will not change the URL because the [name of the web page](#web_file_name) depends on the topic file name, not the title.
Procedure: Override topic title for a help instance
If you [reuse the same topic in multiple outputs](reuse-topics.html), you may want to adjust the title for a specific [instance](instances.html). For example, add a related technology name or some important keywords to make it more discoverable.
1. Right-click a topic in the Writerside tool window and select Edit Title.
2. Under Advanced Settings, specify a title for the current instance and click OK.
This will add the following line to the topic:
```XML
Document almost everything
```
Procedure: 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](table-of-contents.html). The main topic title will remain the same.
1. Right-click a topic in the Writerside tool window and select Edit Title.
2. Under Advanced Settings, specify a TOC title and click OK.
This will add the `toc-title` attribute to the corresponding `` in the [tree file](help-modules.html#tree-file) file of the current instance:
```XML
```
## 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`.
Procedure: 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](#change-file-name) or specify a custom web file name for it.
1. Use the `` element to set a custom name of the web page for the topic:
```XML
Document_almost_everything.html
```
> **Note:**
> Make sure that the custom web file name is unique within an instance and does not conflict with other topic URLs.
2. [Add a redirect](redirects.html) from the previous topic URL to this topic to prevent 404 errors in links that point to the old URL.