Summary elements

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.

However, there are ways to provide the summary as a different paragraph or some custom text that will not be part of the topic content.

Link summary

Use the <link-summary> element to define text that you want to appear in a popup when the reader hovers over a link to this topic.

Link with summary

The text in the <link-summary> element will not appear in the topic content. Use the rel attribute to specify an existing paragraph as the link summary:

            <link-summary rel="some-paragraph"/>
            ...
            <p id="some-paragraph">Use this paragraph as a link summary</p>
        

Use the summary attribute on a <a> link to override the link summary:

Card summary

Use the <card-summary> element to define text that you want to appear in cards as links to topics. These cards are used in Starting pages and See also with style="cards".

<card-summary>Use card summaries to provide context for cards.</card-summary>

For example, see the See also block at the bottom of this page.

The text in the <card-summary> element will not appear in the topic content. Use the rel attribute to specify an existing paragraph as the card summary:

            <card-summary rel="some-paragraph"/>
            ...
            <p id="some-paragraph">Use this paragraph as a card summary</p>
        

Use the summary attribute on a <a> link to override the card summary:

            <seealso style="cards">
                <category ref="related">
                    <a href="some.topic" summary="Show this text in the card summary"/>
                </category>
            </seealso>
        

Web summary

Use the <web-summary> element to define text for the <meta name="description"> tag for the HTML page that search engines can use to produce snippets in search results. Messengers and social media platforms can also use the meta description tag to provide preview text for links to your documentation pages.

The text in the <web-summary> element will not appear in the topic content. Use the rel attribute to specify an existing paragraph as the web summary:

            <web-summary rel="some-paragraph"/>
            ...
            <p id="some-paragraph">Use this paragraph as a web summary</p>
        

Last modified: 14 May 2024