Links and references

When writing content, reference other related content to improve search and navigation for your readers.

Use the <a> element to add a link to another topic, an anchor inside a topic, or an external URL. In Markdown topics, use the standard notation for Markdown links: []().

[Link text](target.topic)

Here is how the previous link will look: Link text

Formatting links

You can format the link text with inline elements.

<a href="target.topic"><code>doThis()</code></a>

[`doThis()`](target.topic)

Here is how the previous link will render: doThis()

Link text

Without any text, Writerside will use the title of the referenced element or the URL if it is an external link. For example, here is how you can add a link to https://www.jetbrains.com:

[](https://www.jetbrains.com)

Link summary

By default, Writerside uses the first paragraph in a topic as a summary for link and card popups, and web descriptions. It is good practice to provide a summary of the content as the intro paragraph, so that readers have a way to quickly evaluate whether the content is applicable to what they are looking for.

Use the <link-summary> element to override what appears in this popup for a topic. Alternatively, use the summary attribute on a <a> link to override the summary just for this link.

For more information, see Link summary.

Nullable links

When you reuse topics in different instances, a link may point to a topic that does not exist in the current instance. In this case, the build will fail unless you filter out the link for the instance. Alternatively, you can make a link nullable, and then Writerside will render just the link text if the target topic does not exist.

[link text](some.topic){nullable="true"}

Markdown links

Insert link in Markdown

Press Alt+Insert to open the Insert menu, and then select Link.
Alternatively, press Ctrl+Shift+U.
If you previously copied a URL to the clipboard, Writerside will insert the URL as the target of the link.

By default, every chapter in a Markdown topic has an ID based on the chapter heading. To assign a custom ID to a chapter or any other element, use the id attribute.

            ## Chapter one

            Text in chapter one

            ## Chapter two {id="second"}

            Text in chapter two

            ## Example links

            Here is [a link to the first chapter](#chapter-one).

            Here is [a link to the second chapter](#second).

            Here is [a link to another topic](another_topic.md).

            Here is [a link to an anchor in another topic](another_topic.md#anchor).

            Here is [a link to the JetBrains website](https://www.jetbrains.com/).

To define the custom link summary, specify it in quotes after the link target:

[Link text](Topic.md "A summary to display when hovering over the link")

Reference-style links in Markdown

In Markdown, you can use reference-style links to insert them multiple times within a topic. To do this, you need to declare the link inside that topic with a reference name and reference the link by this name:

                You can reference [the JetBrains website][jb] multiple times
                and even use [different link text][jb] every time.
                Or reference an [anchor ID][anchor].

                [jb]: https://www.jetbrains.com
                [anchor]: #some-id
            

             <seealso>
                    <category ref="related">
                        <a href="Links.topic">Topic about links</a>
                        <a href="Some_other.topic"/>
                    </category>
                    <category ref="external">
                        <a href="https://www.google.com">Google</a>
                        <a href="https://www.jetbrains.com"/>
                    </category>
             </seealso>
        

See how this section looks at the bottom of the current page. You can set <seealso style="cards"> to render related links as cards instead of a list of links.

Define the list of categories in the c.list file. Make sure that you register the file in writerside.cfg as <categories src="c.list"/>.

Here is an example of the c.list file:

            <!DOCTYPE categories SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
            <categories>
                <category id="related" name="Related topics" order="1"/>
                <category id="external" name="External resources" order="2"/>
            </categories>
        

Last modified: 05 August 2024

Writerside Help