Show anchor links for each heading

asset/css/markbind.css

@@ -23,6 +23,19 @@ pre > code.hljs {
     outline: none !important;
 }
 
+.fa.fa-anchor {
+    color: #ccc;
+    display: none;
+    font-size: 14px;
+    margin-left: 10px;
+    padding: 3px;
+    text-decoration: none;
+}
+
+.fa.fa-anchor:hover {
+    color: #555;
+}
+
 .markbind-table {
     width: auto;
 }

asset/js/setup.js

@@ -15,9 +15,21 @@ function flattenModals() {
   });
 }
 
+function setupAnchorVisibility() {
+  jQuery('h1, h2, h3, h4, h5, h6').each((index, heading) => {
+    jQuery(heading).on('mouseenter', function () {
+      jQuery(this).children('.fa.fa-anchor').show();
+    });
+    jQuery(heading).on('mouseleave', function () {
+      jQuery(this).children('.fa.fa-anchor').hide();
+    });
+  });
+}
+
 function executeAfterMountedRoutines() {
   flattenModals();
   scrollToUrlAnchorHeading();
+  setupAnchorVisibility();
 }
 
 function setupSiteNav() {

docs/userGuide/contentAuthoring.md

@@ -589,4 +589,12 @@ Note:
 - Footers should not be nested in other components or HTML tags. If found inside, they will be shifted outside to be rendered properly.
 - [MarkBind components](#use-components) and [includes](#include-contents) are not supported in footers.
 
-</div>
+### Heading Anchors
+
+Your site's readers may want to obtain a link to a heading within a page, to share with someone else for example.
+
+MarkBind automatically generates heading anchors for your page.
+
+When the reader hovers over a heading in your page, a small anchor icon <i class="fas fa-anchor"></i> will become visible next to the heading. Clicking this icon will redirect the page to that heading, producing the desired URL in the URL bar that the reader can share with someone else. Try it with the headings on this page!
+
+</div>

lib/Page.js

@@ -25,6 +25,7 @@ const PAGE_CONTENT_ID = 'page-content';
 const SITE_NAV_ID = 'site-nav';
 const TITLE_PREFIX_SEPARATOR = ' - ';
 
+const ANCHOR_HTML = '<a class="fa fa-anchor" href="#"></a>';
 const DROPDOWN_BUTTON_ICON_HTML = '<i class="dropdown-btn-icon">\n'
   + '<span class="glyphicon glyphicon-menu-down" aria-hidden="true"></span>\n'
   + '</i>';
@@ -219,16 +220,25 @@ Page.prototype.collectHeadingsAndKeywords = function () {
   this.collectHeadingsAndKeywordsInContent($(`#${CONTENT_WRAPPER_ID}`).html(), null);
 };
 
+/**
+ * Generates a heading selector based on the indexing level
+ * @param headingIndexingLevel to generate
+ */
+function generateHeadingSelector(headingIndexingLevel) {
+  let headingsSelector = 'h1';
+  for (let i = 2; i <= headingIndexingLevel; i += 1) {
+    headingsSelector += `, h${i}`;
+  }
+  return headingsSelector;
+}
+
 /**
  * Records headings and keywords inside content into this.headings and this.keywords respectively
  * @param content that contains the headings and keywords
  */
 Page.prototype.collectHeadingsAndKeywordsInContent = function (content, lastHeading) {
   let $ = cheerio.load(content);
-  let headingsSelector = 'h1';
-  for (let i = 2; i <= this.headingIndexingLevel; i += 1) {
-    headingsSelector += `, h${i}`;
-  }
+  const headingsSelector = generateHeadingSelector(this.headingIndexingLevel);
   $('modal').remove();
   $('panel').not('panel panel')
     .each((index, panel) => {
@@ -309,6 +319,21 @@ Page.prototype.concatenateHeadingsAndKeywords = function () {
   });
 };
 
+/**
+ * Adds anchor links to headings in the page
+ * @param content of the page
+ */
+Page.prototype.addAnchors = function (content) {
+  const $ = cheerio.load(content, { xmlMode: false });
+  if (this.headingIndexingLevel > 0) {
+    const headingsSelector = generateHeadingSelector(this.headingIndexingLevel);
+    $(headingsSelector).each((i, heading) => {
+      $(heading).append(ANCHOR_HTML.replace('#', `#${$(heading).attr('id')}`));
+    });
+  }
+  return $.html();
+};
+
 /**
  * Records the dynamic or static included files into this.includedFiles
  * @param dependencies array of maps of the external dependency and where it is included
@@ -471,6 +496,7 @@ Page.prototype.generate = function (builtFiles) {
       .then(result => markbinder.resolveBaseUrl(result, fileConfig))
       .then(result => fs.outputFileAsync(this.tempPath, result))
       .then(() => markbinder.renderFile(this.tempPath, fileConfig))
+      .then(result => this.addAnchors(result))
       .then((result) => {
         this.content = htmlBeautify(result, { indent_size: 2 });
 

test/test_site/expected/bugs/index.html

@@ -26,7 +26,7 @@
     </navbar>
   </div>
   <div class="website-content">
-    <h2 id="popover-initiated-by-trigger-honor-trigger-attribute">popover initiated by trigger: honor trigger attribute</h2>
+    <h2 id="popover-initiated-by-trigger-honor-trigger-attribute">popover initiated by trigger: honor trigger attribute<a class="fa fa-anchor" href="#popover-initiated-by-trigger-honor-trigger-attribute"></a></h2>
     <p><a href="https://github.com/MarkBind/markbind/issues/49">Issue #49</a></p>
     <p>Repro:</p>
     <p>
@@ -40,7 +40,7 @@ <h2 id="popover-initiated-by-trigger-honor-trigger-attribute">popover initiated
         </div>
       </div>
     </popover>
-    <h2 id="support-multiple-inclusions-of-a-modal">Support multiple inclusions of a modal</h2>
+    <h2 id="support-multiple-inclusions-of-a-modal">Support multiple inclusions of a modal<a class="fa fa-anchor" href="#support-multiple-inclusions-of-a-modal"></a></h2>
     <p><a href="https://github.com/MarkBind/markbind/issues/107">Issue #107</a></p>
     <p>Repro:</p>
     <div>
@@ -65,7 +65,7 @@ <h2 id="support-multiple-inclusions-of-a-modal">Support multiple inclusions of a
         </div>
       </modal>
     </div>
-    <h2 id="remove-extra-space-in-links">Remove extra space in links</h2>
+    <h2 id="remove-extra-space-in-links">Remove extra space in links<a class="fa fa-anchor" href="#remove-extra-space-in-links"></a></h2>
     <p><a href="https://github.com/MarkBind/markbind/issues/147">Issue #147</a></p>
     <p>Repro:</p>
     <p>This is a link. [