DOCS: CREATE: Internal Links using HTML.tid

A new tiddler documenting the process for creating anchors and using links for sub-tiddler navigation.
Arising from issue TiddlyWiki#3811 & Discussed on Google Groups: [Section Names using ID for internal Links](https://groups.google.com/forum/?hl=en#!topic/tiddlywiki/ikjxwjllFtE)

editions/tw5.com/tiddlers/wikitext/Internal Links using HTML.tid

@@ -0,0 +1,118 @@
+created: 20190308000000000
+modified: 20190308000000000
+tags: [[HTML in WikiText]]
+title: Internal Links using HTML
+
+<h2 id=#Introduction:Internal-Links-using-HTML>Introduction</h2>
+
+In a general webpage, an <<.attr id>> attribute of an HTML element acts as a marker or target. A link referencing that target allows readers to scroll to that specific part of a page. This can be useful when the page is very long. The navigation process between tiddlers in [[TiddlyWiki]] uses code similar to how, in a normal webpage, these special targets are accessed using a link. This means you cannot use internal links without taking this into account.
+
+A way to use these targets in ~TiddlyWiki as an internal link is by the slightly unconventional method of starting the <<.attr id>> attribute with a `#` character.
+
+<h2 id="#Navigation within a tiddler: Internal Links using HTML">Navigation within a tiddler</h2>
+
+Similar to how the <<.attr id>> attribute of an HTML element can be used in a normal webpage, it can be used in ~TiddlyWiki (with some limitations) for navigation within displayed tiddlers.
+
+The following applies for proper (limited) useage:
+
+<section id="#section01-Internal%20Links%20using%20HTML">
+
+; Naming the <<.attr id>> attribute for internal navigation:
+: starts with a `#` character
+: is case sensitive
+:;Suggested that:
+:: not to use URI encoding or the `%` character (see the warning below)
+:: preferably not contain any whitespace (see note 1. below) but if it does, the value should be within double quotes
+:: each value to be unique in the ~TiddlyWiki  (see note 2. below)
+
+; Constructing the link
+: The `<a>` HTML element is used with its <<.attr href>> attribute
+: The <<.attr href>> attribute starts with a `#` following by the exact <<.attr id>> value
+: If the <<.attr href>> value contains spaces, the value should be within double quotes
+
+<h2 id="""#"Example":-InternalLinksUsingHTML""">Example:</h2>
+
+```
+<h1 id="#heading-01"> My Heading</h1>
+
+<a href="##heading-01">Link to My Heading</a>
+
+```
+
+; Navigating to the reference
+: Clicking on the link will scroll to the target section of a tiddler that is
+:: in the Story River, or 
+::displayed in the sidebar, 
+:so that the <<.attr id>> location is at the top of the display area.
+:* Note: The browser's history will be updated with the link's <<.attr href>> value appended to the web page's URL
+: Will <<.em not>> scroll to the target in the tiddler if the target is in the Story River or sidebar but:
+
+:: the tiddler is folded
+:: the target is within a non-displaying <<.wlink RevealWidget>> widget
+:: the<<.button "control-panel">> , <<.controlpanel-tab "Appearance">> , <<.controlpanel-tab "StoryView">> is set to (the single page view)  <<.def zoomin>> and the tiddler is not at the top of the story river (not displayed) 
+
+<<.warning "Some browsers will not navigate to an ''id'' that includes an encoded [ext[URI|https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI]] that has a `%` character followed by 2 characters. ">>
+
+<$macrocall $name=.note _="""1. The HTML5 specifications for the <<.attr id>> attribute  says that its value should not contain any whitespace. However a value with whitespace that is surrounded by double-quotes (or triple double-quotes) works ^^(Mar 2019)^^ as an internal navigation marker in ~TiddlyWiki. However it may not work for other code that wants to reference the same <<.attr id>>.
+
+2. If transclusions create multiple instances of the <<.attr id>>, navigation will take place to the first instance found that satisfies the above criteria.
+
+3. The Keyboard Combination <kbd>Ctrl</kbd>+ <kbd>Click</kbd> on such a link will open a new browser window/tab & not the targeted tiddler."""  />
+
+
+</section>
+
+<h2 id="#Another%20Example:-Internal%20Links%20using%20HTML">Another Example:</h2>
+
+Here is an example using a `<section>` HTML tag, that is generally used to define sections in an HTML document, such as chapters, headers, footers, or any other sections of the document.
+
+```
+<section id="#unique001">
+
+!TiddlyWiki
+A rich, interactive tool for manipulating complex data with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors.
+</section>
+```
+<hr>
+<section id="#unique001">
+
+!TiddlyWiki
+A rich, interactive tool for manipulating complex data with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors.
+</section>
+
+A link to scroll to this section could be made as follows:
+
+```
+Clicking this link goes to: <a href="##unique001">Section 1</a>
+```
+Clicking this link goes to: <a href="##unique001">Section 1</a>
+
+
+<hr>
+<h2 id="#Suggestions%0">Suggestions for HTML elements to use</h2>
+
+Some suggestions for the HTML element you choose for marking a position using the <<.attr id>> attribute:
+
+| ! Element | ! Sample code | ! Observations |
+|<<.def anchor>> |<$text text="""<a id="#part001-of-TiddlerName"></a>"""/> |Should work perfectly everywhere|
+|<<.def heading>> |<$text text="""<h2 id="#0 0 1">A New Heading</h2>"""/>|whitespace is against convention, but works|
+|<<.def section>> |<$text text="""<section id="#sect001%20of%20TiddlerName">This is a new section</section>"""/>|URI encoding may not work in some browsers|
+|<<.def span>> |<$text text="""<span id="#007">Marker 007 is here!</span>"""/>|''id'' values should be unique|
+|<<.def division>> |<$text text="""<div id="#007"></div>"""/>|Not advisable to use the same ''id'' value again|
+
+The links below will take you to specified parts of this tiddler.
+
+* <a href=##Introduction:Internal-Links-using-HTML>Introduction</a>
+* <a href="##Navigation within a tiddler: Internal Links using HTML">Navigation within a tiddler</a>
+* <a href="##section01-Internal%20Links%20using%20HTML">Naming the ''id'' and Constructing the link</a>
+* <a href="""##"Example":-InternalLinksUsingHTML""">Example</a>
+* <a href="##Another%20Example:-Internal%20Links%20using%20HTML">Another Example</a>
+* <a href="##Suggestions%0">Suggestions</a>
+
+!! Hint
+
+If you want to include an <<.attr id>> attribute to a link in your sidebar Table of Contents, you can include it in your listed tiddler's <<.field caption>> field similar to the way shown below:
+
+```
+<span id=#some-value>Your caption</span>
+```