add 'Edit Page' feature to doc pages (#278)

* add 'Edit Page' feature to doc pages * restructure MicrositeEditButtonSettings * fix Arbitraries
47degrees · Oct 9, 2018 · ad5a20a · ad5a20a
1 parent 9c06a5a
commit ad5a20a
Show file tree

Hide file tree

Showing 7 changed files with 62 additions and 4 deletions.
diff --git a/docs/src/main/tut/docs/settings.md b/docs/src/main/tut/docs/settings.md
@@ -327,3 +327,14 @@ micrositeConfigYaml := ConfigYml(
 ```
 micrositeFooterText := Some("<b>Bob</b> the <i>Builder</i>")
 ```
+
+- `micrositeEditButtonText`: This setting allows the optional inclusion and configuration of an edit button on pages
+with the docs layout. The button links to the given path of the page in it's repository.
+By default, it is set to `None` and not visible. To enable, set the MicrositeEditButton with text
+for the button and the basePath for the file. The basePath is comprised of the file URL excluding the top-level
+repository URL and should include the dynamic property `{{page.path}}` that will be generated for each page when Jekyll
+compiles the site.  **The strings are passed in unsanitized to the templating engine.**
+
+```
+micrositeEditButton := Some(MicrositeEditButton("Improve this Page", "/edit/master/docs/src/main/tut/{{ page.path }}"))
+```
diff --git a/src/main/resources/_sass/_docs.scss b/src/main/resources/_sass/_docs.scss
@@ -198,6 +198,10 @@
     }
 }
 
+.edit-button {
+    padding: 0 30px 10px;
+}
+
 @media (min-width: 768px) {
     #wrapper {
         padding-left: 250px;

diff --git a/src/main/scala/microsites/MicrositeKeys.scala b/src/main/scala/microsites/MicrositeKeys.scala
@@ -153,6 +153,11 @@ trait MicrositeKeys {
   )
 
   val publishMicrositeCommandKey: String = "publishMicrositeCommand"
+
+  val micrositeEditButton: SettingKey[Option[MicrositeEditButton]] =
+    settingKey[Option[MicrositeEditButton]](
+      "Optional. Add a button in DocsLayout pages that links to the file in the repository."
+    )
 }
 
 object MicrositeKeys extends MicrositeKeys
@@ -201,7 +206,7 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {
           shareOnSocial = micrositeShareOnSocial.value
         ),
         templateTexts = MicrositeTemplateTexts(
-          footer = micrositeFooterText.value
+          micrositeFooterText.value
         ),
         configYaml = configWithAllCustomVariables,
         fileLocations = MicrositeFileLocations(
@@ -245,6 +250,9 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {
           gitHostingUrl = micrositeGitHostingUrl.value,
           gitSidecarChat = micrositeGitterChannel.value,
           gitSidecarChatUrl = micrositeGitterChannelUrl.value
+        ),
+        editButtonSettings = MicrositeEditButtonSettings(
+          micrositeEditButton.value
         )
       ))
   }

diff --git a/src/main/scala/microsites/MicrositesPlugin.scala b/src/main/scala/microsites/MicrositesPlugin.scala
@@ -108,6 +108,7 @@ object MicrositesPlugin extends AutoPlugin {
     micrositeGitterChannel := true,
     micrositeGitterChannelUrl := s"${micrositeGithubOwner.value}/${micrositeGithubRepo.value}",
     micrositeFooterText := Some(layouts.Layout.footer.toString),
+    micrositeEditButton := None,
     micrositeGithubLinks := true,
     includeFilter in makeSite := "*.html" | "*.css" | "*.png" | "*.jpg" | "*.jpeg" | "*.gif" | "*.js" | "*.swf" | "*.md" | "*.webm" | "*.ico" | "CNAME" | "*.yml" | "*.svg" | "*.json",
     includeFilter in Jekyll := (includeFilter in makeSite).value,

diff --git a/src/main/scala/microsites/layouts/DocsLayout.scala b/src/main/scala/microsites/layouts/DocsLayout.scala
@@ -92,7 +92,8 @@ class DocsLayout(config: MicrositeSettings) extends Layout(config) {
         ),
         div(id := "content", data("github-owner") := config.gitSettings.githubOwner, data("github-repo") := config.gitSettings.githubRepo,
           div(cls := "content-wrapper",
-            section("{{ content }}")
+            section("{{ content }}"),
+            editButton
           )
         )
       )
@@ -155,4 +156,20 @@ class DocsLayout(config: MicrositeSettings) extends Layout(config) {
       (if (config.micrositeKazariSettings.micrositeKazariEnabled)
          List(script(src := "{{ site.baseurl }}/js/kazari.js"))
        else List.empty[TypedTag[String]])
+
+  def editButton: Option[TypedTag[String]] =
+    config.editButtonSettings.button match {
+      case Some(button) =>
+        Some(
+          div(
+            cls := "edit-button",
+            a(
+              href := config.gitSiteUrl,
+              href := button.basePath,
+              cls := "btn-sm btn-info",
+              button.text
+            )
+          ))
+      case _ => None
+    }
 }
diff --git a/src/main/scala/microsites/microsites.scala b/src/main/scala/microsites/microsites.scala
@@ -81,6 +81,10 @@ case class MicrositeVisualSettings(
 
 case class MicrositeTemplateTexts(footer: Option[String])
 
+case class MicrositeEditButton(text: String, basePath: String)
+
+case class MicrositeEditButtonSettings(button: Option[MicrositeEditButton])
+
 case class MicrositeSettings(
     identity: MicrositeIdentitySettings,
     visualSettings: MicrositeVisualSettings,
@@ -89,6 +93,7 @@ case class MicrositeSettings(
     fileLocations: MicrositeFileLocations,
     urlSettings: MicrositeUrlSettings,
     gitSettings: MicrositeGitSettings,
+    editButtonSettings: MicrositeEditButtonSettings,
     micrositeKazariSettings: KazariSettings) {
 
   def gitSiteUrl: String = {

diff --git a/src/test/scala/microsites/util/Arbitraries.scala b/src/test/scala/microsites/util/Arbitraries.scala
@@ -22,7 +22,6 @@ import microsites.MicrositeKeys._
 import microsites._
 import org.scalacheck.Arbitrary
 import org.scalacheck.Gen._
-import sbt.Resolver
 
 trait Arbitraries {
 
@@ -103,6 +102,13 @@ trait Arbitraries {
     } yield MicrositeFavicon(filename, size)
   }
 
+  implicit def micrositeEditButtonArbitrary: Arbitrary[Option[MicrositeEditButton]] = Arbitrary {
+    for {
+      text     <- Arbitrary.arbitrary[String]
+      basePath <- Arbitrary.arbitrary[String]
+    } yield Some(MicrositeEditButton(text, basePath))
+  }
+
   implicit def settingsArbitrary: Arbitrary[MicrositeSettings] = Arbitrary {
     for {
       name                                   ← Arbitrary.arbitrary[String]
@@ -148,6 +154,7 @@ trait Arbitraries {
       micrositeKazariDependencies            ← dependenciesListArbitrary.arbitrary
       micrositeKazariResolvers               ← Arbitrary.arbitrary[Seq[String]]
       micrositeFooterText                    ← Arbitrary.arbitrary[Option[String]]
+      micrositeEditButton                    ← micrositeEditButtonArbitrary.arbitrary
     } yield
       MicrositeSettings(
         MicrositeIdentitySettings(
@@ -165,7 +172,9 @@ trait Arbitraries {
           palette,
           favicon,
           shareOnSocial),
-        MicrositeTemplateTexts(micrositeFooterText),
+        MicrositeTemplateTexts(
+          micrositeFooterText
+        ),
         micrositeConfigYaml,
         MicrositeFileLocations(
           micrositeImgDirectory,
@@ -192,6 +201,9 @@ trait Arbitraries {
           gitHostingUrl,
           gitSidecarChat,
           gitSidecarChatUrl),
+        MicrositeEditButtonSettings(
+          micrositeEditButton
+        ),
         KazariSettings(
           micrositeKazariEnabled,
           micrositeKazariEvaluatorUrl,