Merge pull request #47 from jonas/admonition-directives

Admonition directives
lightbend · Oct 28, 2016 · 790f972 · 790f972
2 parents ecc84db + df2018b
commit 790f972
Show file tree

Hide file tree

Showing 12 changed files with 257 additions and 9 deletions.
diff --git a/build.sbt b/build.sbt
@@ -16,7 +16,7 @@
 
 lazy val paradox = project
   .in(file("."))
-  .aggregate(core, plugin, themePlugin, themes)
+  .aggregate(core, plugin, themePlugin, themes, docs)
   .enablePlugins(NoPublish)
   .settings(inThisBuild(List(
     organization := "com.lightbend.paradox",
@@ -104,7 +104,7 @@ lazy val genericTheme = (project in (file("themes") / "generic"))
   )
 
 lazy val docs = (project in file("docs"))
-  .enablePlugins(ParadoxPlugin)
+  .enablePlugins(NoPublish, ParadoxPlugin)
   .settings(
     name := "paradox docs",
     paradoxTheme := Some(builtinParadoxTheme("generic"))

diff --git a/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala b/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala
@@ -366,3 +366,20 @@ case class VarsDirective(variables: Map[String, String]) extends ContainerBlockD
     }
   }
 }
+
+/**
+ * Callout directive.
+ *
+ * Replaces property values in verbatim blocks.
+ */
+case class CalloutDirective(name: String, defaultTitle: String) extends ContainerBlockDirective(Array(name): _*) {
+  def render(node: DirectiveNode, visitor: Visitor, printer: Printer): Unit = {
+    val classes = node.attributes.classesString
+    val title = node.attributes.value("title", defaultTitle)
+
+    printer.print(s"""<div class="callout $name $classes">""")
+    printer.print(s"""<div class="callout-title">$title</div>""")
+    node.contentsNode.accept(visitor)
+    printer.print("""</div>""")
+  }
+}
diff --git a/core/src/main/scala/com/lightbend/paradox/markdown/Writer.scala b/core/src/main/scala/com/lightbend/paradox/markdown/Writer.scala
@@ -115,7 +115,9 @@ object Writer {
     FiddleDirective(context.location.tree.label),
     TocDirective(context.location),
     VarDirective(context.properties),
-    VarsDirective(context.properties)
+    VarsDirective(context.properties),
+    CalloutDirective("note", "Note"),
+    CalloutDirective("warning", "Warning")
   )
 
   class DefaultLinkRenderer(context: Context) extends LinkRenderer {

diff --git a/core/src/test/scala/com/lightbend/paradox/markdown/CalloutDirectiveSpec.scala b/core/src/test/scala/com/lightbend/paradox/markdown/CalloutDirectiveSpec.scala
@@ -0,0 +1,103 @@
+/*
+ * Copyright © 2015 - 2016 Lightbend, Inc. <http://www.lightbend.com>
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.lightbend.paradox.markdown
+
+import com.lightbend.paradox.tree.Tree.Location
+
+class CalloutDirectiveSpec extends MarkdownBaseSpec {
+
+  val testProperties = Map("version" -> "1.2.3")
+
+  implicit val context: Location[Page] => Writer.Context = { loc =>
+    writerContext(loc).copy(properties = testProperties)
+  }
+
+  "Note directive" should "render notes" in {
+    markdown("""
+      |@@@ note
+      |Latest version is @var[version]
+      |@@@
+      """) shouldEqual html("""
+      |<div class="callout note">
+      |<div class="callout-title">Note</div>
+      |Latest version is 1.2.3
+      |</div>
+      """)
+  }
+
+  it should "support class and title attributes" in {
+    markdown("""
+      |@@@ note { title="Release Notes" .release-note }
+      |
+      |New features:
+      |
+      | - Support X
+      | - Make Y configurable
+      |
+      |Bug fixes:
+      |
+      | - Fix segfault in Z
+      |
+      |@@@
+      """) shouldEqual html("""
+      |<div class="callout note release-note">
+      |<div class="callout-title">Release Notes</div>
+      |<p>New features:</p>
+      |<ul>
+      |<li>Support X</li>
+      |<li>Make Y configurable</li>
+      |</ul>
+      |<p>Bug fixes:</p>
+      |<ul>
+      |<li>Fix segfault in Z</li>
+      |</ul>
+      |</div>
+      """)
+  }
+
+  "Warning directive" should "render warnings" in {
+    markdown("""
+      |@@@ warning
+      |Version @var[version] is deprecated!
+      |@@@
+      """) shouldEqual html("""
+      |<div class="callout warning">
+      |<div class="callout-title">Warning</div>
+      |Version 1.2.3 is deprecated!
+      |</div>
+      """)
+  }
+
+  it should "support class and title attributes" in {
+    markdown("""
+      |@@@ warning { title='Caution!' .caution }
+      |
+      |Version @var[version] is experimental!
+      |
+      |Expect breaking API changes.
+      |
+      |@@@
+      """) shouldEqual html("""
+      |<div class="callout warning caution">
+      |<div class="callout-title">Caution!</div>
+      |<p>Version 1.2.3 is experimental!</p>
+      |<p>Expect breaking API changes.</p>
+      |</div>
+      """)
+  }
+
+}
diff --git a/docs/src/main/paradox/features/callouts.md b/docs/src/main/paradox/features/callouts.md
@@ -0,0 +1,74 @@
+Callouts
+========
+
+Use callouts to discuss and clarify specific topics. In the resulting output,
+the content inside the callout will appear in a separate block.
+
+Paradox provides callouts for notes and warnings which can further be
+customized to fit specific needs.
+
+## @@@note callout
+
+Notes are written as:
+
+```
+@@@ note
+
+For the connection pooled client side the idle period is counted only when the
+pool has no pending requests waiting.
+
+@@@
+```
+
+will render as:
+
+@@@ note
+
+For the connection pooled client side the idle period is counted only when the
+pool has no pending requests waiting.
+
+@@@
+
+The note title can be customized using the `title` attribute. For example:
+
+```
+@@@ note { title=Hint }
+...
+@@@
+```
+
+will render as:
+
+@@@ note { title=Hint }
+...
+@@@
+
+## @@@warning callout
+
+Warnings are written as:
+
+```
+@@@ warning
+Make sure to use basic authentication only over SSL/TLS because credentials are transferred in plaintext.
+@@@
+```
+
+and will render as:
+
+@@@ warning
+Make sure to use basic authentication only over SSL/TLS because credentials are transferred in plaintext.
+@@@
+
+The warning title can be customized using the `title` attribute. For example:
+
+```
+@@@ warning { title='Caveat Emptor' }
+...
+@@@
+```
+
+will render as:
+
+@@@ warning { title='Caveat Emptor' }
+...
+@@@
diff --git a/docs/src/main/paradox/index.md b/docs/src/main/paradox/index.md
@@ -4,7 +4,7 @@ Paradox
 Paradox is a Markdown documentation tool for software projects.
 The Github repo is [lightbend/paradox][repo].
 
-**Paradox is NOT supported under Lightbend subscription.**
+**Paradox is NOT supported under the Lightbend subscription.**
 
 ### Setup
 
@@ -32,7 +32,7 @@ Your markdown documentation will go inside `src/main/paradox/`. For example, you
 ### Key features
 
 - Supports Github flavored Markdown powered by [Pegdown][].
-- Principled markdown exntension using generic directives syntax.
+- Principled markdown extension using generic directives syntax.
 - Github-friendly Markdown source (links work).
 - Code snippet inclusion for compilable code examples.
 - Templating and theming.
@@ -52,6 +52,7 @@ which basically means that all of our extensions would start with `@` (for inlin
 * [Organizing pages](features/organizing-pages.md)
 * [Linking](features/linking.md)
 * [Snippet inclusion](features/snippet-inclusion.md)
+* [Callouts](features/callouts.md)
 * [Templating](features/templating.md)
 
 @@@

diff --git a/notes/0.2.1.markdown b/notes/0.2.1.markdown
@@ -2,7 +2,7 @@
 
 - `paradoxTheme` now defaults to `Some(builtinParadoxTheme("generic"))`. To opt out of a theme you must set `None` explicitly. [#19][19] by [@eed3si9n][@eed3si9n]
 
-### Fixes and enhacements
+### Fixes and enhancements
 
 - Allows non-H1 headers. [#18][18] by [@dwijnand][@dwijnand]
 - Fixes NPE when `page.st` is not set. [#19][19] by [@eed3si9n][@eed3si9n]

diff --git a/notes/0.2.2.markdown b/notes/0.2.2.markdown
@@ -1,4 +1,4 @@
-### Fixes and enhacements
+### Fixes and enhancements
 
 - Aggregates from multiple snip labels. [#22][22] by [@jonas][@jonas]
 

diff --git a/notes/0.2.3.markdown b/notes/0.2.3.markdown
@@ -1,4 +1,4 @@
-### Fixes and enhacements
+### Fixes and enhancements
 
 - Adds per-page properties front matter.
 - Adds parameterized links.

diff --git a/notes/0.2.5.markdown b/notes/0.2.5.markdown
@@ -1,4 +1,4 @@
-### Fixes and enhacements
+### Fixes and enhancements
 
 - Fixes css/js theme generation. [#30][30] by [@gsechaud][@gsechaud]
 - Fixes ref bug with anchor. [#34][34] by [@gsechaud][@gsechaud]

diff --git a/notes/0.2.6.markdown b/notes/0.2.6.markdown
@@ -0,0 +1,19 @@
+### Fixes and enhancements
+
+- Fixes handling of paths on Windows. [#42][42] by [@drewhk][@drewhk]
+- Document [Paradox][Paradox] using Paradox. [#44][44] by [@gsechaud][@gsechaud] and [@eed3si9n][@eed3si9n]
+- Validate PRs on Windows using [AppVeyor][AppVeyor]. [#45][45] by [@gsechaud][@gsechaud]
+- Fix `@ref` fragment links and normalize relative links. [#46][46] by [@jonas][@jonas]
+- Add note and warning callout directives. [#47][47] by [@jonas][@jonas]
+
+  [42]: https://github.com/lightbend/paradox/issues/42
+  [44]: https://github.com/lightbend/paradox/pull/44
+  [45]: https://github.com/lightbend/paradox/pull/45
+  [46]: https://github.com/lightbend/paradox/pull/46
+  [47]: https://github.com/lightbend/paradox/pull/47
+  [@drewhk]: https://github.com/drewhk
+  [@eed3si9n]: https://github.com/eed3si9n
+  [@gsechaud]: https://github.com/gsechaud
+  [@jonas]: https://github.com/jonas
+  [AppVeyor]: https://www.appveyor.com/
+  [Paradox]: http://developer.lightbend.com/docs/paradox/latest/
diff --git a/themes/generic/src/main/assets/css/page.css b/themes/generic/src/main/assets/css/page.css
@@ -380,6 +380,38 @@ blockquote p code {
   padding-right: 0.4em !important;
 }
 
+/* callout */
+
+.callout {
+  border: none;
+  border-left: 10px solid #4078c0;
+  background-color: rgba(64, 120, 192, 0.1);
+}
+
+.callout.warning {
+  border-color: #DB504A;
+  background-color: #fff3d9;
+}
+
+.callout .callout-title {
+  font-weight: bold;
+  margin-bottom: 0.33em;
+}
+
+.callout div ~ p {
+  margin-top: 0;
+}
+
+.callout p ~ p {
+  margin-top: 1em;
+  margin-bottom: 0;
+}
+
+.callout p code {
+  background: #fff;
+  padding-right: 0.4em !important;
+}
+
 /* footnotes */
 
 small {