Merge branch 'master' into updateScalaFiddleIntegration

core/src/main/java/org/pegdown/ParserWithDirectives.java

@@ -80,7 +80,7 @@ public Rule VarName() {
                 Letter(), name.append(matchedChar()),
                 ZeroOrMore(
                         FirstOf(
-                                Sequence(FirstOf(Alphanumeric(), AnyOf("+-_")), name.append(matchedChar())),
+                                Sequence(FirstOf(Alphanumeric(), AnyOf("+-_.")), name.append(matchedChar())),
                                 Sequence('\\', VAR_SUBSTITUTION_MARKER, name.append(VAR_SUBSTITUTION_MARKER))
                         )
                 ),

core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala

@@ -81,7 +81,7 @@ abstract class ContainerBlockDirective(val names: String*) extends Directive {
 /**
  * Directives with defined "source" semantics.
  */
-sealed trait SourceDirective { this: Directive =>
+trait SourceDirective { this: Directive =>
   def page: Page
 
   protected def resolvedSource(node: DirectiveNode, page: Page): String = {

docs/src/main/paradox/configuration.md

@@ -0,0 +1,64 @@
+# Configuration
+
+Paradox is configured with sbt settings.
+
+TBD - explain main settings here
+
+## Overlays
+
+It is possible to add one or more overlays to a paradox project. Their location can be defined at build level and is applied to all configurations in the project unless we overwrite it for a particular configuration.
+
+```scala
+val DocsFirst = config("docs-first")
+val DocsSecond = config("docs-second")
+
+lazy val root = (project in file(".")).
+  enablePlugins(ParadoxPlugin).
+  settings(
+    name := "Paradox Project",
+    paradoxTheme := Some(builtinParadoxTheme("generic")),
+    paradoxOverlayDirectories := Seq(baseDirectory.value / "src" / "docs-common"),
+    ParadoxPlugin.paradoxSettings(DocsFirst),
+    ParadoxPlugin.paradoxSettings(DocsSecond),
+    paradoxOverlayDirectories in DocsFirst := Seq(baseDirectory.value / "src" / "docs-first-common", baseDirectory.value / "src" / "docs-second-common")
+  )
+```
+
+Markdown source files from the overlay directories are merged with the ones in the main project directory and are generated as if they were part of this latest.
+If a file duplicate exist between the directories, the overlay file is dropped in favour of the main directory file.
+
+## Multi Configuration
+
+Paradox supports multiple sbt configurations. Each configuration is by default located to `src/configName` of the project,
+with the target directory defined as `target/paradox/site/configName`, `configName` corresponding to configuration.name of
+a particular configuration. There still remains the usual main project in `src/main` of course if you don't need multiple
+paradox project directories.
+
+To associate a configuration to paradox, use its settings, and change its default source and/or target directorie(s) if needed:
+
+```scala
+val SomeConfig = config("some-config")
+
+lazy val root = (project in file(".")).
+  enablePlugins(ParadoxPlugin).
+  settings(
+    paradoxTheme = Some(builtinParadoxTheme("generic")),
+    ParadoxPlugin.paradoxSettings(SomeConfig),
+    sourceDirectory in SomeConfig := baseDirectory.value / "src" / "configuration-source-directory",
+    (target in paradox) in SomeConfig := baseDirectory.value / "paradox" / "site" / "configuration-target-directory"
+  )
+```
+
+Now, either you run paradox on one configuration; "sbt someConfig:paradox" or you can run the main project with the usual way; "sbt paradox".
+
+## Version warning
+
+Paradox supports showing a warning when users browse documentation which is not the current released version. This is achieved by storing a JSON file (`paradox.json`) together with the generated site and specifying a stable URL to where the released version will be available.
+
+The built in theme (`generic`) contains Javascript to fetch the JSON file and compare the version with the version for which the documentation showing was generated. Whenever they differ, a warning text shows on every page offering a link to the released version's page.
+
+To use this functionality, add `project.url` to Paradox properties
+
+```scala
+paradoxProperties += ("project.url" -> "https://developer.lightbend.com/docs/paradox/current/")
+```

docs/src/main/paradox/customization/extensions.md

@@ -0,0 +1,18 @@
+# Pre-packaged Extensions
+
+## Themes
+
+ * [Akka Paradox Theme + Extensions](https://github.com/akka/akka-paradox): Custom theme used by the 
+   [Akka documentation](https://akka.io/docs/akka/):
+
+   ![Akka Docs Screenshot](../img/akka-paradox-theme.png)
+
+ * [Paradox Material Theme](https://github.com/jonas/paradox-material-theme): A theme built using Google's Material Design
+   guidelines:
+
+   ![Material Theme Screenshot](../img/material-theme.png)
+
+## Directives
+
+ * [Apidoc directive](https://github.com/lightbend/sbt-paradox-apidoc): `@apidoc` directive that will automatically
+   create links to Java Apidoc or Scala Scaladoc depending on a language choosing dropdown

docs/src/main/paradox/customization/index.md

@@ -0,0 +1,9 @@
+# Customization
+
+@@toc
+
+@@@ index
+ * [Templating](templating.md)
+ * [Themes](theming.md)
+ * [Pre-packaged Extensions](extensions.md)
+@@@

docs/src/main/paradox/features/templating.md → docs/src/main/paradox/customization/templating.md

@@ -4,10 +4,15 @@ tripleDelimiters: ```
 
   [st]: http://www.stringtemplate.org/
 
-Templating
-----------
+# Templating
 
-Paradox uses [StringTemplate][st] for the basic templating.
+Paradox uses [StringTemplate][st] for the basic templating, i.e. for creating full HTML documents from documentation content
+generated from markdown. A set of templates of assets that comprises all that is needed for a full documentation page,
+is called a @ref[theme](theming.md). There's a default theme that is used if nothing else was specified.
+
+String Templates are text files that include placeholders where property values are to be inserted during generation
+
+## Properties  
 
 Here is a list of supported properties that can be used in the string template files:
 
@@ -24,7 +29,7 @@ Here is a list of supported properties that can be used in the string template f
 - `$page.navigation$` : gives the links of all pages in the project (except the main page).
 - `$page.subheaders$` : determines if the current page contains subheaders or not, which concretely means that it contains multiple sections depending on the `toc-.
 - `$page.toc$` : in relation with `$page.subheaders$`, displays the list of all sections on the page as anchor links.
-- `$page.source_url$` : contains the plain text of the github source url of the current page. Works only if the associated `github.base_url` is defined (see @ref[github directive](linking.md#github-directive) for additional information). If this property is not defined, this field returns a null value; then a condition testing like `$if(page.source_url)$` would be necessary in this case.
+- `$page.source_url$` : contains the plain text of the github source url of the current page. Works only if the associated `github.base_url` is defined (see @ref[github directive](../directives/linking.md#github-directive) for additional information). If this property is not defined, this field returns a null value; then a condition testing like `$if(page.source_url)$` would be necessary in this case.
 - `$page.properties$`: displays purely the list of the properties for the current page, which contains the actual properties of the page and the global ones shared to all pages. See next sections to figure out how to deal with properties.
 
 ### Custom properties
@@ -40,7 +45,7 @@ The special `$` character can always be escaped with a back slash, i.e. `\$`.
 To add properties to your pages, there exists two ways for doing this:
 
 - To add properties to the entire document, common to all pages, you can add them in your build: `paradoxProperties += ("foo" -> "bar")`
-- To add propreties at page level, use Properties front matter (next section)
+- To add properties at page level, use Properties front matter (next section)
 
 ### Properties front matter
 

docs/src/main/paradox/features/theming.md → docs/src/main/paradox/customization/theming.md

@@ -1,5 +1,4 @@
-Theming
--------
+# Theming
 
 A theme is a collection of templates and other resources like css and image files that can be distributed as a web jar. Using this mechanism, multiple Paradox sites can have consistent look and feel. By default, a simple predefined theme in paradox is used and looks like [this](https://github.com/lightbend/paradox/tree/master/themes/generic/src/main/assets).
 

docs/src/main/paradox/features/css-friendliness.md → docs/src/main/paradox/directives/css-friendliness.md

@@ -8,8 +8,7 @@ difficult and brittle.
 Paradox comes with a "wrapping directive" which addresses this problem by allowing you to introduce additional
 `div` elements, with custom `id` or `class` attributes, at arbitrary points in the document structure.
 
-
-### @@@ div
+### @@@div
 
 Wrapping content with `@@@ div`, e.g. like this:
 

docs/src/main/paradox/directives/directives-alphabetically.md

@@ -0,0 +1,16 @@
+# Alphabetical List of Directives
+
+ * @ref[`@@dependencies`](dependencies.md)
+ * @ref[`@@@div`](css-friendliness.md#div)
+ * @ref[`@extref`](linking.md#extref-directive)
+ * @ref[`@github`](linking.md#github-directive)
+ * @ref[`@@@index`](organizing-pages.md#index-container)
+ * @ref[`@javadoc`](linking.md#javadoc)
+ * @ref[`@@@note`](callouts.md#note-callout)
+ * @ref[`@ref`](linking.md#ref-link)
+ * @ref[`@scaladoc`](linking.md#scaladoc)
+ * @ref[`@@snip`](snippets.md)
+ * @ref[`@@toc`](organizing-pages.md#toc-block)
+ * @ref[`@var`](vars.md#var)
+ * @ref[`@vars`](vars.md#vars)
+ * @ref[`@@@warning`](callouts.md#warning-callout)

docs/src/main/paradox/directives/index.md

@@ -0,0 +1,19 @@
+# Directives
+
+Directives are Paradox' extension points for providing customized behavior over Markdown. Directive can be recognized by the `@` sign
+which signifies a directive usage. Depending on the scope of the directive you will use a different kind of syntax. Use `@` (for inline),
+`@@` (leaf block), `@@@`(container block), `@@@@` or more for nested container blocks.
+
+@@toc
+
+@@@ index
+
+ * [Index and Table Of Contents Directives](organizing-pages.md)
+ * [Linking Directives](linking.md)
+ * [Snippet Directives](snippets.md)
+ * [Callout Directives](callouts.md)
+ * [Variable Substitution Directives](vars.md)
+ * [CSS Friendliness Directives](css-friendliness.md)
+ * [Directive List](directives-alphabetically.md)
+
+@@@

docs/src/main/paradox/features/organizing-pages.md → docs/src/main/paradox/directives/organizing-pages.md

@@ -1,8 +1,10 @@
-Organizing pages
-----------------
+# Organizing pages
 
 The first header in a markdown page will become the title of this page, even if it's a smaller header than the others.
 
+You can organize the page tree by including an `@@@ index` container inside of a page to declare which pages are child
+pages of this page.
+
 ### @@@index container
 
 `@@@index` is used to list child pages or sections from a page.
@@ -32,7 +34,7 @@ Inside `setup/index.md` can list its own child pages as follows:
 
 Paradox will walk through these indices and create a hierarchical navigation sidebar:
 
-![index](../img/index.png)
+![index](img/index.png)
 
 Similar to `@ref`, the source document on Github will link correctly the other sources.
 
@@ -49,4 +51,4 @@ The `@@toc` block is used to include a table of content with arbitrary depth.
 
 This will render the page names (first header), and the second headers.
 
-![toc](../img/toc.png)
+![toc](img/toc.png)

docs/src/main/paradox/features/snippet-inclusion.md → docs/src/main/paradox/directives/snippets.md

@@ -6,7 +6,7 @@ Snippet inclusion
 The `@@snip` block is used to include code snippets from another file.
 
 ```markdown
-@@snip [Hello.scala](../../scala/Hello.scala) { #hello_example }
+@@snip [Hello.scala](/docs/src/main/scala/Hello.scala) { #hello_example }
 ```
 
 Inside of `Hello.scala` mark the desired section you want to extract using the `#hello_example` label as follows:
@@ -22,33 +22,33 @@ object Hello extends App {
 This lets us compile and test the source before including it in the documentation.
 The snippet is rendered with code formatting like this:
 
-@@snip [Hello.scala](../../scala/Hello.scala) { #hello_example }
+@@snip [Hello.scala](/docs/src/main/scala/Hello.scala) { #hello_example }
 
 To display multiple snippets in a tabbed view, use definition list syntax as follows:
 
 @@@vars
 ```markdown
 sbt
-:   @@snip [build.sbt](../../resources/build.sbt) { #setup_example }
+:   @@snip [build.sbt](/docs/src/main/resources/build.sbt) { #setup_example }
 $empty$
 Maven
-:   @@snip [pom.xml](../../resources/pom.xml) { #setup_example }
+:   @@snip [pom.xml](/docs/src/main/resources/pom.xml) { #setup_example }
 $empty$
 Gradle
-:   @@snip [build.gradle](../../resources/build.gradle) { #setup_example }
+:   @@snip [build.gradle](/docs/src/main/resources/build.gradle) { #setup_example }
 ```
 @@@
 
 This will be rendered like this:
 
 sbt
-:   @@snip [build.sbt](../../resources/build.sbt) { #setup_example }
+:   @@snip [build.sbt](/docs/src/main/resources/build.sbt) { #setup_example }
 
 Maven
-:   @@snip [pom.xml](../../resources/pom.xml) { #setup_example }
+:   @@snip [pom.xml](/docs/src/main/resources/pom.xml) { #setup_example }
 
 Gradle
-:   @@snip [build.gradle](../../resources/build.gradle) { #setup_example }
+:   @@snip [build.gradle](/docs/src/main/resources/build.gradle) { #setup_example }
 
 By default, Paradox uses Prettify to highlight code and will try to detect the
 language of the snippet using the file extension. In cases where a snippet
@@ -58,48 +58,48 @@ should not be highlighted set `type=text` in the directive's attribute section:
 @@snip [example.log](example.log) { #example-log type=text }
 ```
 
-#### tab switching
+#### Tab Switching
 
 It is possible to associate multiple snippets under the same "tag". If some tab of a snippet is switched by the user, all tabs associated with the selected one will be switched as well.
 
 @@@vars
 ```markdown
 First-java
-:   @@snip [example-first.java](../../resources/tab-switching/examples.java) { #java_first }
+:   @@snip [example-first.java](/docs/src/main/resources/tab-switching/examples.java) { #java_first }
 $empty$
 First-scala
-:   @@snip [example-first.scala](../../resources/tab-switching/examples.scala) { #scala_first }
+:   @@snip [example-first.scala](/docs/src/main/resources/tab-switching/examples.scala) { #scala_first }
 $empty$
 Some separator.
 $empty$
 Java
-:   @@snip [example-second.java](../../resources/tab-switching/examples.java)
+:   @@snip [example-second.java](/docs/src/main/resources/tab-switching/examples.java)
 $empty$
 Scala
-:   @@snip [example-second.scala](../../resources/tab-switching/examples.scala)
+:   @@snip [example-second.scala](/docs/src/main/resources/tab-switching/examples.scala)
 ```
 @@@
 
 The result will be rendered like this (try to switch tabs):
 
 First-java
-:   @@snip [example-first.java](../../resources/tab-switching/examples.java) { #java_first group=java }
+:   @@snip [example-first.java](/docs/src/main/resources/tab-switching/examples.java) { #java_first group=java }
 
 First-scala
-:   @@snip [example-first.scala](../../resources/tab-switching/examples.scala) { #scala_first group=scala }
+:   @@snip [example-first.scala](/docs/src/main/resources/tab-switching/examples.scala) { #scala_first group=scala }
 
 Some separator.
 
 Java
-:   @@snip [example-second.java](../../resources/tab-switching/examples.java)
+:   @@snip [example-second.java](/docs/src/main/resources/tab-switching/examples.java)
 
 Scala
-:   @@snip [example-second.scala](../../resources/tab-switching/examples.scala)
+:   @@snip [example-second.scala](/docs/src/main/resources/tab-switching/examples.scala)
 
 This is also synced if some tabs have no snippet:
 
 Java
-:   @@snip [example-second.java](../../resources/tab-switching/examples.java)
+:   @@snip [example-second.java](/docs/src/main/resources/tab-switching/examples.java)
 
 Scala
 :   More inline tabbing
@@ -111,7 +111,7 @@ either in the page's front matter or globally like this (for example):
 
 ```sbt
 paradoxProperties in Compile ++= Map(
-  "snip.foo.base_dir" -> "../../../some/dir",
+  "snip.foo.base_dir" -> "/docs/src/main/../some/dir",
   "snip.test.base_dir" -> s"${(sourceDirectory in Test).value}/scala/org/example",
   "snip.project.base_dir" -> (baseDirectory in ThisBuild).value.getAbsolutePath
 )