Links and references

Semantic link

In semantic markup, to create a link to another topic, to an anchor inside a topic, or the external resource, use <a>.

The link text may contain text with inline formatting, shortcuts, UI paths, controls, and images.

href: Specify the topic ID for internal reference or the page URL for external.
anchor: Refer to a specific element ID or anchor element on the page.
Do not use a snippet id to reference an anchor, the link will be broken.
nullable: [true|false] By default, we check that links are valid and lead to either topic, anchor, or an existing external resource. If true, the link won't be validated and will be considered plain text.
summary: Specify a summary to display when hovering over a link.
caps=[title,sentence,upper,lower]: Specify how to display title: title case, sentence case, all upper letters, all lower letters, or as written.
id: Specify a unique identifier to use as a link anchor and generate a meaningful URL for this link. You can reference and reuse any element that has an ID.
filter: Define a set of custom filters for conditionally including this link.
instance: Define a set of instances for conditionally filtering this link.
switcher-key: Make this link switchable depending on the selected key.
target-switcher-key: Specify which topic variant to open first when you point to the topic with sections.

If no text is specified for an internal link, we will display the topic title instead. For external, we will display an address.

Markdown links

Markdown uses the following markup for links:

[Link text](link target)

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

A link can reference an external URL, another topic file (as long as it's in the same help instance), or any element with an ID, which creates an anchor on the page.

A chapter in Markdown has a default ID based on the header. To assign a custom ID to any element, specify {id="some_id"} syntax.

            ## 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 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][anc].

                [jb]: https://www.jetbrains.com
                [anc]: #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 in the documentation project root. Make sure that you register the file in writerside.cfg as <categories src="c.list"/>.

Here is an example of the c.list file:

            
                <?xml version="1.0" encoding="UTF-8"?>
                <!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: 21 December 2023

Writerside Help

Links and references

Semantic link

Markdown links

Reference-style links in Markdown

See also