From 226a0cd3efffea206e43fcc85fced49036018dd9 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Wed, 26 Oct 2016 20:31:11 -0400 Subject: [PATCH 1/4] Aggregate the docs project Makes `~docs/paradox` work as expected. --- build.sbt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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")) From b7e698644b54644e30e57ecc3fb501544530f7d7 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Wed, 26 Oct 2016 20:45:46 -0400 Subject: [PATCH 2/4] Fix typos in release notes and index page --- docs/src/main/paradox/index.md | 4 ++-- notes/0.2.1.markdown | 2 +- notes/0.2.2.markdown | 2 +- notes/0.2.3.markdown | 2 +- notes/0.2.5.markdown | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/src/main/paradox/index.md b/docs/src/main/paradox/index.md index 5bca9692..a62b308c 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. 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] From 235dd00da0188b702706bf0ba3605a38b78da785 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Wed, 26 Oct 2016 21:42:04 -0400 Subject: [PATCH 3/4] Add 0.2.6 notes --- notes/0.2.6.markdown | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 notes/0.2.6.markdown diff --git a/notes/0.2.6.markdown b/notes/0.2.6.markdown new file mode 100644 index 00000000..f04844d8 --- /dev/null +++ b/notes/0.2.6.markdown @@ -0,0 +1,17 @@ +### 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] + + [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 + [@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/ From df2018b18b4a4e28422b7950b1ddf2d2ec9740d8 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Wed, 26 Oct 2016 14:55:05 -0400 Subject: [PATCH 4/4] Fix #7: Add note and warning callout directives The warning border color is based on this generated palette: - https://coolors.co/4078c0-084c61-db504a-e3b505-4f6d7a --- .../paradox/markdown/Directive.scala | 17 +++ .../lightbend/paradox/markdown/Writer.scala | 4 +- .../markdown/CalloutDirectiveSpec.scala | 103 ++++++++++++++++++ docs/src/main/paradox/features/callouts.md | 74 +++++++++++++ docs/src/main/paradox/index.md | 1 + notes/0.2.6.markdown | 2 + themes/generic/src/main/assets/css/page.css | 32 ++++++ 7 files changed, 232 insertions(+), 1 deletion(-) create mode 100644 core/src/test/scala/com/lightbend/paradox/markdown/CalloutDirectiveSpec.scala create mode 100644 docs/src/main/paradox/features/callouts.md 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:

+ |
    + |
  • Support X
    • + |
  • Make Y configurable
    • + |
+ |

Bug fixes:

+ |
    + |
  • Fix segfault in Z
    • + |
+ |
+ """) + } + + "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 a62b308c..2ee2e9c9 100644 --- a/docs/src/main/paradox/index.md +++ b/docs/src/main/paradox/index.md @@ -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.6.markdown b/notes/0.2.6.markdown index f04844d8..4de51180 100644 --- a/notes/0.2.6.markdown +++ b/notes/0.2.6.markdown @@ -4,11 +4,13 @@ - 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 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 {