Auto generate interactive table of contents for user-guide. (#1818)

2 files changed, 137 insertions, 16 deletions

diff --git a/docs/_includes/anchor_headings.html b/docs/_includes/anchor_headings.html
new file mode 100644
index 000000000..3df42b6a6
--- /dev/null
+++ b/docs/_includes/anchor_headings.html
@@ -0,0 +1,137 @@
+{% capture headingsWorkspace %}
+{% comment %}
+Copyright (c) 2018 Vladimir "allejo" Jimenez
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+{% endcomment %}
+{% comment %}
+Version 1.0.9
+https://github.com/allejo/jekyll-anchor-headings
+
+"Be the pull request you wish to see in the world." ~Ben Balter
+
+Usage:
+{% include anchor_headings.html html=content anchorBody="#" %}
+
+Parameters:
+* html (string) - the HTML of compiled markdown generated by kramdown in Jekyll
+
+Optional Parameters:
+* beforeHeading (bool) : false - Set to true if the anchor should be placed _before_ the heading's content
+* headerAttrs (string) : '' - Any custom HTML attributes that will be added to the heading tag; you may NOT use `id`;
+the `%heading%` and `%html_id%` placeholders are available
+* anchorAttrs (string) : '' - Any custom HTML attributes that will be added to the `<a>` tag; you may NOT use `href`,
+    `class` or `title`;
+    the `%heading%` and `%html_id%` placeholders are available
+    * anchorBody (string) : '' - The content that will be placed inside the anchor; the `%heading%` placeholder is
+    available
+    * anchorClass (string) : '' - The class(es) that will be used for each anchor. Separate multiple classes with a
+    space
+    * anchorTitle (string) : '' - The `title` attribute that will be used for anchors
+    * h_min (int) : 1 - The minimum header level to build an anchor for; any header lower than this value will be
+    ignored
+    * h_max (int) : 6 - The maximum header level to build an anchor for; any header greater than this value will be
+    ignored
+    * bodyPrefix (string) : '' - Anything that should be inserted inside of the heading tag _before_ its anchor and
+    content
+    * bodySuffix (string) : '' - Anything that should be inserted inside of the heading tag _after_ its anchor and
+    content
+
+    Output:
+    The original HTML with the addition of anchors inside of all of the h1-h6 headings.
+    {% endcomment %}
+
+    {% assign minHeader = include.h_min | default: 1 %}
+    {% assign maxHeader = include.h_max | default: 2 %}
+    {% assign beforeHeading = include.beforeHeading %}
+    {% assign nodes = include.html | split: '<h' %} {% capture edited_headings %}{% endcapture %} {% for _node in nodes
+        %} {% capture node %}{{ _node | strip }}{% endcapture %} {% if node=="" %} {% continue %} {% endif %} {% assign
+        nextChar=node | replace: '"' , '' | strip | slice: 0, 1 %} {% assign headerLevel=nextChar | times: 1 %} <!-- If
+        the level is cast to 0, it means it's not a h1-h6 tag, so let's see if we need to fix it -->
+        {% if headerLevel == 0 %}
+        <!-- Split up the node based on closing angle brackets and get the first one. -->
+        {% assign firstChunk = node | split: '>' | first %}
+
+        <!-- If the first chunk does NOT contain a '<', that means we've broken another HTML tag that starts with 'h' -->
+        {% unless firstChunk contains '<' %} {% capture node %}<h{{ node }}{% endcapture %} {% endunless %} {% capture
+            edited_headings %}{{ edited_headings }}{{ node }}{% endcapture %} {% continue %} {% endif %} {% capture
+            _closingTag %}</h{{ headerLevel }}>{% endcapture %}
+            {% assign _workspace = node | split: _closingTag %}
+            {% assign _idWorkspace = _workspace[0] | split: 'id="' %}
+            {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}
+            {% assign html_id = _idWorkspace[0] %}
+
+            {% capture _hAttrToStrip %}{{ _workspace[0] | split: '>' | first }}>{% endcapture %}
+            {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
+
+            <!-- Build the anchor to inject for our heading -->
+            {% capture anchor %}{% endcapture %}
+
+            {% if html_id and headerLevel >= minHeader and headerLevel <= maxHeader %} {% assign escaped_header=header |
+                strip_html %} {% if include.headerAttrs %} {% capture _hAttrToStrip %}{{ _hAttrToStrip | split: '>' |
+                first }} {{ include.headerAttrs | replace: '%heading%' , escaped_header | replace: '%html_id%' , html_id
+                }}>{% endcapture %}
+                {% endif %}
+
+                {% capture anchor %}href="#{{ html_id }}"{% endcapture %}
+
+                {% if include.anchorClass %}
+                {% capture anchor %}{{ anchor }} class="{{ include.anchorClass }}"{% endcapture %}
+                {% endif %}
+
+                {% if include.anchorTitle %}
+                {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', escaped_header
+                }}"{% endcapture %}
+                {% endif %}
+
+                {% if include.anchorAttrs %}
+                {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', escaped_header |
+                replace: '%html_id%', html_id }}{% endcapture %}
+                {% endif %}
+
+                {% capture anchor %}<a {{ anchor }}>{{ include.anchorBody | replace: '%heading%', escaped_header |
+                    default: '' }}</a>{% endcapture %}
+
+                <!-- In order to prevent adding extra space after a heading, we'll let the 'anchor' value contain it -->
+                {% if beforeHeading %}
+                {% capture anchor %}{{ anchor }} {% endcapture %}
+                {% else %}
+                {% capture anchor %} {{ anchor }}{% endcapture %}
+                {% endif %}
+                {% endif %}
+
+                {% capture new_heading %}
+                <h{{ _hAttrToStrip }} {{ include.bodyPrefix }} {% if beforeHeading %} {{ anchor }}{{ header }} {% else
+                    %} {{ header }}{{ anchor }} {% endif %} {{ include.bodySuffix }} </h{{ headerLevel }}>
+                    {% endcapture %}
+
+                    <!--
+    If we have content after the `</hX>` tag, then we'll want to append that here so we don't lost any content.
+    -->
+                    {% assign chunkCount = _workspace | size %}
+                    {% if chunkCount > 1 %}
+                    {% capture new_heading %}{{ new_heading }}{{ _workspace | last }}{% endcapture %}
+                    {% endif %}
+
+                    {% capture edited_headings %}{{ edited_headings }}{{ new_heading }}{% endcapture %}
+                    {% endfor %}
+                    {% endcapture %}{% assign headingsWorkspace = '' %}{{ edited_headings | strip }}
\ No newline at end of file
diff --git a/docs/_includes/user-guide-toc.html b/docs/_includes/user-guide-toc.html
deleted file mode 100644
index 511b30aad..000000000
--- a/docs/_includes/user-guide-toc.html
+++ /dev/null
@@ -1,16 +0,0 @@
-
-<a href="/slang/user-guide/">Slang User's Guide</a>
-<ol class="toc_list">
-    <li><a href="/slang/user-guide/00-introduction.html">Introduction</a></li>
-    <li><a href="/slang/user-guide/01-get-started.html">Getting Started</a></li>
-    <li><a href="/slang/user-guide/02-conventional-features.html">Conventional Language Features</a></li>
-    <li><a href="/slang/user-guide/03-convenience-features.html">Extended language features</a></li>
-    <li><a href="/slang/user-guide/04-interfaces-generics.html">Interfaces and Generics</a></li>
-    <li><a href="/slang/user-guide/05-compiling.html">Compiling Code with Slang</a></li>
-    <li><a href="/slang/user-guide/06-targets.html">Supported Compilation Targets</a></li>
-    <li><a href="/slang/user-guide/a1-special-topics.html">Special Topics</a></li>
-    <ol class="toc_list">
-        <li><a href="/slang/user-guide/a1-01-matrix-layout.html">Matrix Layout</a></li>
-    </ol>
-
-</ol>