JP - Allows to create submenus under Documentation Layout

docs/src/main/resources/microsite/data/menu.yml

@@ -0,0 +1,15 @@
+options:
+  - title: Getting Started
+    url: index.html
+
+  - title: Configuring the Microsite
+    url: settings.html
+
+  - title: Layouts
+    url: layouts.html
+
+  - title: Customize
+    url: customize.html
+
+  - title: Build the microsite
+    url: build-the-microsite.html

docs/src/main/tut/docs/build-the-microsite.md

@@ -1,8 +1,6 @@
 ---
 layout: docs
 title: Build the Microsite
-section: docs
-weight : 5
 ---
 
 # Build the microsite

docs/src/main/tut/docs/customize.md

@@ -1,8 +1,6 @@
 ---
 layout: docs
 title: Customize
-section: docs
-weight : 4
 ---
 
 # Customize

docs/src/main/tut/docs/index.md

@@ -1,17 +1,64 @@
 ---
 layout: docs
-title: Home
-section: docs
-weight : 0
+title: Getting Started
 ---
 
-# sbt-microsites Documentation
+# Prerequisites
 
-In this section, you can find everything you need to know about how **sbt-microsites** work and how they can be tweaked, review the following points to learn more: 
+* [sbt](http://www.scala-sbt.org/) 0.13.8+
+* [jekyll](https://jekyllrb.com/)
 
-{% assign pages = site.pages | sort:"weight"  %}
-{% for x in pages %}
-  {% if x.section == 'docs' and x.title != 'Home' %}
-- [{{x.title}}]({{site.baseurl}}{{x.url}})
-  {% endif %}
-{% endfor %}
+To satisfy the `jekyll` prerequisite, here are a few hints for local and travis environments.
+
+## Local Environment
+
+Depending on your platform, you might do this with:
+
+```bash
+yum install jekyll
+
+apt-get install jekyll
+
+gem install jekyll
+```
+
+## Continuous Integration - Travis
+
+If you have enabled [Travis](https://travis-ci.org/) for your project, you might have to tweak some parts of your `.travis.yml` file:
+
+Potentially, your project is a Scala project (`language: scala`), therefore you need to add the bundle gems vendor path in the `PATH` environment variable:
+
+```
+before_install:
+ - export PATH=${PATH}:./vendor/bundle
+```
+
+This is needed in order to install and be able to use the `jekyll` gem from other parts of your travis descriptor file. Once we have the `/vendor/bundle` path in the Travis `PATH` env variable, we have to install the gem in the `install` travis section:
+
+```
+install:
+ - ...
+ - gem install jekyll -v 2.5
+```
+
+# Set it up in your Project
+
+To begin, add the following lines to the `project/plugins.sbt` file within your project or sbt module where you want to use the `sbt-microsites` plugin. Depending on the version, you might want to use:
+
+Latest release:
+
+```
+addSbtPlugin("com.fortysevendeg"  % "sbt-microsites" % "0.2.4")
+```
+
+Latest snapshot built from the `master` branch code:
+
+```tut:evaluated
+println("""resolvers += Resolver.sonatypeRepo("snapshots")""")
+println(s"""addSbtPlugin("com.fortysevendeg"  % "sbt-microsites" % "${microsites.BuildInfo.version}"""")
+```
+
+Finally, to enable the plugin, add this to your `build.sbt` file:
+```
+enablePlugins(MicrositesPlugin)
+```

docs/src/main/tut/docs/layouts.md

@@ -1,8 +1,6 @@
 ---
 layout: docs
 title: Layouts
-section: docs
-weight : 3
 ---
 
 # Layouts
@@ -56,12 +54,66 @@ All these files contain as a header, something similar to this:
 ---
 layout: docs
 title: <Document Title>
-section: docs
-weight : <order>
 ---
 ```
 
-`<Document Title>` will be used as a menu item name on the left. `<order>` is related to the order in which they will appear in the left menu.
+`<Document Title>` will be used as a menu item name on the left.
+
+### How to setup the Docs Menu?
+
+Looking at the [Configuring the Microsite](settings.html) section, in the directory configured under the `micrositeDataDirectory` setting, you need to create a new file named `menu.yml`. This `YAML` file will be accessed by the `Docs Layout` in order to create the menu. Let's see an example:
+
+```
+options:
+  - title: Getting Started
+    url: index.html
+    section: intro
+
+  - title: Configuring the Microsite
+    url: settings.html
+
+  - title: Layouts
+    url: layouts.html
+    section: resources
+
+  - title: Customize
+    url: customize.html
+
+  - title: Build the microsite
+    url: build-the-microsite.html
+```
+
+* The `options` key is mandatory. It'll be the parent of all the options defined here. Each `option` or menu item will contain:
+* `title`: the menu title. It should be the same as defined in the meta-property associated with the file (`<Document Title>`, where the layout is defined).
+* `url`: relative path to the documentation file.
+* `section`: this key is mandatory only when you have a nested submenu. It'll be useful to distinguish between sub-items with the same name in different menu options.
+* Optionally, we could define a second level of nested sub-items, thanks to the `nested_options` key, defined at the same level that `title` and `url` of the parent menu. For example:
+
+```
+options:
+  - title: Introduction
+    url: index.html
+    section: intro
+
+    nested_options:
+     - title: Submenu 1
+       url: subfolder/submenu1.html
+     - title: Submenu 2
+       url: subfolder/submenu2.html
+
+  - title: Configuring the Microsite
+    url: settings.html
+```
+
+In this example, `Submenu 1` and `Submenu 2` will be nested under the `Introduction` menu option. At the same time, `submenu1` and `submenu2` would have the same section name as the parent. For instance, `submenu1.md` would have a header like this, where the `section` field matches the one defined in `menu.yml`:
+
+```
+---
+layout: docs
+title:  "Submenu 2"
+section: "intro"
+---
+```
 
 ## Page Layout and Menu Partial Layout
 

docs/src/main/tut/docs/settings.md

@@ -1,8 +1,6 @@
 ---
 layout: docs
 title: Configuring the Microsite
-section: docs
-weight : 2
 ---
 
 # Configuring the Microsite
@@ -90,6 +88,14 @@ micrositeImgDirectory := (resourceDirectory in Compile).value / "site" / "images
 micrositeCssDirectory := (resourceDirectory in Compile).value / "site" / "styles"
 ```
 
+- `micrositeDataDirectory`: in addition, you can provide new data to your jekyll site through the `micrositeDataDirectory` setting. It's based on the idea of [Jekyll Data Files](https://jekyllrb.com/docs/datafiles/). It's important to keep in mind that if you are defining documentation in your microsite, you have to configure the menu through this setting. The default value is `(resourceDirectory in Compile).value / "microsite" / "data"` but you can override it like this:
+
+```
+micrositeDataDirectory := (resourceDirectory in Compile).value / "site" / "mydatafiles"
+```
+
+In the Documentation **Menu** case, as you can see in the [layouts](layouts.html) section, you need to create a file named as `menu.yml` under the `micrositeDataDirectory` setting.
+
 - `micrositeExtraMdFiles`: this setting can be handy if you want to include additional markdown files in your site, and these files are not located in the same place in your `tut` directory. By default, the setting is set up as an empty map. You can override it, in this way:
 
 ```

project/plugins.sbt

@@ -7,5 +7,6 @@ resolvers += "jgit-repo" at "http://download.eclipse.org/jgit/maven"
 addSbtPlugin("com.typesafe.sbt"                    % "sbt-ghpages"     % "0.5.4")
 libraryDependencies <+= sbtVersion("org.scala-sbt" % "scripted-plugin" % _)
 // Plugin inception dependency to be able to generate the sbt-microsites' microsite
-addSbtPlugin("com.fortysevendeg" % "sbt-microsites" % "0.2.4")
+resolvers += Resolver.sonatypeRepo("snapshots")
+addSbtPlugin("com.fortysevendeg" % "sbt-microsites" % "0.2.5-SNAPSHOT")
 addSbtPlugin("com.eed3si9n" % "sbt-buildinfo" % "0.6.1")

src/main/resources/_sass/_colors.scss

@@ -93,6 +93,7 @@ body.docs {
 			}
 			&.active {
 				border-left: 3px solid $brand-primary;
+				color: #fff;
 			}
 		}
 	}

src/main/resources/_sass/_docs.scss

@@ -154,9 +154,6 @@
             }
         }
     }
-    ul.sub_section {
-        display: none;
-    }
     .active {
         display: block;
     }

src/main/scala/microsites/MicrositeKeys.scala

@@ -36,6 +36,9 @@ trait MicrositeKeys {
     "Optional. Microsite images directory. By default, it'll be the resourcesDirectory + '/microsite/img'")
   val micrositeCssDirectory = settingKey[File](
     "Optional. Microsite CSS directory. By default, it'll be the resourcesDirectory + '/microsite/css'")
+  val micrositeDataDirectory = settingKey[File](
+    "Optional. Microsite Data directory, useful to define the microsite data files " +
+      "(https://jekyllrb.com/docs/datafiles/). By default, it'll be the resourcesDirectory + '/microsite/data'")
   val micrositeExtraMdFiles = settingKey[Map[File, String]](
     "Optional. The key is related with the source file, the map value corresponds with the target relative file path. " +
       "This keys is useful for those document files that are located in a different places from the tutSourceDirectory. " +

src/main/scala/microsites/MicrositesPlugin.scala

@@ -63,6 +63,7 @@ object MicrositesPlugin extends AutoPlugin {
     micrositeHighlightTheme := "default",
     micrositeImgDirectory := (resourceDirectory in Compile).value / "microsite" / "img",
     micrositeCssDirectory := (resourceDirectory in Compile).value / "microsite" / "css",
+    micrositeDataDirectory := (resourceDirectory in Compile).value / "microsite" / "data",
     micrositeExtraMdFiles := Map.empty,
     micrositePalette := Map("brand-primary"   -> "#02B4E5",
                             "brand-secondary" -> "#1C2C52",
@@ -86,6 +87,7 @@ object MicrositesPlugin extends AutoPlugin {
         highlightTheme = micrositeHighlightTheme.value,
         micrositeImgDirectory = micrositeImgDirectory.value,
         micrositeCssDirectory = micrositeCssDirectory.value,
+        micrositeDataDirectory = micrositeDataDirectory.value,
         micrositeExtraMdFiles = micrositeExtraMdFiles.value,
         micrositeBaseUrl = micrositeBaseUrl.value,
         micrositeDocumentationUrl = micrositeDocumentationUrl.value,

src/main/scala/microsites/domain/MicrositeSettings.scala

@@ -26,6 +26,7 @@ case class MicrositeSettings(name: String,
                              highlightTheme: String,
                              micrositeImgDirectory: File,
                              micrositeCssDirectory: File,
+                             micrositeDataDirectory: File,
                              micrositeExtraMdFiles: Map[File, String],
                              micrositeBaseUrl: String,
                              micrositeDocumentationUrl: String,

src/main/scala/microsites/layouts/DocsLayout.scala

@@ -37,18 +37,7 @@ class DocsLayout(config: MicrositeSettings) extends Layout(config) {
   def sideBarAndContent: TypedTag[String] = {
     val text = s"${config.name} ${config.description}"
     div(id := "wrapper",
-      div(id := "sidebar-wrapper",
-        ul(id := "sidebar", cls := "sidebar-nav",
-          li(cls := "sidebar-brand",
-            a(href := "{{ site.baseurl }}/", cls := "brand",
-              div(cls := "brand-wrapper", style := "background:url('{{site.baseurl}}/img/sidebar_brand.png') no-repeat", span(config.name))
-            )
-          ),
-          "{% assign items = site.pages | sort: 'weight' %} {% for x in items %} {% if x.section == page.section %}",
-          li(a(href := "{{ site.baseurl }}{{x.url}}", cls := "{% if x.title == page.title %} active {% endif %}", "{{x.title}}")),
-          "{% endif %} {% endfor %}"
-        )
-      ),
+      div(id := "sidebar-wrapper", buildSidebar),
       div(id := "page-content-wrapper",
         div(cls := "nav",
           div(cls := "container-fluid",
@@ -87,6 +76,27 @@ class DocsLayout(config: MicrositeSettings) extends Layout(config) {
     )
   }
 
+  def buildSidebar: TypedTag[String] = {
+    val baseUrl = s"${config.micrositeDocumentationUrl}"
+    ul(id := "sidebar", cls := "sidebar-nav",
+      li(cls := "sidebar-brand",
+        a(href := "{{ site.baseurl }}/", cls := "brand",
+          div(cls := "brand-wrapper", style := "background:url('{{site.baseurl}}/img/sidebar_brand.png') no-repeat", span(config.name))
+        )
+      ),
+      "{% assign items = site.data.menu.options %} {% for x in items %} ",
+      li(
+        a(href := s"$baseUrl{{x.url}}", cls := "{% if x.title == page.title %} active {% endif %}", "{{x.title}}"),
+      "{% if x.nested_options %} ",
+      ul(cls := "sub_section",
+        "{% for sub in x.nested_options %} ",
+        li(a(href := s"$baseUrl{{sub.url}}", cls := "{% if sub.title == page.title and x.section == page.section %} active {% endif %}", "{{sub.title}}")),
+        "{% endfor %}"
+      ),
+      "{% endif %} {% endfor %}"
+    ))
+  }
+
   def scriptsDocs: List[TypedTag[String]] = scripts ++
     List(script(src := "{{ site.baseurl }}/js/main.js"))
 }

src/main/scala/microsites/util/MicrositeHelper.scala

@@ -43,6 +43,8 @@ class MicrositeHelper(config: MicrositeSettings) {
                          s"$targetDir$jekyllDir/img/")
     copyFilesRecursively(config.micrositeCssDirectory.getAbsolutePath,
                          s"$targetDir$jekyllDir/css/")
+    copyFilesRecursively(config.micrositeDataDirectory.getAbsolutePath,
+                         s"$targetDir$jekyllDir/_data/")
 
     config.micrositeExtraMdFiles foreach {
       case (sourceFile, relativeTargetFile) =>