lucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tflo...@apache.org
Subject [08/27] lucene-solr:jira/solr-10233: SOLR-10612: add jekyll support for page-toclevels, page-tocclass, and a new {section-toc} macro
Date Tue, 23 May 2017 00:03:30 GMT
SOLR-10612: add jekyll support for page-toclevels, page-tocclass, and a new {section-toc} macro


Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/3392a128
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/3392a128
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/3392a128

Branch: refs/heads/jira/solr-10233
Commit: 3392a128667f927783199fe3d9f0c6a17f0a787f
Parents: 4a57fb4
Author: Chris Hostetter <hossman@apache.org>
Authored: Fri May 19 10:47:37 2017 -0700
Committer: Chris Hostetter <hossman@apache.org>
Committed: Fri May 19 10:47:37 2017 -0700

----------------------------------------------------------------------
 solr/solr-ref-guide/build.xml                |  1 +
 solr/solr-ref-guide/meta-docs/jekyll.adoc    | 16 +++++++--
 solr/solr-ref-guide/src/_config.yml.template |  2 ++
 solr/solr-ref-guide/src/_includes/toc.html   | 22 +++---------
 solr/solr-ref-guide/src/css/ref-guide.css    | 44 +++++++++++++++--------
 solr/solr-ref-guide/src/js/ref-guide-toc.js  | 36 +++++++++++++++++++
 6 files changed, 87 insertions(+), 34 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/3392a128/solr/solr-ref-guide/build.xml
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/build.xml b/solr/solr-ref-guide/build.xml
index 74e6dee..4e00992 100644
--- a/solr/solr-ref-guide/build.xml
+++ b/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"/>

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/3392a128/solr/solr-ref-guide/meta-docs/jekyll.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/meta-docs/jekyll.adoc b/solr/solr-ref-guide/meta-docs/jekyll.adoc
index e1ba129..8d3f2fc 100644
--- a/solr/solr-ref-guide/meta-docs/jekyll.adoc
+++ b/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.

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/3392a128/solr/solr-ref-guide/src/_config.yml.template
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/_config.yml.template b/solr/solr-ref-guide/src/_config.yml.template
index e10eeb7..eac2d28 100755
--- a/solr/solr-ref-guide/src/_config.yml.template
+++ b/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>"

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/3392a128/solr/solr-ref-guide/src/_includes/toc.html
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/_includes/toc.html b/solr/solr-ref-guide/src/_includes/toc.html
index 14f74e0..faa4701 100755
--- a/solr/solr-ref-guide/src/_includes/toc.html
+++ b/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>

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/3392a128/solr/solr-ref-guide/src/css/ref-guide.css
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/css/ref-guide.css b/solr/solr-ref-guide/src/css/ref-guide.css
index 7443c56..8cbe0f2 100644
--- a/solr/solr-ref-guide/src/css/ref-guide.css
+++ b/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;

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/3392a128/solr/solr-ref-guide/src/js/ref-guide-toc.js
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/js/ref-guide-toc.js b/solr/solr-ref-guide/src/js/ref-guide-toc.js
new file mode 100644
index 0000000..3acd191
--- /dev/null
+++ b/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
+	})
+	
+    });
+}


Mime
View raw message