diff --git a/build.sbt b/build.sbt index a587022c..1ecf8dbb 100644 --- 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 index f8758231..c6a61d10 100644 --- 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"""
""") + printer.print(s"""
$title
""") + node.contentsNode.accept(visitor) + printer.print("""
""") + } +} diff --git a/core/src/main/scala/com/lightbend/paradox/markdown/Writer.scala b/core/src/main/scala/com/lightbend/paradox/markdown/Writer.scala index 3832006d..9a399267 100644 --- 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 new file mode 100644 index 00000000..a603d693 --- /dev/null +++ b/core/src/test/scala/com/lightbend/paradox/markdown/CalloutDirectiveSpec.scala @@ -0,0 +1,103 @@ +/* + * Copyright © 2015 - 2016 Lightbend, Inc. + * + * 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(""" + |
+ |
Note
+ |Latest version is 1.2.3 + |
+ """) + } + + 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(""" + |
+ |
Release Notes
+ |

New features:

+ | + |

Bug fixes:

+ | + |
+ """) + } + + "Warning directive" should "render warnings" in { + markdown(""" + |@@@ warning + |Version @var[version] is deprecated! + |@@@ + """) shouldEqual html(""" + |
+ |
Warning
+ |Version 1.2.3 is deprecated! + |
+ """) + } + + it should "support class and title attributes" in { + markdown(""" + |@@@ warning { title='Caution!' .caution } + | + |Version @var[version] is experimental! + | + |Expect breaking API changes. + | + |@@@ + """) shouldEqual html(""" + |
+ |
Caution!
+ |

Version 1.2.3 is experimental!

+ |

Expect breaking API changes.

+ |
+ """) + } + +} diff --git a/docs/src/main/paradox/features/callouts.md b/docs/src/main/paradox/features/callouts.md new file mode 100644 index 00000000..01670fef --- /dev/null +++ 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 index 5bca9692..2ee2e9c9 100644 --- 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 index 09db110b..4d813207 100644 --- 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 index c0ea521d..abae5d35 100644 --- 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 index ede28e3c..acd3b1e9 100644 --- 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 index d4063def..7bb2688b 100644 --- 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 new file mode 100644 index 00000000..4de51180 --- /dev/null +++ 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 index 944928e8..86b36382 100644 --- 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 {