You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ho...@apache.org on 2017/05/19 17:49:48 UTC
[1/3] lucene-solr:master: SOLR-10612: add jekyll support for
page-toclevels, page-tocclass, and a new {section-toc} macro
Repository: lucene-solr
Updated Branches:
refs/heads/branch_6_6 8a88eaf0d -> c42455c89
refs/heads/branch_6x 43220c36a -> 3654ae291
refs/heads/master 4a57fb4d8 -> 3392a1286
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/master
Commit: 3392a128667f927783199fe3d9f0c6a17f0a787f
Parents: 4a57fb4
Author: Chris Hostetter <ho...@apache.org>
Authored: Fri May 19 10:47:37 2017 -0700
Committer: Chris Hostetter <ho...@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
+ })
+
+ });
+}
[2/3] lucene-solr:branch_6x: SOLR-10612: add jekyll support for
page-toclevels, page-tocclass, and a new {section-toc} macro
Posted by ho...@apache.org.
SOLR-10612: add jekyll support for page-toclevels, page-tocclass, and a new {section-toc} macro
(cherry picked from commit 3392a128667f927783199fe3d9f0c6a17f0a787f)
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/3654ae29
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/3654ae29
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/3654ae29
Branch: refs/heads/branch_6x
Commit: 3654ae291b51726a9bffc6165f63593b32070c4e
Parents: 43220c3
Author: Chris Hostetter <ho...@apache.org>
Authored: Fri May 19 10:47:37 2017 -0700
Committer: Chris Hostetter <ho...@apache.org>
Committed: Fri May 19 10:47:59 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/3654ae29/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/3654ae29/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/3654ae29/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/3654ae29/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/3654ae29/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/3654ae29/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
+ })
+
+ });
+}
[3/3] lucene-solr:branch_6_6: SOLR-10612: add jekyll support for
page-toclevels, page-tocclass, and a new {section-toc} macro
Posted by ho...@apache.org.
SOLR-10612: add jekyll support for page-toclevels, page-tocclass, and a new {section-toc} macro
(cherry picked from commit 3392a128667f927783199fe3d9f0c6a17f0a787f)
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/c42455c8
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/c42455c8
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/c42455c8
Branch: refs/heads/branch_6_6
Commit: c42455c89b0446238adbad3548485498d671dd7d
Parents: 8a88eaf
Author: Chris Hostetter <ho...@apache.org>
Authored: Fri May 19 10:47:37 2017 -0700
Committer: Chris Hostetter <ho...@apache.org>
Committed: Fri May 19 10:48:14 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/c42455c8/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/c42455c8/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/c42455c8/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/c42455c8/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/c42455c8/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/c42455c8/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
+ })
+
+ });
+}