Working with skip links in Confluence Data Center

Availability

Confluence 7.20 or later

In Confluence 7.20, we will ship a number of skip links that can be used in the editor and across general pages. These include "Skip to search", "Skip to main content", "Skip to edit title", "Log in" and more.

As part of this framework, app developers can inject their own skip links to improve accessibility for customers using their app in Confluence. See below for instructions.

You can find detailed information in the links bellow:

We are currently supporting skip links in AUI Page Layout, please see more details in the example here(look for instances of aui-skip-link): https://aui.atlassian.com/aui/latest/docs/page.html

Skip links are also supported in AtlasKit: https://atlaskit.atlassian.com/packages/design-system/page-layout/docs/skip-links

Browser support for skip links

To make skip links work on Firefox and Safari Browsers follow up on this page:

https://www.a11yproject.com/posts/macos-browser-keyboard-navigation/

Unfortunately, the tab management on macOS is different by default than what we expect :(

You can activate the skip links by navigating from the address bar using Tab key or by using keyboard shortcuts. At the moment we support these keyboard shortcuts:

u+8 from any page
Command+Shift+u+8 from inside of an editor

How do I inject skip links from an app?

Option 1

If an app has its own page - you can choose to use the AUI or Atlaskit implementation mentioned above(AUI/AtlasKit). If an app injects itself as part of an existing page, you usually don't have access the the page header and using AUI or Atlaskit will be very problematic.

Option 2

From Confluence 7.20.0 we support a new Javascript API to allow injection of skip links.

Web resource key: com.atlassian.confluence.plugins.confluence-frontend:skip-links

All of the HTML elements with a 'aui-skip-link-target' attribute will be auto mapped once you call the rerenderSkipLinks() Javascript function (see next section 'API'). The skip link text will be the result of this function:

1
2
I18n.getText('confluence-frontend.skiplinks.skipTo', el.getAttribute('aui-skip-link-target'))

For example if the attribute value is "toolbar" - the result will be a localized version of "Skip to toolbar".

This function will be automatically executed on document DOMContentLoaded and on AJS events rte-ready and rte-quick-edit-ready.

If for your element this timings don't work (your element hasn't been rendered yet) you will need to run the rerenderSkipLinks() again. The rerenderSkipLinks() will not duplicate content - so you can run it as many times as needed.

API

1
2
 /**
 * Render configured skip links in the header, reusing the AUI implementation.
 * The rendered skip links will be the once you configured with "addSkipLink" function and auto
 * mapped elements with aui-skip-link-target attribute (value of the property will be used as part
 * of the 'confluence-frontend.skiplinks.skipTo' key) in combination with aui-skip-link-ignore-visibility attribute (see context.ignoreVisibility)
 * @returns {void}
 */
 rerenderSkipLinks() { ... }

/**
 * remove a skip link (use same object as you used for addSkipLink)
 * * important - nothing will happen until rerenderSkipLinks is executed
 * @param {object} context
 * @returns {void}
 */
removeSkipLink(context)

 /**
 * Add a skip link. use one of the properties: href/skipToCssPath/onclick
 *
 * <b> important - nothing will happen until rerenderSkipLinks is executed </b>
 * @param {object} context the context used to generate the skip link
 * @param {string} context.label the label of the skip link
 * @param {string} context.href the href property of the generated skip link
 * @param {string} context.onlyIfExists css path - this skip link will only be generated if an element on this css path exists
 * @param {bool} context.ignoreVisibility  by default skip link only generated if "onlyIfExists" is visible. This option overrides it
 * @param {string} context.skipToCssPath css path - when the skip link is clicked - the element on this css path will be focused
 * @param {function} context.onclick when the skip link is clicked - this function will be executed
 * @returns {void}
 * */
 addSkipLink(context) { ... }

Usage example

1
2
 document.addEventListener('DOMContentLoaded', () => {
    require(['confluence/skip-links-loader'], (skipLinksLoader) => {
        // add a new skip link
        skipLinksLoader.addSkipLink({
            onlyIfExists: '#nav-sidebar',
            skipToCssPath: '#nav-sidebar',
            ignoreVisibility: true,
            content: 'Skip to sidebar',
        });

        // rerender all skip links - this will map out all of the 'aui-skip-link-target' attributes
        // and rerender all of the addSkipLink configures elements as well
        skipLinksLoader.rerenderSkipLinks();
    });
});