Inspections
Inspections detect and highlight various problems in the file currently open in the editor, such as invalid markup, missing elements, duplicate IDs, and non-existent references. Inspections are a feature of the IntelliJ platform, so you can read about them in IntelliJ IDEA Help: Inspections.
Most inspections are enabled by default, and Writerside continuously scans the files in your project and shows the number of problems detected in the current file in the top-right corner of the editor:
You can click this widget or press Alt+6 to open the Problems tool window that lists all problems in the current file.

Inspections have different severity levels ranging from errors that are critical and will most likely break something, through warnings that should be addressed to avoid potential problems, to typos and considerations for improvement. For more information about severity levels, see IntelliJ IDEA Help: Change inspection severity.
When you see an inspection highlighting something in a file, hover over it to see the popup with the inspection name. Put the cursor at the highlighted element and press Alt+Enter to see the available context actions, including automatic quick-fixes.

Run inspections on all project files
If you want to find and fix all issues in your project, you don't need to open every topic file manually. Instead, run Writerside inspections on the whole project and get a full report.
From the main menu, select
.In the Specify Inspection Scope dialog, select Whole Project.
If necessary, change the inspection profile, that is, the set of inspections to use. There are many inspections in the default profile that are not relevant for you, so you can disable all inspections except the ones specific to Writerside.
Click Analyze and wait for the analysis to finish. Depending on the size of your project, it may take a while. You will see the results in the Problems tool window.
Writerside includes the following inspections that are specific to topic files, tree files, and various configuration files in a Writerside project.
Content validity
- Missing entity reference
Detects attribute values that reference non-existent entities.
For example, there must be a topic file named
introduction.topic
with an existing anchormy_anchor
to reference it like this:<a href="introduction.topic" anchor="my_anchor"/>This also applies to
from
,element-id
,instance
,use-filter
, and other similar attributes.Enabled by default with severity
Error.
- Link content matches the referred element's title
Detects link titles that match the referred topic's titles.
When you add a link to another topic, Writerside uses the topic's title as the link title unless you put some text inside the
<a>
tag. It is not necessary to manually add the topic's title there.Disabled by default with severity
Weak warning.
- Unreachable external link
Detects unreachable external links.
You can add an external link to your documentation by providing a URL in the
href
attribute. This inspection sends a request to the specified URL and reports a problem if the response status code is 400 or more.Disabled by default with severity
Warning.
- Large image without a thumbnail
Detects large images without thumbnails.
Thumbnails are small previews which you can use to replace large images on the topic pages. When the user clicks on the thumbnail, it expands to the full image.
You can either set
thumbnail="true"
to generate a small thumbnail from the original image, or usepreview-src
to specify a custom preview image instead of the thumbnail.You can set the maximum image width allowed by the inspection in Settings/Preferences | Editor | Inspections.
Disabled by default with severity
Warning.
- Unresolved Markdown reference
Highlights unresolved references in Writerside Markdown topics as errors.
Enabled by default with severity
Error.
- Element content shadowed by ancestors
Detects content filters that are shadowed by filters of parent elements.
Example:
<p instance="foo">Click <control instance="bar">OK</control>.</p>In this example,
bar
is shadowed byfoo
. This means that any build which will includefoo
content, will not includebar
content. Make sure that all parent elements include filters that you expect for any of its child elements. So in this case, you should addbar
to the parent paragraph.Enabled by default with severity
Warning.
- Missing title
Checks for missing
title
attribute inchapter
,def
, andtab
elements.Enabled by default with severity
Error.
- Format element checker
Checks the
<format>
element style and color validity. A valid<format>
element must specifycolor
,style
, or both attributes, and they must contain valid values.Inspection reports invalid and conflicting style values.
style
can be a valid combination of the following:bold
,italic
,strikethrough
,underline
,superscript
,subscript
.color
can be a valid color name, for example:red
,green
,blue
, and so on.Enabled by default with severity
Warning.
- Missing alt attribute inspection
Detects
<img>
elements without thealt
attribute.Always use the
alt
attribute to provide a textual alternative to non-text content (in our case, to screenshots and icons) on web pages.The purpose of using the
alt
attribute is to:Make the page accessible to people who use screen readers.
Display information about non-textual page elements when they cannot be displayed.
Provide search engines with semantic information about the page contents.
Enabled by default with severity
Warning.
- Unreachable external image
Detects unreachable URLs to external images.
You can add an external image to your documentation by providing its URL in the
src
attribute. This inspection sends a request to the specified URL and reports a problem if the response status code is 400 or more.Disabled by default with severity
Warning.
- Unreachable external video
Detects unreachable URLs to external videos.
You can add an external video to your documentation by providing its URL in the
src
attribute. This inspection sends a request to the specified URL and reports a problem if the response status code is 400 or more.Disabled by default with severity
Warning.
- Include uses 'filter' instead of 'use-filter'
Detects includes with the
filter
attribute.Usually,
filter
is used on elements inside snippets, and when you include the snippet, you specifyuse-filter
.Enabled by default with severity
Error.
- Invalid filter value
Reports problematic filter declarations that may result in unexpected behavior:
Explicit
empty
values infilter
attributesRedundant or misplaced negation
!
operators
Enabled by default with severity
Warning.
- Image is animated and thumbnail at the same time
Detects the simultaneous use of the
thumbnail
andanimated
attribute.An image can be either thumbnail or animation, not both.
Enabled by default with severity
Warning.
- Content of the <code> element must be text-only
Detects any XML-like code inside the
code
tag.Don't use any XML markup to highlight text within the
code
section. If you see legacy code using XML markup to set highlighting in the code snippet, use the intention to remove it.If you need to put sources that can be recognized as XML code inside the
code
tag, use theCDATA
section. There is a quick fix available for that.Enabled by default with severity
Warning.
- <available-only-for> should be a child element
Detects
available-only-for
attributes in<topic>
,<chapter>
, and<procedure>
elements.<available-only-for>
should be a child element of a<topic>
,<chapter>
, or<procedure>
.Enabled by default with severity
Warning.
- Plain procedure is used
Detects occurences of
plain
procedures (without numbered steps or bulleted choices).Plain procedures are deprecated. Consider using quick fixes either to change the procedure style to
choices
or to unwrap the procedure.Enabled by default with severity
Warning.
- Non-latin character in an attribute value
Detects non-Latin characters in attribute values.
Enabled by default with severity
Warning.
- Title mentions a version
Detects version numbers in titles.
You should probably use a variable instead of a hard-coded version number.
Enabled by default with severity
Weak warning.
- Tip of the day image without dimension specification
Images without the
width
attribute are incorrectly displayed in Tips of the Day.This inspection detects such images and offers a quick-fix to add the
width
attribute based on the image dimensions.For images witn @2x name suffix the actual value is divided by 2.
Enabled by default with severity
Warning.
- Non-step element in a procedure
Detects usage of tags other that
step
inside the procedure.Only
step
elements andp
elements with short and precise introductions are allowed inside procedures.Enabled by default with severity
Weak warning.
- Image dimensions problems
Detects problems caused by improper image dimension settings.
We have three recommended image widths that best fit our layout:
296
460
706
This inspection checks that:
An
<img>
element has thewidth
attribute.The
width
attribute is one of the above values.Real image dimensions are in acceptable range for its specified width, that is, the image is not stretched or shrunk too much relative to its original size.
Disabled by default with severity
Weak warning.
- Content element is misused
Detects the misuse of markup elements based on rules from the XML schema.
Disabled by default with severity
Warning.
- Link to topic outside the current instance
Detects links pointing to existing topics that are outside of current product tree.
Enabled by default with severity
Error.
- Code snippet file is empty
Detects empty files referenced via
src
in code blocks.Enabled by default with severity
Warning.
- GIF can be replaced with video
Checks if there is an MP4 video to replace an animation with.
Enabled by default with severity
Warning.
- Unexpected media file type in XML tags
Detects media references in Writerside XML tags that do not match their expected media types, e.g., image references in
<video>
tags.Enabled by default with severity
Warning.
- Unexpected media file type in Markdown images
Detects references in Markdown images that do not match their expected media type, e.g., links to local video files.
Enabled by default with severity
Warning.
- Video has no preview image
Detects videos without a preview image.
Enabled by default with severity
Error.
- Link has no type
Detects links without the `type` attribute inside the
spotlight
element on a section starting page.Enabled by default with severity
Error.
- Top-level header is implicitly converted to a chapter
Detects top-level headers in Writerside Markdown topics that will be converted to chapter headers in the generated documentation.
In Writerside Markdown topics, the first top-level (level 1) header is interpreted as the topic title. All subsequent top-level headers are implicitly converted to chapter titles (level 2 Markdown headers).
Enabled by default with severity
Warning.
- Title tag is ignored
Detects
<title>
tags that do not affect the topic title.In Writerside XML topics, only the first
<title>
tag in the file defines the topic title. All subsequent<title>
tags are ignored and can be removed.Enabled by default with severity
Warning.
Table of contents
- Unreachable URL in TOC
Detects external URLs in the table of contents that can't be reached.
You can add a link to any URL to the table of contents with the
href
attribute. This inspection sends a request to the specified URL and reports a problem if the response status code is 400 or more. For values that start withmailto:
, it ensures that the email has valid syntax.Disabled by default with severity
Warning.
- Redundant TOC title
Detects TOC titles that match the topic title.
By default, Writerside renders the topic title in the TOC. If the topic title is too long for the TOC, you can assign a shorter TOC title for it by specifying the
toc-title
attribute in<toc-element>
. The TOC title is used only for the corresponding TOC entry and does not change the topic title.If the TOC title matches the topic title, this inspection highlights the redundant
toc-title
attribute and suggests removing it.Enabled by default with severity
Warning.
- Duplicate redirect
Detects duplicate redirects.
You can use the
accepts-web-file-names
attribute on a<toc-element>
to specify HTML pages from which you want to redirect to this TOC entry. For example, when you remove a topic, you probably want to redirect its web filename to another topic. If you use the same web filename for multiple redirects, it will lead to a conflict. This inspection detects duplicate redirects and suggests removing the duplicates.Enabled by default with severity
Error.
- Redirect from existing topic
Detects redirects from web filenames of existing topics.
You can use the
accepts-web-file-names
attribute on a<toc-element>
to specify HTML pages from which you want to redirect to this TOC entry. For example, when you remove a topic, you probably want to redirect its web filename to another topic. If you use a web filename of an existing topic, it will lead to a conflict. This inspection detects such conflicts and suggests removing the redirect.Enabled by default with severity
Error.
- Duplicate topic in TOC
Detects topics that are added to the TOC more than once.
Every entry in the table of contents references a specific topic. If you add a topic to the same help instance tree more than once, it will lead to conflicts. This inspection detects TOC elements that reference the same topic and suggests removing the TOC element.
Enabled by default with severity
Error.
Configuration
- Duplicate category sort order
Detects non-unique sort order values of
<seealso>
categories inc.list
.The
c.list
file defines categories for the<seealso>
block at the end of topics. Use theorder
attribute to set the order in which Writerside renders the categories. Make sure that order values are unique within thec.list
file to avoid conflicts.Enabled by default with severity
Warning.
Element id problems
- Element without an 'id' attribute
Highlights elements that don't have the
id
attribute.By default,
id
is mandatory only for the<chapter>
element. You can specify the elements to check in Settings/Preferences | Editor | Inspections.Enabled by default with severity
Weak warning.
- Element id occurs more than once
Detects duplicate element IDs.
You can use IDs to set up links to topic elements or to reuse them in other topics, so element IDs must be unique within a file.
Replace matching IDs and make sure that new IDs are easy to distinguish.
Enabled by default with severity
Error.
- Element id occurs more than once
Detects duplicate element identifiers in Markdown Writerside topics.
You can use IDs to set up links to topic elements or to reuse them in other topics, so element IDs must be unique within a file.
Replace matching IDs and make sure that new IDs are easy to distinguish.
Enabled by default with severity
Error.
- Unresolved anchor reference
Reports unresolved references in Markdown links.
Enabled by default with severity
Warning.
- Root file tag must have an 'id' attribute
Checks that the root element has the
id
attribute.The
id
attribute is necessary for proper project configuration.Disabled by default with severity
Error.
Unused symbols
- Unused content snippet
Detects content snippets that are not included anywhere.
Usually, you create snippets to include their content somewhere. If you don't, probably, you can remove the snippet.
Enabled by default with severity
Weak warning.
- Unused topic
Detects topics that are not included in any instance tree.
If the topic is not used anywhere, consider deleting it from the project.
Disabled by default with severity
Weak warning.
Style checks
- Hardcoded text can be replaced with property
Detects
<control>
values that can be replaced with the corresponding property keys.If the value in
<control>
is present in one of the property bundles, Writerside suggests replacing it with the corresponding property key.Enabled by default with severity
Warning.
- Dangling text without paragraph
Detects text outside of paragraphs.
Writerside uses paragraphs to apply styles to the textual information. During the build, it automatically wraps text with the
p
tag in most places. However, it cannot process some complicated cases, when it is not obvious what is a paragraph. To avoid this, use paragraphs in list items, table cells, procedure steps, definitions when there's more than one paragraph or other block elements. Always use thep
tag in chapters, tips, notes, and warnings.Enabled by default with severity
Warning.
- Style checker for markdown
Checks whether the textual topic content follows the style guidelines.
Enabled by default with severity
Warning.
- Style checker for markdown
Checks whether the textual topic content follows the style guidelines.
Enabled by default with severity
Warning.
- Missing space checker
Detects the absence of whitespace characters around tags.
Enabled by default with severity
Warning.