This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

Anchor Links using HTML

30th November 2020 at 6:43am

What do they do?

In TiddlyWiki anchor links can help us link to target points and distinct sections within rendered tiddlers. They can help the reader navigate longer tiddler content.

For example this link, Bottom, should take you to the bottom of this tiddler. The "Back to the top" link below should return you back to the top of this tiddler.

Back to the top

How do I make them?

There are only 2 steps to making anchor links.

  • First, create the target point (called an 'anchor') where you want it.
  • Second, add a link to it where the reader might need it.

That's it.

Step 1: Create an 'anchor' (link target)

<a id="#Bottom_of_tiddler"></a>

Step 2: Create a link to the target anchor

<a href="##Bottom_of_tiddler">Bottom</a>
  • Create an <a href> link using exactly the same 'address' value as the target but with double ## characters preceding it.
  • Place this code where it will most help the reader.

The above example can be adapted to work for many situations in TiddlyWiki, such as the table of contents at the top of this tiddler.

Is it really that simple?

Yes, it's that simple. BUT... in TiddlyWiki there are some small differences from standard HTML5 anchor links and some specific TiddlyWiki limitations.

Back to the top

Limitations and things to watch out for

Step 1: Creating the target anchor

  • Unlike standard HTML5, in TiddlyWiki you must put a single # character in front of the target address value that follows the id attribute. (Notice the single # character used in the #Bottom_of_tiddler in Example 1.)
  • Unlike standard HTML5, TiddlyWiki anchor links are case sensitive. In the example above #Bottom_of_tiddler works, but #bottom_of_Tiddler wouldn't.
  • Avoid using the % character in your link, as some browsers have a bug where navigation to anchors containing a % character can sometimes fail (see warning below).
  • Avoid using any whitespace in your link (see note 1 below).
  • Each link address should be unique in the TiddlyWiki. If transclusions create multiple instances of the same id attribute, navigation will take place to the first instance found that satisfies the above criteria. To avoid this, you can use the qualify macro in both the id and the href attributes in a similar style to the example given below: Avoiding duplicate IDs when transcluding.

Step 2: Creating the link to the target

  • Remember that the href value should start with two # characters, one more than the id value of the target anchor.
  • Remember that TiddlyWiki anchor links are case sensitive

Step 3: Navigating to the target

Normally you can click on the link and TiddlyWiki will scroll the window so the target anchor is at the top of the window, but there are several limitations:

  • Anchor links in TiddlyWiki do not work if the tiddler is not in the Story River, or is not displayed in the sidebar.
  • Anchor links in TiddlyWiki do not work if the tidlder is in the Story River or sidebar but anchor marked target point is not visible on the page (e.g., the tiddler is folded or the anchor is within a non-displaying $reveal widget). Ctrl+Click on such an anchor link will open a new browser window/tab loading the base web page and will not navigate to the expected tiddler.
  • Anchor links in Tiddlywiki do not work if Control Panel > Appearance > Story View is set to Zoomin (the single page view) and the tiddler is not at the top of the story river (i.e. not displayed).
  • When an anchor link is clicked the browser's navigation history will be updated with the link's href value appended to the web page's URL. This will happen even if the Control Panel > Settings > Navigation History value is set to "Do not update history".

Note
1. The HTML5 specification for the id attribute says that its value should not contain any whitespace. Currently (Dec 2020) an id value with whitespace can sometimes work. However, it may not work in all browsers and is not guaranteed to work in the future.

Warning
Some browsers may fail to navigate to an anchor target whose id value includes a % character followed by 2 digits. This is a bug in the browser and nothing that TiddlyWiki can fix. To be safe, avoid using the % character.

Back to the top

More examples

In each case the target code is placed at the destination the reader navigates to, the link code is placed where it will help the reader navigate from.

<h2 id="#heading-01"> My Target Heading</h2>

<a href="##heading-01">Link to My Target Heading</a>

This looks like:

My Target Heading

Link to My Target Heading 

<section id="#unique001">

!! My Target section

A `<section>` HTML tag is generally used to define sections in an HTML document, such as chapters, headers, footers, or any other sections of the document.
</section>

Clicking this anchor link goes to: <a href="##unique001">Link to My Target Section</a>

This looks like:

My Target section

A <section> HTML tag is generally used to define sections in an HTML document, such as chapters, headers, footers, or any other sections of the document.

Clicking this anchor link goes to: Link to My Target Section

Back to the top

Suggestions for HTML elements to use

Some suggestions for the HTML element you choose for marking a position using the id attribute:

Element Sample code Observations
anchor<a id="#part001-of-TiddlerName"></a>Should work perfectly everywhere
heading<h2 id="#a-new-heading">A New Heading</h2>Headings can have id attributes as well
section<section id="#sect001-of-TiddlerName">This is a new section</section>If you use the section element it should probably have an id of its own
span<span id="#007">Marker 007 is here!</span>span elements can be used to insert an id mid-paragraph

Back to the top

Suggestions for target names to use

Sample code Observations
Recommended<a id="#part001-of-TiddlerName"></a>Include the tiddler name for easy unique ids
Avoid: whitespace<h2 id="#0 0 1">A New Heading</h2>Whitespace is not guaranteed to work in all browsers
Avoid: %<section id="#sect001%20of%20TiddlerName">This is a new section</section>URI encoding (turning space into %20 and so on) may not work in some browsers
Avoid: duplicate IDs<span id="#007">Marker 007 is here!</span>id values should be unique within entire wiki
Avoid: duplicate IDs<a id="#007"></a>A different marker 007If id values are duplicated, one will be ignored

Back to the top

Avoiding duplicate IDs when transcluding

The id and anchor link to this header has been made as follows:

<a href=<<qualify "##qualify-example">>>Avoiding duplicate IDs when transcluding</a>

<h2 id=<<qualify "#qualify-example">>>Avoiding duplicate IDs when transcluding</h2>
For this to work:
  • The href and id values use the macro invocation syntax for attributes, using the qualify Macro to create a unique id value.
  • Both the id and the anchor link must be in the same tiddler.
  • There must not be any quote characters between the = and the <<.
  • The double quotes around the target name are optional, but recommended.
  • There should be a total of three > characters after the target name, two >> to close the <<qualify macro, and one > to close the <a tag.

Back to the top

Style Hints

If you don't want the link to look like an external link, give the <a> element's class attribute the value tc-tiddlylink and if you want the link to also be italic & bold, give the additional classes tc-tiddlylink-missing tc-tiddlylink-shadow like below:

<a class="tc-tiddlylink" href="##Introduction:Anchor-Links-using-HTML">Back to the top</a> or just back to <a class="tc-tiddlylink tc-tiddlylink-missing tc-tiddlylink-shadow" href=<<qualify ##Hints>>>Hints</a>.

Back to the top or just back to Style Hints.

If you want to include an id attribute to a link in your sidebar Table of Contents, you can include it in your listed tiddler's caption field similar to the way shown below:

<span id=#some-value>Your caption</span>

Back to the top