Writerside Help

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:

Problems widget

You can click this widget or press Alt+6 to open the Problems tool window that lists all problems in the current file.

Problems tool window

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.

Show Context Actions

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.

  1. From the main menu, select Code | Inspect Code.

  2. In the Specify Inspection Scope dialog, select Whole Project.

  3. 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.

  4. 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 anchor my_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 icon Error.

Redundant link text

Detects links to topics where the topic title matches the link text.

When you add a link to another topic, Writerside uses the topic title as the link text, unless you put some text inside the <a> tag. If this text matches the topic title, Writerside suggests removing the text and collapsing the <a> tag.

Enabled by default with severity Weak warning icon 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 icon Warning.

Large image without a thumbnail

Detects large images without a thumbnail and suggests making them expandable.

Thumbnails are small previews that you can use in place of large images. When the user clicks on the thumbnail, it expands to the full image.

You can either set thumbnail="true" to make the original image expandable (optionally, also set the `width` to make the image thumbnail smaller), or use preview-src to specify a custom preview image as a thumbnail.

You can set the maximum image width allowed by the inspection in Settings | Editor | Inspections.

Disabled by default with severity Warning icon Warning.

Combinable elements

Detects elements that can be combined.

Such elements as <var>, <title>, <web-file-name>, <show-structure>, <help-id>, <card-summary>, <link-summary>, and <web-summary> are generally one per topic or chapter. If you define them multiple times with overlapping scopes, they can usually be combined for clarity.

For example:

<title instance="foo">Custom title</title> <title instance="bar">Custom title</title>

Can be combined as:

<title instance="foo,bar">Custom title</title>

Enabled by default with severity Weak warning icon Weak warning.

Unresolved Markdown reference

Highlights unresolved references in Writerside Markdown topics as errors.

Enabled by default with severity Error icon Error.

Unresolved XML reference

Highlights unresolved references in Writerside XML topics as errors.

Enabled by default with severity Error icon Error.

Anchor is overridden

Detects overridden anchors in XML <a href> links.

Enabled by default with severity Warning icon Warning.

Element filter 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 by foo, meaning that it will never be included in any instance. Make sure that all parent elements include filters that you expect for the child elements. So in this case, you should add bar to the parent paragraph.

Enabled by default with severity Warning icon Warning.

Missing title

Checks for missing title attribute in chapter, def, and tab elements.

Enabled by default with severity Error icon Error.

Format element checker

Checks the <format> element style and color validity. A valid <format> element must specify color, style, or both attributes, and they must contain valid values.

style can be a valid combination of the following: bold, italic, strikethrough, underline, superscript, subscript.

color can be a hexadecimal RGB code or a valid color name, such as #ff0000 or Red.

Enabled by default with severity Warning icon Warning.

Missing alt attribute inspection

Detects <img> elements without the alt 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 icon 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 icon 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 icon 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 specify use-filter.

Enabled by default with severity Error icon Error.

Invalid filter value

Reports problematic filter declarations that may result in unexpected behavior:

  • Explicit empty values in filter attributes

  • Redundant or misplaced negation ! operators

Enabled by default with severity Warning icon Warning.

Image is animated and thumbnail at the same time

Detects the simultaneous use of the thumbnail and animated attribute.

An image can be either thumbnail or animation, not both.

Enabled by default with severity Warning icon Warning.

Wide code block

Detects code blocks with long lines.

The frontend adds a horizontal scroll bar to code block elements with lines that don't fit inside the block. The maximum width of the code block element can fit lines up to 70 characters without a scroll bar. This inspection highlights code blocks with long lines: rearrange such code to avoid truncated examples for your readers.

You can change the maximum line length for this inspection.

Enabled by default with severity Warning icon 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 the CDATA section. There is a quick fix available for that.

Enabled by default with severity Warning icon 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 icon 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 icon Warning.

Non-latin character in an attribute value

Detects non-Latin characters in attribute values.

Enabled by default with severity Warning icon Warning.

Non-step element in a procedure

Detects usage of tags other that step inside the procedure.

Only step elements and p elements with short and precise introductions are allowed inside procedures.

Disabled by default with severity Weak warning icon 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 the width 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 icon 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 icon Warning.

Link to topic not in current instance

Detects links pointing to an existing topic that is not in the current help instance tree.

It ignores such links if the current topic itself is not in the current help instance tree.

You have several options to deal with this issue:

  • Mark the link with nullable="true", which will render it as plain text if the target is not available

  • Exclude the containing element (such as the paragraph with the problematic link) from the current help instance

  • Include the target topic into the current help instance

Enabled by default with severity Error icon Error.

Code snippet file is empty

Detects empty files referenced via src in code blocks.

Enabled by default with severity Warning icon 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 icon 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 icon 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 icon Warning.

Video has no preview image

Detects videos without a preview image.

Enabled by default with severity Error icon 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 icon 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 icon 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 icon 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 with mailto:, it ensures that the email has valid syntax.

Disabled by default with severity Warning icon 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 icon 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 icon 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 icon 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 icon Error.

Configuration

Duplicate category sort order

Detects non-unique sort order values of <seealso> categories in c.list.

The c.list file defines categories for the <seealso> block at the end of topics. Use the order attribute to set the order in which Writerside renders the categories. Make sure that order values are unique within the c.list file to avoid conflicts.

Enabled by default with severity Warning icon Warning.

Element id problems

Element without an 'id' attribute

Highlights elements that don't have the id attribute.

All elements in the generated help instance get random unique hash IDs, unless an element has the id attribute. By default, id is mandatory for structural elements, such as chapters and procedures, for elements with titles and anchor links, such as tabs and definition list items, and for snippets that are expected to be referenced by their ID. Use this inspection's settings to define a comma-separated list of elements that should have an id.

Enabled by default with severity Weak warning icon 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 icon 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 icon Error.

Unresolved anchor reference

Reports unresolved references in Markdown links.

Enabled by default with severity Warning icon Warning.

Root file tag must have an 'id' attribute

Detects missing or incorrect topic IDs in XML files. Every XML topic must have the id attribute in the root <topic> tag with the value equal to the topic file name without the extension.

The quick fix either adds or corrects the ID to match the topic file name.

For example, if the topic file name is some_intro.topic, then the root <topic> tag must have id="some_intro".

Enabled by default with severity Error icon Error.

Unused symbols

Unused snippet

Detects snippets that are not included anywhere.

For regular topics, Writerside suggests unwrapping the <snippet> element (preserving the content).

For library topics, Writerside suggests removing the <snippet> element (preserving only descendant snippets that are used somewhere).

Enabled by default with severity Weak warning icon Weak warning.

Unused topic

Warns you when the topic file is not used anywhere.

If the topic file is not included in any table of contents and does not have anything from it included in other topics, consider removing it from the project.

Enabled by default with severity Weak warning icon Weak warning.

Topic not in current instance

Warns you when the topic currently open in the editor is not in the current help instance.

You can either add this topic to the current help instance or select a help instance with this topic.

Enabled by default with severity Weak warning icon Weak warning.

Style checks

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 the p tag in chapters, tips, notes, and warnings.

Enabled by default with severity Warning icon Warning.

Style checker for markdown

Checks whether the textual topic content follows the style guidelines.

Enabled by default with severity Warning icon Warning.

Style checker for markdown

Checks whether the textual topic content follows the style guidelines.

Enabled by default with severity Warning icon Warning.

Missing space checker

Detects the absence of whitespace characters around tags.

Enabled by default with severity Warning icon Warning.

Last modified: 23 May 2024