SOLR-10612: add jekyll support for page-toclevels, page-tocclass, and a new {section-toc} macro

solr/solr-ref-guide/build.xml

@@ -177,6 +177,7 @@
                  imagesDir="${build.content.dir}"
                  doctype="book"
                  safemode="unsafe">
+      <attribute key="section-toc" value='' /><!-- we don't use these in the pdf -->
       <attribute key="icons" value="font" />
       <attribute key="icon-set" value="fa" />
       <attribute key="pdf-stylesDir" value="./pdf/themes"/>

solr/solr-ref-guide/meta-docs/jekyll.adoc

@@ -30,10 +30,22 @@ Front matter for Jekyll is like a header that defines the title of the page, and
 
 Every document that will be converted to HTML *must* include at least the page title at the top of the page.
 
-The Solr Ref Guide uses the front matter to define the "short name" and permanent URL of a page, and to define the children of a page. The list of children is used to build the site navigation menu that appears to the left of each page's content.
-
 Many guides to Jekyll also say that defining the layout in the front matter is required. However, since we only have one layout for all pages, we have defined this as a default.
 
+The Solr Ref Guide uses the front matter to define some custom attributes on a per page basis:
+
+* `page-shortname` - uniquely identifying the page
+* `page-permalink` - permanent URL of a page,
+* `page-children` - ordered list of child pages, this is used to build the site navigation menu that appears to the left of each page's content (and to order the pages in the PDF)
+
+There are also some optional custom attributes that can be defined in pages to affect the Table of Contents presentation in jekyll:
+
+* `page-toclevels` - changes how "deep" the TOC will be in terms of nested section/sub-section titles (default = 2
+* `page-tocclass` - changes the CSS class applied to the TOC, default = "normal", resulting in the class name `toc-normal`
+* `page-toc` - if this is false, then no TOCs will be generated for the page at all.
+
+NOTE: The special macro `{section-toc}` can be used anywhere in a page to create an "In this Section" TOC covering only the sub-headings in the same secion.  `:page-toc: false` will also prevent this macro from working, so if you want no "top level" TOC, but you do want section TOCs, use `:page-toclevels: 0`
+
 === Layouts
 
 Layouts define the "look and feel" of each page.

solr/solr-ref-guide/src/_config.yml.template

@@ -87,3 +87,5 @@ asciidoctor:
     icons: "font"
     source-highlighter: "pygments"
     pygments-css: "style"
+    # NOTE: do *NOT* use an self-empty div tag (ie: <div/>) here - it will break jquery
+    section-toc: "<div class=\"toc section-toc\"></div>"

solr/solr-ref-guide/src/_includes/toc.html

@@ -1,21 +1,9 @@
 
 <!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
-<script>
-$( document ).ready(function() {
-  // Handler for .ready() called.
 
-$('#toc').toc({ minimumHeaders: 2, listType: 'ul', showSpeed: 0, headers: 'h2,h3' });
-
-/* this offset helps account for the space taken up by the floating toolbar. */
-$('#toc').on('click', 'a', function() {
-  var target = $(this.getAttribute('href'))
-    , scroll_target = target.offset().top
-
-  $(window).scrollTop(scroll_target - 10);
-  return false
-})
-
-});
+<script src="{{ "js/ref-guide-toc.js" }}" type="text/javascript"></script>
+<script type="text/javascript">
+  // based on page variables, build up the list of headers for the top level toc (and any sub-section tocs)
+  do_tocs({{ page.toclevels | default:2 }})
 </script>
-
-<div id="toc"></div>
+<div id="toc" class="toc toc-{{ page.tocclass | default:'normal' }}"></div>

solr/solr-ref-guide/src/css/ref-guide.css

@@ -1098,50 +1098,60 @@ body.toc2 #header > h1:nth-last-child(2)
     border-bottom: 1px solid #efefed;
 }
 
-#toc > ul
+@media only screen
+       and (min-width : 768px)
+{
+    #toc.toc-right
+    {   
+	float: right;
+	margin-left: 1em;
+	border: none;
+    }
+}
+.toc > ul
 {
     margin-left: .125em;
 }
 
-#toc ul.sectlevel0 > li > a
+.toc ul.sectlevel0 > li > a
 {
     font-weight: bold;
 }
 
-#toc ul.sectlevel0 ul.sectlevel1
+.toc ul.sectlevel0 ul.sectlevel1
 {
     margin: .5em 0;
 }
 
-#toc ul
+.toc ul
 {
     list-style-type: none;
     font-family: 'Noto Sans', sans-serif;
 }
 
-#toc a
+.toc a
 {
     text-decoration: none;
 }
 
-#toc a:active
+.toc a:active
 {
     text-decoration: underline;
 }
 
-#toctitle
+.toctitle
 {
     color: #7a2518;
     font-size: 1.2em;
 }
 
-div#toc ul li {
+div.toc ul li {
     margin: 8px 0 8px 22px;
     list-style: square;
     line-height: 1.25;
 }
 
-div#toc ul {
+div.toc ul {
     background-color: whitesmoke;
     padding: 5px;
     border-radius: 5px;
@@ -1149,16 +1159,19 @@ div#toc ul {
     color: gray;
 }
 
-div#toc ul li ul {
+div.toc ul li ul {
     padding-left:8px;
 
 }
 
-div#toc ul li ul li::before {
+div.toc ul li ul li::before {
     content: "–  ";
 }
 
-div#toc >ul::before {
+div.toc.section-toc >ul::before {
+    content: "In this section";
+}
+div.toc >ul::before {
     content: "On this Page";
     font-weight: bold;
     color: #555;
@@ -1290,12 +1303,12 @@ div#toc >ul::before {
     background: #f8f8f7;
 }
 
-#content #toc > :first-child
+#content .toc > :first-child
 {
     margin-top: 0;
 }
 
-#content #toc > :last-child
+#content .toc > :last-child
 {
     margin-bottom: 0;
 }
@@ -1421,6 +1434,7 @@ h6 > a.link:hover
 .videoblock
 {
     margin-bottom: 1.25em;
+    overflow: auto;
 }
 
 
@@ -1445,7 +1459,7 @@ table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p
 
 .admonitionblock > table
 {
-    width: 100%;
+    width: auto;
     border: 0;
     border-collapse: separate;
     background: none;

solr/solr-ref-guide/src/js/ref-guide-toc.js

@@ -0,0 +1,36 @@
+// see toc.js and toc.html
+
+// NOTE: toc.html is only include if :page-toc: is true, so it's safe to do this document.ready unconditionally
+function do_tocs(page_toc_levels) {
+    $( document ).ready(function() {
+
+	// headers used - start at 2, and we have to be careful about trailing comma
+	toc_headers = 0 < page_toc_levels ? 'h2' : '';
+	
+	for (i = 1; i < page_toc_levels; i++) {
+	    toc_headers += ",h" + (2 + i);
+	}
+	// top level TOC
+	$('#toc').toc({ minimumHeaders: 2, listType: 'ul', showSpeed: 0, headers: toc_headers });
+	
+	// any subsection TOCs
+	$('.section-toc').each(function() {
+            // toc() needs a selector string, so we'll build one by fetching the id of the nearest header
+	    // that comes before us, then use to make a selector for all sub headers in the same section
+	    // NOTE: this depends a lot of the particular structure of HTML asciidoctor generates
+	    header = $(this).closest("div:has(:header:first-child)").children(":header").first();
+            selector = "#" + header.attr("id") + " ~ * :header";
+            $(this).toc({ minimumHeaders: 2, listType: 'ul', showSpeed: 0, headers: selector });
+	});
+	
+	/* this offset helps account for the space taken up by the floating toolbar. */
+	$('.toc').on('click', 'a', function() {
+	    var target = $(this.getAttribute('href'))
+	    , scroll_target = target.offset().top
+	    
+	    $(window).scrollTop(scroll_target - 10);
+	    return false
+	})
+	
+    });
+}