Adds navigation pane (TOC) to documentation pages

- Register Asciidoctor TOC into Awestruct page
- Register Asciidoctor::Document to page context
- Create a dedicated layout for documentation
- Display a navigation pane (TOC) on the left of the screen
- Add a toggle button to control bar hide/show the navigation pane
- Change color of CTA button and bottom border of main navigation
- control toc in documents rather than globally
- keep user manual as standalone document
- tweak margin around control bar

_ext/awestruct_ext.rb

@@ -1,5 +1,15 @@
 require 'asciidoctor'
 require 'asciidoctor/extensions'
+require 'awestruct/handlers/template/asciidoc'
+
+# Monkeypatch the AsciidoctorTemplate class from Awestruct to register Asciidoctor::Document object in page context.
+# Remove this hack when issue [1] will be resolved and available in a release.
+# [1] https://github.com/awestruct/awestruct/issues/288
+class Awestruct::Tilt::AsciidoctorTemplate
+  def evaluate(scope, locals)
+    @output ||= (scope.document = ::Asciidoctor.load(data, options)).convert
+  end
+end
 
 #require 'open-uri/cached'
 #OpenURI::Cache.cache_path = ::File.join Awestruct::Engine.instance.config.dir, 'vendor', 'uri-cache'

_layouts/about.html.slim

@@ -0,0 +1,61 @@
+---
+layout: base
+---
+header
+  .row
+    - if page.url == '/'
+      .large-8.columns.hero
+        h1=page.title
+        p.description
+          |A <em>fast</em> text processor &amp; publishing toolchain for converting AsciiDoc to HTML5, DocBook &amp; more.
+        .actions
+          a.button.secondary href='https://rubygems.org/gems/asciidoctor' style='color: #6d180b; max-width: 220px;'
+            i.fa.fa-download.fa-2x.pull-left
+            |Download gem from RubyGems
+          a.button.secondary href='https://github.com/asciidoctor/asciidoctor' style='max-width: 220px;'
+            i.fa.fa-github.fa-2x.pull-left
+            |Checkout source from GitHub
+      .large-4.columns.hello
+        / TODO make this an AsciiDoc snippet when it becomes available in Slim
+        .listingblock
+          .content
+            pre.CodeRay.highlight
+              code data-lang='asciidoc'
+                |= Hello, AsciiDoc!
+                 Doc Writer &lt;doc@example.com&gt;
+
+                 An introduction to http://asciidoc.org[AsciiDoc].
+
+                 == First Section
+
+                 * item 1
+                 * item 2
+
+                 [source,ruby]
+                 puts "Hello, World!"
+    - else
+      .large-12.columns
+        h1=page.title
+        - if page.leadin
+          p.description=page.leadin
+.row
+  .large-8.columns
+    #content
+      =content
+  .large-4.columns.secondary id='sidebar'
+    - if page.url == '/'
+      .quoteblock
+        blockquote
+          .paragraph
+            |Use AsciiDoc for document markup. Really. It's actually <strong>readable</strong> by humans, easier to parse and way more flexible than XML.
+        .attribution
+          |&#8212; Linus Torvalds
+    h4 Asciidoctor Project
+    p
+      |The Asciidoctor project is an effort to bring a comprehensive and accessible publishing toolchain, centered around the AsciiDoc syntax, to a growing range of ecosystems, including Ruby, JavaScript and the JVM.
+      br
+      br
+      |In addition to an AsciiDoc processor and a collection of stylesheets, the project provides plugins for Maven, Gradle and Guard and packages for operating systems such as Fedora, Debian and Ubuntu. It also pushes AsciiDoc to evolve by introducing new ideas and innovation and helps promote AsciiDoc through education and advocacy.
+    h4 Contribute to asciidoctor.org
+    p This website is open source! The source is hosted under the Asciidoctor organization on GitHub.
+    p If you want to help by improving upon it, <a href="https://github.com/asciidoctor/asciidoctor.org">fork the project</a>, revise the content, then send a pull request. When the pull request is merged, the site will be updated automatically.

_layouts/base.html.slim

@@ -45,77 +45,7 @@ body.antialiased
         li.divider
         li.has-form: a.button href='/docs/asciidoc-writers-guide/' Get Writing!
   .container
-    - unless page.url.start_with? '/news/'
-      header
-        .row
-          - if page.url == '/'
-            .large-8.columns.hero
-              h1=page.title
-              p.description
-                |A <em>fast</em> text processor &amp; publishing toolchain for converting AsciiDoc to HTML5, DocBook &amp; more.
-              .actions
-                a.button.secondary href='https://rubygems.org/gems/asciidoctor' style='color: #6d180b; max-width: 220px;'
-                  i.fa.fa-download.fa-2x.pull-left
-                  |Download gem from RubyGems
-                a.button.secondary href='https://github.com/asciidoctor/asciidoctor' style='max-width: 220px;'
-                  i.fa.fa-github.fa-2x.pull-left
-                  |Checkout source from GitHub
-            .large-4.columns.hello
-              / TODO make this an AsciiDoc snippet when it becomes available in Slim
-              .listingblock
-                .content
-                  pre.CodeRay.highlight
-                    code data-lang='asciidoc'
-                      |= Hello, AsciiDoc!
-                       Doc Writer &lt;doc@example.com&gt;
-
-                       An introduction to http://asciidoc.org[AsciiDoc].
-
-                       == First Section
-
-                       * item 1
-                       * item 2
-
-                       [source,ruby]
-                       puts "Hello, World!"
-          - else
-            .large-12.columns
-              h1=page.title
-              - if page.leadin
-                p.description=page.leadin
-    .row
-      div class=["large-#{page.url.start_with?('/news/') ? 12 : 8}", 'columns']
-        .row
-          .large-12.columns.primary
-            =content
-      - unless page.url.start_with? '/news/'
-        .large-4.columns.secondary
-          - if page.url =~ /^\/docs\/.+/
-            ul.button-group.radius style='margin-top: 0.5em; margin-bottom: -0.625em'
-              li: a.small.secondary.button href="https://github.com/asciidoctor/asciidoctor.org/edit/master#{page.relative_source_path}" Edit
-              li: a.small.secondary.button href="https://github.com/asciidoctor/asciidoctor.org/raw/master#{page.relative_source_path}" Raw
-              li: a.small.secondary.button href="https://github.com/asciidoctor/asciidoctor.org/commits/master#{page.relative_source_path}" History
-              li: i.fa.fa-github.fa-2x
-              - if page.url =~ /^\/docs\/asciidoc-syntax-quick-reference/
-                li: a href='/docs/asciidoc-syntax-quick-reference.pdf' style='text-decoration: none' title='Download PDF': i.fa.fa-file-text-alt.fa-2x
-              - if page.url =~ /^\/docs\/asciidoc-writers-guide/
-                li: a href='/docs/asciidoc-writers-guide.pdf' style='text-decoration: none' title='Download PDF': i.fa.fa-file-text-alt.fa-2x
-          - if page.url == '/'
-            .quoteblock
-              blockquote
-                .paragraph
-                  |Use AsciiDoc for document markup. Really. It's actually <strong>readable</strong> by humans, easier to parse and way more flexible than XML.
-              .attribution
-                |&#8212; Linus Torvalds
-          h4 Asciidoctor Project
-          p
-            |The Asciidoctor project is an effort to bring a comprehensive and accessible publishing toolchain, centered around the AsciiDoc syntax, to a growing range of ecosystems, including Ruby, JavaScript and the JVM.
-            br
-            br
-            |In addition to an AsciiDoc processor and a collection of stylesheets, the project provides plugins for Maven, Gradle and Guard and packages for operating systems such as Fedora, Debian and Ubuntu. It also pushes AsciiDoc to evolve by introducing new ideas and innovation and helps promote AsciiDoc through education and advocacy.
-          h4 Contribute to asciidoctor.org
-          p This website is open source! The source is hosted under the Asciidoctor organization on GitHub.
-          p If you want to help by improving upon it, <a href="https://github.com/asciidoctor/asciidoctor.org">fork the project</a>, revise the content, then send a pull request. When the pull request is merged, the site will be updated automatically.
+    =content
   footer
     .row.full-width
       .large-6.columns
@@ -158,6 +88,8 @@ body.antialiased
 
   script
     |document.write('<script src=' + ('__proto__' in {} ? '/javascripts/vendor/zepto' : '/javascripts/vendor/jquery') + '.js><\/script>')
+  script
+    |$('.toggle-navigation').click(function() { $('.navigation').toggle(); $('.content').toggleClass('large-8'); $('.content').toggleClass('large-12'); $('.toolbar').toggleClass('off'); });
   script src='/javascripts/foundation/foundation.js'
   - [:topbar].each do |component|
     script src="/javascripts/foundation/foundation.#{component}.js"

_layouts/docs.html.slim

@@ -0,0 +1,33 @@
+---
+layout: base
+---
+header
+  .row
+    .large-12.columns
+      h1=page.title
+      - if page.leadin
+        p.description=page.leadin
+.row
+  .large-4.columns
+    ul.button-group.toolbar style='margin-bottom: -0.3333em'
+      li: a.tiny.secondary.button.toggle-navigation href='#'
+        i.fa.fa-toggle-on
+        i.fa.fa-toggle-off
+        |  Nav
+      li: span.separator
+      li: a.tiny.secondary.button href="https://github.com/asciidoctor/asciidoctor.org/edit/master#{page.relative_source_path}" Edit
+      li: a.tiny.secondary.button href="https://github.com/asciidoctor/asciidoctor.org/raw/master#{page.relative_source_path}" Raw
+      li: a.tiny.secondary.button href="https://github.com/asciidoctor/asciidoctor.org/commits/master#{page.relative_source_path}" History
+      li: i.fa.fa-github.fa-fw
+      - if page.url =~ /^\/docs\/asciidoc-syntax-quick-reference/
+        li: a href='/docs/asciidoc-syntax-quick-reference.pdf' style='text-decoration: none' title='Download PDF': i.fa.fa-file-text-alt.fa-fw
+      - if page.url =~ /^\/docs\/asciidoc-writers-guide/
+        li: a href='/docs/asciidoc-writers-guide.pdf' style='text-decoration: none' title='Download PDF': i.fa.fa-file-text-alt.fa-fw
+.row
+  .large-4.columns.secondary.navigation
+    div id='toc' class='toc'
+      .title id='toctitle' =document.attr 'toc-title'
+      =document.converter.convert document, 'outline', toclevels: 3
+  .large-8.columns.content
+    #content
+      =content

_layouts/post.html.slim

@@ -1,5 +1,7 @@
 ---
 layout: base
 ---
-#content
-  =partial('entry.html.slim', :post => page)
+.row
+  .large-12.columns
+    #content
+      =partial('entry.html.slim', :post => page)

_layouts/press.html.slim

@@ -6,5 +6,7 @@ layout: base
   span#author=page.author
   br
   span#revdate=page.date || '2013-01-30'
-#content
-  =content
+.row
+  .large-12.columns
+    #content
+      =content

contributors.html.slim

@@ -1,5 +1,5 @@
 ---
-layout: base
+layout: about
 ---
 - contributors = YAML.load_file '_config/contributors.yml'
 - page.title = %[Contributors and Participants <small>#{contributors.size}</small>]

docs/asciidoc-article.adoc

@@ -1,7 +1,7 @@
 = AsciiDoc Article Template
 :description: This is an AsciiDoc article template. It illustrates the usage of the most common content structures and markup used in AsciiDoc documents and parsed by Asciidoctor, including section headings, lists, tables, example blocks, sidebars, image macros, listing blocks, literal blocks, quote blocks, verse blocks, admonitions, footnotes, links, and cross references.
 :keywords: AsciiDoc, Asciidoctor, AsciiDoc template, Asciidoctor template, AsciiDoc article template, Asciidoctor article template, AsciiDoc example, Asciidoctor example, AsciiDoc table example, AsciiDoc list example, AsciiDoc heading example, AsciiDoc article example, AsciiDoc sidebar example, AsciiDoc image example, AsciiDoc listing example, AsciiDoc code example, AsciiDoc literal example, AsciiDoc quote example, AsciiDoc verse example, AsciiDoc footnote example, AsciiDoc link example, AsciiDoc cross reference example
-:page-layout: base
+:page-layout: docs
 :sectanchors:
 :sectlinks:
 :linkattrs:

docs/asciidoc-asciidoctor-diffs.adoc

@@ -1,12 +1,8 @@
 = Differences between Asciidoctor and AsciiDoc
 Dan Allen; Sarah White
-:page-layout: base
-ifdef::env-site[]
-:toc:
-:toc-placement: preamble
-endif::[]
+:page-layout: docs
 ifndef::env-site[]
-:toc2:
+:toc: left
 :icons: font
 :idprefix:
 :idseparator: -

docs/asciidoc-recommended-practices.adoc

@@ -2,7 +2,7 @@
 Dan Allen
 v1.0-HEAD, 2013-02-10
 :description: This document catalogs a set of recommended practices for composing documents in AsciiDoc.
-:page-layout: base
+:page-layout: docs
 
 {description}
 

docs/asciidoc-syntax-quick-reference.adoc

@@ -1,22 +1,21 @@
 = AsciiDoc Syntax Quick Reference
 Dan Allen; Sarah White
 v1.0.4, 2014-08-08
-:page-layout: base
+:page-layout: docs
 :page-javascripts: [view-result]
 :description: This guide is a quick reference for the common AsciiDoc document and text formatting markup.
 :keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet
 :compat-mode!:
 :imagesdir: ../images
 :includedir: _includes
-:toc:
-:toc-placement!:
 :experimental:
 :table-caption!:
 :example-caption!:
 :figure-caption!:
 ifndef::env-site[]
 :idprefix:
 :idseparator: -
+:toc: macro
 endif::[]
 :linkattrs:
 // URLs

docs/asciidoc-writers-guide.adoc

@@ -3,15 +3,11 @@
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
 :description: This guide describes the basic structure of an AsciiDoc document, how to create your first AsciiDoc document, how to add other structural elements such as lists, block quotes and source code, and how to convert an AsciiDoc document to HTML, DocBook and PDF.
 :keywords: AsciiDoc, Asciidoctor, syntax, reference, learn, how to, writers, authors
-:page-layout: base
+:page-layout: docs
 :page-description: {description}
 :page-keywords: {keywords}
-ifdef::env-site[]
-:toc:
-:toc-placement: preamble
-endif::[]
 ifndef::env-site[]
-:toc: right
+:toc: left
 :icons: font
 :idprefix:
 :idseparator: -

docs/asciidoclet.adoc

@@ -3,7 +3,7 @@ John Ericksen <https://github.com/johncarl81[@johncarl81]>; Ben Evans <https://g
 v1.5.0
 :description: This is a guide for setting up and using the Asciidoclet project. Asciidoclet is a Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.
 :keywords: Asciidoclet, AsciiDoc, Asciidoctor, syntax, Javadoc, Doclet, reference
-:page-layout: base
+:page-layout: docs
 :source-language: java
 :language: {source-language}
 ifndef::env-site[]

docs/asciidoctor-diagram.adoc

@@ -2,13 +2,11 @@
 Pepijn Van_Eeckhoudt <https://github.com/pepijnve[@pepijnve]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
 :description: This guide describes the Asciidoctor Diagram extension for Asciidoctor.
 :keywords: Asciidoctor diagram, AsciiDoc, Asciidoctor, PlantUML, sequence diagram, use case diagram, class diagram, activity diagram, component diagram, state diagram, object diagram, Graphviz, DOT, ditaa, diagram, ASCII diagram, ASCII art, ASCII art diagram, Asciidoctor PlantUML, Asciidoctor Graphviz, Asciidoctor ditaa, diagram to PNG, diagram to SVG, AsciiDoc to SVG, AsciiDoc to PNG, Asciidoctor to SVG, Asciidoctor to PNG, ASCII to SVG, ASCII to PNG, Asciidoctor UML, AsciiDoc UML, Asciidoctor to UML, AsciiDoc to UML, convert to UML, convert to PNG, convert to SVG, convert to bitmap, draw UML with Asciidoctor, draw UML with AsciiDoc, draw diagrams with Asciidoctor, draw diagrams with AsciiDoc, graph visualization with Asciidoctor, Asciidoctor to bitmap, embed diagram, Asciidoctor diagram gem, install Asciidoctor diagram, install AsciiDoc diagram
-:page-layout: base
+:page-layout: docs
 :compat-mode!:
-:toc: preamble
 :sectanchors:
 :sectlinks:
 :linkattrs:
-:numbered!:
 :icons: font
 :source-highlighter: coderay
 :idprefix:

docs/asciidoctor-gradle-plugin.adoc

@@ -1,10 +1,9 @@
 = Installing and Using the Asciidoctor Gradle Plugin
 Andres Almiray <https://github.com/aalmiray[@aalmiray]>
 // Settings:
-:page-layout: base
+:page-layout: docs
 :compat-mode!:
 :linkattrs:
-ifdef::env-site[:toc: preamble]
 // Aliases:
 :project-name: asciidoctor-gradle-plugin
 :project-version: 1.5.1.SNAPSHOT

docs/asciidoctor-maven-plugin.adoc

@@ -1,13 +1,9 @@
 = Installing and Using the Asciidoctor Maven Plugin
 Jason Porter; Sarah White
-:page-layout: base
+:page-layout: docs
 :compat-mode!:
-ifdef::env-site[]
-:toc:
-:toc-placement: preamble
-endif::[]
 ifndef::env-site[]
-:toc2:
+:toc: left
 :icons: font
 :idprefix:
 :idseparator: -

docs/asciidoctorj.adoc

@@ -2,10 +2,12 @@
 Alex Soto <https://github.com/lordofthejars[@lordofthejars]>; Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
 // Settings:
 :compat-mode!:
-:page-layout: base
+:page-layout: docs
+:toclevels: 1
+ifndef::env-site[]
 :toc: macro
 :toclevels: 2
-ifdef::env-site[:toclevels: 1]
+endif::[]
 //:table-caption!:
 :source-language: java
 :language: {source-language}
@@ -38,7 +40,7 @@ ifdef::env-github[]
 image::http://img.shields.io/travis/asciidoctor/asciidoctorj/master.svg[Build Status,90,18,link=https://travis-ci.org/asciidoctor/asciidoctorj]
 endif::[]
 
-ifdef::env-site,env-browser[]
+ifeval::["{toc-placement}" == "macro"]
 toc::[]
 endif::[]
 

docs/convert-asciidoc-to-epub.adoc

@@ -4,16 +4,12 @@ Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://g
 v1.0
 :description: Asciidoctor EPUB3 is a direct AsciiDoc to EPUB3 converter. The generate-epub3 script converts an AsciiDoc document to an EPUB3 archive.
 :keywords: asciidoctor-epub, asciidoctor-epub3, Asciidoctor, AsciiDoc, EPUB, EPUB3, KF8, mobi, Kindle, iBooks, OSX, Windows, Linux, mobile, Android, ereader, e-reader, ebook, e-book, convert, generate, theme, Ruby, modern, generate-epub, day mode, night mode, sepia mode, fully semantic, readability, responsive, declare spine, converter
-:page-layout: base
+:page-layout: docs
 :page-description: {description}
 :page-keywords: {keywords}
 :compat-mode!:
-ifdef::env-site[]
-:toc:
-:toc-placement: preamble
-endif::[]
 ifndef::env-site[]
-:toc: right
+:toc: left
 :icons: font
 :idprefix:
 :idseparator: -