How Do I Wagtail?

How Do I Wagtail?

Adding links

When adding links to content in Wagtail, we need to make sure they will work for all languages, even if this content is not translated because the content might be translated, or could be at some point, and this is forcing a specific language on users, for the rest of their session on our site.

Inline links

When adding an inline link, there are two options:

1) Using the “Internal link” feature

Search for the English version of the page you want to link to. Wagtail will automatically redirect users to the right version of this page for each language we support.

Internal link
2) Using the “External link” feature

It’s acceptable to use an external link to link to an internal page, as long as the locale code (e.g. /en) is removed from the URL. Keeping the locale code in the URL will degrade the experience of our international audience by switching them to a version of the website in a different language where they will be unable to access translated pages when further browsing the website.

External links

URL fields

There’s no equivalent to the “Internal link” feature for these, so please always remove the locale code, like in the screenshot below.

URL field

Linking to page headings

We automatically turn headings into linkable anchors.

When using the paragraph editing tool, make sure to use the H2 and H3 buttons in the markup bar to ensure headings are marked up correctly. Doing so will let the CMS auto-generate anchors for these headings.

Image showing how to create a header

As an important note, make sure not to mark up the heading text outside of "setting the heading", as things like bold or italics or making the heading itself a link will interfere with generating the heading anchor targets (additionally, heading styling from our style guide assumes no additional markup is used, so that's a good rule to follow in general).

In order to find out what the anchor is, you can either preview the page, or you can publish it and then view the live version - with the page open in the browser:

  1. Right-click on the heading you want the anchor for,
  2. select "inspect element" from the context menu and your browser should open the Developer Tools with a view of the current document, focused on the heading you inspected:
Inspecting a heading

You will see that the heading has a little drop down icon, which you can click to reveal the anchor element (<a>) for this heading. The anchor element should have a class called "fragment-id", as well as an "id" attribute: we need to know the value for that "id" attribute.

Auto-generated anchor id

The text in this id attribute is what we can use to directly link to the anchored heading on the page. If the id attribute reads "purchasing-adult-and-youth-tickets", for example, then the associated direct link to that heading consists of the page URL plus "#purchasing-adult-and-youth-tickets" added to the end of that URL.

Linking to a page header

To make text elsewhere on the page, or on a different page, link to a header, you can use the "link" button in the rich text editor to turn any stretch of text into a link. After selecting some text and pressing the link button:

Image showing where to highlight and add link

Pick "Anchor link" in the link dialog and add the anchor id.

image showing how to link jump words to an anchored section
All done!

Save draft or publish and your anchor links should be set up. Remember to test your links to make sure they're jumping to the sections you want them to jump to.