Redirect to other content

When you remove or rename a topic, your readers might encounter the 404 error page when opening a previously published URL. To avoid this, Writerside suggests adding redirects from the previous web file name to another topic.

Redirection rules are stored in the redirection-rules.xml file and have the following syntax:

        <rule id="36921bf6">
            <description>Created after removal of "Introduction" from Writerside</description>
            <accepts>introduction.html</accepts>
        </rule>
    

The accepts-web-file-names-ref attribute on a <toc-element> ensures that all applicable web file names from the corresponding redirection rule will be redirected to this entry in the table of contents:

        <toc-element topic="getting-started.topic" accepts-web-file-names-ref="36921bf6"/>
    

In the previous example, all links to introduction.html will redirect to the web file generated from getting-started.topic.

Add redirect manually

Open the tree file and locate the <toc-element> that should serve as the new target.
Add the accepts-web-file-names attribute to this <toc-element> and specify the HTML file name from which to redirect.
<toc-element topic="new-topic.topic" accepts-web-file-names="old-topic.html"/>
If you want to redirect multiple web file names to this <toc-element>, separate them with commas, or manually create a redirection rule and reference it from the tree file to avoid cluttering it with a long list of web filenames.

Redirect to an external URL

If the relevant content is available outside of your documentation, you can add a redirect to an external URL. For example, if you removed a topic and moved the content to a blog post, a knowledge base article, or a page in your learning center. Or maybe some feature was removed, and it is available in another product, then you can redirect to the relevant documentation page of that product.

Add the target-for-accepts-web-file-names attribute to a <toc-element> without an associated topic and make it hidden so that your readers do not see in the TOC.
<toc-element toc-title="Redirect to blog post" hidden="true" accepts-web-file-names="cool-feature.html" target-for-accept-web-file-names="https://my.company.com/blog/about-cool-feature"/>
In the previous example, readers with a link to cool-feature.html in your documentation will be redirected to the relevant post in your company's blog.

Last modified: 13 June 2024