Update usage guide

build.sbt

@@ -106,7 +106,7 @@ lazy val refined =
   crossProject(JSPlatform, JVMPlatform)
     .in(file("modules/refined"))
     .settings(moduleName := "ciris-refined", name := "Ciris refined")
-    .settings(libraryDependencies += "eu.timepit" %%% "refined" % "0.8.7")
+    .settings(libraryDependencies += "eu.timepit" %%% "refined" % refinedVersion)
     .settings(scalaSettings)
     .settings(testSettings)
     .jsSettings(jsModuleSettings)
@@ -236,13 +236,13 @@ lazy val docs = project
         s"""
           |This is the API documentation for [[https://cir.is Ciris]]: lightweight, extensible, and validated configuration loading in Scala.<br>
           |The documentation is kept up-to-date with new releases, currently documenting release [[https://github.com/vlovgr/ciris/releases/tag/v$version v$version]] on Scala $scalaTargetVersion.<br>
-          |Note that the API documentation targets the JVM, and there may be differences on Scala.js and Scala Native.
+          |Please note that the documentation targets the JVM, and there may be differences on Scala.js and Scala Native.
           |
           |Ciris is divided into the following set of modules.
           |
           | - The [[ciris.cats cats]] module integrates with [[https://github.com/typelevel/cats cats]] for typeclasses and typeclass instances.
           | - The [[ciris.cats.effect cats-effect]] module integrates with [[https://github.com/typelevel/cats-effect cats-effect]] for typeclasses for effect types.
-          | - The [[ciris core]] module provides basic functionality and support for reading standard library types.
+          | - The [[ciris core]] module provides basic functionality and support for standard library types.
           | - The [[ciris.enumeratum enumeratum]] module integrates with [[https://github.com/lloydmeta/enumeratum enumeratum]] to be able to read enumerations.
           | - The [[ciris.generic generic]] module uses [[https://github.com/milessabin/shapeless shapeless]] to be able to read products and coproducts.
           | - The [[ciris.refined refined]] module integrates with [[https://github.com/fthomas/refined refined]] to be able to read refinement types.
@@ -255,6 +255,10 @@ lazy val docs = project
       IO.write(target, content)
       target
     },
+    libraryDependencies ++= Seq(
+      "org.typelevel" %% "kittens" % "1.0.0-RC3",
+      "eu.timepit" %% "refined-cats" % refinedVersion
+    ),
     scalacOptions --= Seq("-Xlint", "-Ywarn-unused", "-Ywarn-unused-import"),
     unidocProjectFilter in (ScalaUnidoc, unidoc) := inAnyProject -- inProjects(noDocumentationModules: _*),
     siteSubdirName in ScalaUnidoc := micrositeDocumentationUrl.value,
@@ -439,7 +443,6 @@ generateReadme in ThisBuild := {
   val source = IO.read((tutTargetDirectory in docs).value / "index.md")
   val readme =
     source
-      .replaceAll("""\n(#+) <a[^>]+>(.+)<\/a>""", "\n$1 $2") // Remove header links
       .replaceAll("^\\s*---[^(---)]*---\\s*", "") // Remove metadata
   val target = (baseDirectory in ciris).value / "readme.md"
   IO.write(target, readme)
@@ -458,10 +461,9 @@ updateReadme in ThisBuild := {
 val generateContributing = taskKey[File]("Generates the contributing guide")
 generateContributing in ThisBuild := {
   (tut in docs).value
-  val source = IO.read((tutTargetDirectory in docs).value / "docs" / "contributing" / "readme.md")
+  val source = IO.read((tutTargetDirectory in docs).value / "docs" / "contributing.md")
   val contributing =
     source
-      .replaceAll("""\n(#+) <a[^>]+>(.+)<\/a>""", "\n$1 $2") // Remove header links
       .replaceAll("^\\s*---[^(---)]*---\\s*", "") // Remove metadata
   val target = (baseDirectory in ciris).value / "contributing.md"
   IO.write(target, contributing)
@@ -652,3 +654,5 @@ addCommandsAlias("validateDocs", List("docTests", "docs/unidoc", "docs/tut"))
 lazy val scalaTestVersion = "3.0.5"
 
 lazy val scalaCheckVersion = "1.13.5"
+
+lazy val refinedVersion = "0.8.7"

docs/src/main/resources/microsite/css/custom.css

@@ -6,6 +6,7 @@ a:hover, a:focus {
 
 blockquote {
   font-size: 13px;
+  margin-top: 20px;
 }
 
 h4 {
@@ -16,8 +17,15 @@ section h1:first-of-type {
   margin-top: 0;
 }
 
-table, .highlight {
-  margin-bottom: 12.5px !important;
+table {
+  margin-bottom: 12.5px;
+}
+
+pre.highlight code.hljs {
+  white-space: pre;
+  word-break: normal;
+  word-wrap: normal;
+  overflow: auto;
 }
 
 /* Home layout */
@@ -34,6 +42,15 @@ table, .highlight {
   color: #f3f3f3;
 }
 
+#site-main .use .container {
+  max-width: 845px;
+}
+
+#site-main .use .container img {
+  margin-top: 15px;
+  margin-bottom: 15px;
+}
+
 .technologies {
   display: none;
 }
@@ -46,6 +63,35 @@ table, .highlight {
   color: rgba(243, 243, 243, 0.6);
 }
 
+#site-main #content .header-link {
+  float: left;
+  font-size: 20px;
+  line-height: 1;
+  margin-left: -20px;
+  margin-top: 4px;
+  opacity: 0;
+  padding-right: 0;
+  transition: opacity 0.2s ease, color 0.2s ease;
+}
+
+#site-main #content h3 .header-link {
+  font-size: 18px;
+  margin-top: 2px;
+}
+
+#site-main #content h4 .header-link {
+  font-size: 15px;
+  margin-top: 0;
+  margin-left: -17px;
+}
+
+#site-main #content h1:hover .header-link,
+#site-main #content h2:hover .header-link,
+#site-main #content h3:hover .header-link,
+#site-main #content h4:hover .header-link {
+  opacity: 1;
+}
+
 /* Docs layout */
 
 .sidebar-nav > li > a:hover {
@@ -73,8 +119,40 @@ table, .highlight {
   display: none;
 }
 
-#page-content-wrapper section a:hover, #page-content-wrapper section a:focus {
+#page-content-wrapper section {
+  max-width: 845px;
+}
+
+#page-content-wrapper .nav {
+  max-width: 875px;
+  margin-right: 30px;
+}
+
+#page-content-wrapper section p,
+#page-content-wrapper section ul {
+  text-align: justify;
+  hyphens: auto;
+  -ms-hyphens: auto;
+  -webkit-hyphens: auto;
+}
+
+#page-content-wrapper section p code,
+#page-content-wrapper section ul li code {
+  white-space: nowrap;
+}
+
+#page-content-wrapper section > *:last-child { margin-bottom: 0; }
+#page-content-wrapper section > *:last-child > .highlight { margin-bottom: 0; }
+#page-content-wrapper section > .footnotes:last-child > ol { margin-bottom: 0; }
+#page-content-wrapper section > .footnotes:last-child > ol > li:last-child > p:last-child { margin-bottom: 0; }
+
+#page-content-wrapper section a:hover,
+#page-content-wrapper section a:focus {
   text-decoration: underline;
   text-decoration-skip: ink;
   -webkit-text-decoration-skip: ink;
 }
+
+section > ul + .highlighter-rouge {
+  margin-left: 40px;
+}

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

@@ -1,17 +1,45 @@
 options:
   - title: Usage Basics
     url: docs/basics
-  - title: Core Concepts
-    url: docs/concepts
-  - title: Modules Overview
-    url: docs/modules
-  - title: Encoding Validation
-    url: docs/validation
-  - title: Multiple Environments
-    url: docs/environments
+  - title: Configuration Topics
+    url: docs/topics
+    nested_options:
+      - title: Encoding Validation
+        url: docs/validation
+      - title: Multiple Environments
+        url: docs/environments
+      - title: Logging Configurations
+        url: docs/logging
   - title: Configuration Sources
     url: docs/sources
-  - title: Custom Decoders
+    nested_options:
+      - title: Current Supported Sources
+        url: docs/supported-sources
+      - title: Supporting New Sources
+        url: docs/supporting-new-sources
+  - title: Configuration Decoders
     url: docs/decoders
+    nested_options:
+      - title: Current Supported Types
+        url: docs/supported-types
+      - title: Supporting New Types
+        url: docs/supporting-new-types
+  - title: Modules Overview
+    url: docs/modules
+    nested_options:
+      - title: Cats Module
+        url: docs/cats-module
+      - title: Cats Effect Module
+        url: docs/cats-effect-module
+      - title: Enumeratum Module
+        url: docs/enumeratum-module
+      - title: Generic Module
+        url: docs/generic-module
+      - title: Refined Module
+        url: docs/refined-module
+      - title: Spire Module
+        url: docs/spire-module
+      - title: Squants Module
+        url: docs/squants-module
   - title: Contributing Guide
     url: docs/contributing

docs/src/main/resources/microsite/js/custom.js

@@ -1,2 +1,36 @@
 // Cleanup footer credits
 $('#site-footer .row:last p').html('Website built with <a href="https://47deg.github.io/sbt-microsites" target="_blank">sbt-microsites</a> by <a href="https://www.47deg.com" target="_blank">47 Degrees</a>')
+
+// Linkify main page
+jQuery(document).ready(function() {
+  linkifyAllLevels("#site-main #content");
+});
+
+var anchorForId = function (id) {
+  var anchor = document.createElement("a");
+  anchor.className = "header-link";
+  anchor.href      = "#" + id;
+  anchor.innerHTML = "<i class=\"fa fa-link\"></i>";
+  return anchor;
+};
+
+var linkifyAnchors = function (level, containingElement) {
+  var headers = containingElement.getElementsByTagName("h" + level);
+  for (var h = 0; h < headers.length; h++) {
+    var header = headers[h];
+
+    if (typeof header.id !== "undefined" && header.id !== "") {
+      header.appendChild(anchorForId(header.id));
+    }
+  }
+};
+
+var linkifyAllLevels = function (blockSelector) {
+  var contentBlock = document.querySelector(blockSelector);
+  if (!contentBlock) {
+    return;
+  }
+  for (var level = 1; level <= 4; level++) {
+    linkifyAnchors(level, contentBlock);
+  }
+};