diff --git a/core/src/main/java/org/pegdown/ParserWithDirectives.java b/core/src/main/java/org/pegdown/ParserWithDirectives.java index 31269a53..ffcf8a05 100644 --- a/core/src/main/java/org/pegdown/ParserWithDirectives.java +++ b/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)) ) ), 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 3a6bd6e7..bf298a23 100644 --- a/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala +++ b/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 = { diff --git a/docs/src/main/paradox/configuration.md b/docs/src/main/paradox/configuration.md new file mode 100644 index 00000000..40073c54 --- /dev/null +++ b/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/") +``` diff --git a/docs/src/main/paradox/customization/extensions.md b/docs/src/main/paradox/customization/extensions.md new file mode 100644 index 00000000..17099108 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/src/main/paradox/customization/index.md b/docs/src/main/paradox/customization/index.md new file mode 100644 index 00000000..93061243 --- /dev/null +++ b/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) +@@@ \ No newline at end of file diff --git a/docs/src/main/paradox/features/templating.md b/docs/src/main/paradox/customization/templating.md similarity index 82% rename from docs/src/main/paradox/features/templating.md rename to docs/src/main/paradox/customization/templating.md index b857988e..0357dbe5 100644 --- a/docs/src/main/paradox/features/templating.md +++ b/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 diff --git a/docs/src/main/paradox/features/theming.md b/docs/src/main/paradox/customization/theming.md similarity index 99% rename from docs/src/main/paradox/features/theming.md rename to docs/src/main/paradox/customization/theming.md index 661adabe..7584d055 100644 --- a/docs/src/main/paradox/features/theming.md +++ b/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). diff --git a/docs/src/main/paradox/features/callouts.md b/docs/src/main/paradox/directives/callouts.md similarity index 100% rename from docs/src/main/paradox/features/callouts.md rename to docs/src/main/paradox/directives/callouts.md diff --git a/docs/src/main/paradox/features/css-friendliness.md b/docs/src/main/paradox/directives/css-friendliness.md similarity index 98% rename from docs/src/main/paradox/features/css-friendliness.md rename to docs/src/main/paradox/directives/css-friendliness.md index dbb9f883..83ac3a54 100644 --- a/docs/src/main/paradox/features/css-friendliness.md +++ b/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: diff --git a/docs/src/main/paradox/features/dependencies.md b/docs/src/main/paradox/directives/dependencies.md similarity index 100% rename from docs/src/main/paradox/features/dependencies.md rename to docs/src/main/paradox/directives/dependencies.md diff --git a/docs/src/main/paradox/directives/directives-alphabetically.md b/docs/src/main/paradox/directives/directives-alphabetically.md new file mode 100644 index 00000000..e80d74e8 --- /dev/null +++ b/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) diff --git a/docs/src/main/paradox/directives/index.md b/docs/src/main/paradox/directives/index.md new file mode 100644 index 00000000..45468768 --- /dev/null +++ b/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) + +@@@ \ No newline at end of file diff --git a/docs/src/main/paradox/features/linking.md b/docs/src/main/paradox/directives/linking.md similarity index 100% rename from docs/src/main/paradox/features/linking.md rename to docs/src/main/paradox/directives/linking.md diff --git a/docs/src/main/paradox/features/organizing-pages.md b/docs/src/main/paradox/directives/organizing-pages.md similarity index 83% rename from docs/src/main/paradox/features/organizing-pages.md rename to docs/src/main/paradox/directives/organizing-pages.md index ba8729f2..76ccfb0a 100644 --- a/docs/src/main/paradox/features/organizing-pages.md +++ b/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) diff --git a/docs/src/main/paradox/features/snippet-inclusion.md b/docs/src/main/paradox/directives/snippets.md similarity index 64% rename from docs/src/main/paradox/features/snippet-inclusion.md rename to docs/src/main/paradox/directives/snippets.md index 0af4816f..2d21a7bf 100644 --- a/docs/src/main/paradox/features/snippet-inclusion.md +++ b/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 ) diff --git a/docs/src/main/paradox/directives/vars.md b/docs/src/main/paradox/directives/vars.md new file mode 100644 index 00000000..eb4bbc28 --- /dev/null +++ b/docs/src/main/paradox/directives/vars.md @@ -0,0 +1,67 @@ +# Variable Substitution Directives + +## @var + +Inserts the given variable into the text. + +Example: + +``` +The Scala Version is @var[scala.version]. +``` + +results in: + +The Scala Version is @var[scala.version]. + +## @@@vars + +Allows to insert property values in verbatim blocks. + +For example, + +``` + @@@vars + + ```scala + println("The project version is $version$") + ``` + + @@@ +``` + +(added extra indentation to be able to show the example) + +would render to: + +@@@vars + +```scala +println("The project version is $version$") +``` + +@@@ + +### Customize delimiters with @@@vars + +You can customize the delimiters if `$` already has a special meaning inside the verbatim block: + +``` + @@@vars { start-delimiter="*&*" stop-delimiter="&*&" } + + ```scala + println("The project version is *&*version&*&") + ``` + +@@@ +``` + +renders to: + +@@@vars { start-delimiter="*&*" stop-delimiter="&*&" } + +```scala +println("The project version is *&*version&*&") +``` + +@@@ \ No newline at end of file diff --git a/docs/src/main/paradox/features/markdown.md b/docs/src/main/paradox/features/markdown.md deleted file mode 100644 index f7744906..00000000 --- a/docs/src/main/paradox/features/markdown.md +++ /dev/null @@ -1,11 +0,0 @@ -Markdown flavour ----------------- - -Paradox source files are formatted in [Markdown syntax](https://daringfireball.net/projects/markdown/syntax), and by convention we prefer the [GitHub-flavored style](https://help.github.com/articles/basic-writing-and-formatting-syntax/). - -We currently use the [Pegdown](https://github.com/sirthias/pegdown#introduction) processor, though this may not [remain the case](https://github.com/lightbend/paradox/issues/81). - -Some aspects of our Markdown dialect worth noting are: - -* Bulleted lists must always be preceded by an empty line (otherwise they'll be considered to be a 'normal' part of the previous paragraph) -* For references within a paradox tree, we prefer `@ref:[Link Text](../other-file.md#some-anchor)` syntax over free-form `[Link Text](../other-file.html#some-anchor)`. This introduces opportunities for [validation](https://github.com/lightbend/paradox/issues/53) diff --git a/docs/src/main/paradox/features/multi-configuration.md b/docs/src/main/paradox/features/multi-configuration.md deleted file mode 100644 index 3fd9e75d..00000000 --- a/docs/src/main/paradox/features/multi-configuration.md +++ /dev/null @@ -1,21 +0,0 @@ -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". \ No newline at end of file diff --git a/docs/src/main/paradox/features/overlay.md b/docs/src/main/paradox/features/overlay.md deleted file mode 100644 index fc771923..00000000 --- a/docs/src/main/paradox/features/overlay.md +++ /dev/null @@ -1,23 +0,0 @@ -Documentation overlay ---------------------- - -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. \ No newline at end of file diff --git a/docs/src/main/paradox/features/version-warning.md b/docs/src/main/paradox/features/version-warning.md deleted file mode 100644 index 91931e47..00000000 --- a/docs/src/main/paradox/features/version-warning.md +++ /dev/null @@ -1,12 +0,0 @@ -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/") -``` diff --git a/docs/src/main/paradox/getting-started.md b/docs/src/main/paradox/getting-started.md new file mode 100644 index 00000000..51f471b5 --- /dev/null +++ b/docs/src/main/paradox/getting-started.md @@ -0,0 +1,50 @@ +# Getting Started + +This guide helps you to quickly setup an sbt project to use paradox and write your first documentation pages. + +### Setup + +Create `project/paradox.sbt`: + +@@@vars +```scala +addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "$version$") +``` +@@@ + +Inside `build.sbt`, add `ParadoxPlugin` to a subproject: + +```scala +lazy val root = (project in file(".")). + enablePlugins(ParadoxPlugin). + settings( + name := "Hello Project", + paradoxTheme := Some(builtinParadoxTheme("generic")) + ) +``` + +### Writing docmentation + +Create your first documentation page in `src/main/paradox/index.md` which is the entry page of your documentation site. + +``` +# My Documentation + +This is my first documentation page! +``` + + +### Generating documentation + +Call `paradox` in sbt which will generate the site in `target/paradox/site/main`. + +@@@note + +You may want to use `~ show paradox` in sbt, which shows the absolute path where Paradox generated your +documentation and which will automatically regenerate documentation when you change a documentation file. + +@@@ + +Open `target/paradox/site/main/index.html` and admire the results! + +![First Generated Docs Page](img/first-docs.png) \ No newline at end of file diff --git a/docs/src/main/paradox/features/groups.md b/docs/src/main/paradox/groups.md similarity index 66% rename from docs/src/main/paradox/features/groups.md rename to docs/src/main/paradox/groups.md index 23a66f0e..97aed17d 100644 --- a/docs/src/main/paradox/features/groups.md +++ b/docs/src/main/paradox/groups.md @@ -1,8 +1,7 @@ -Groups ------- +# Groups Paradox supports 'groups' which allow users to easily switch between different -'variations' of the documentation. +variants of the documentation. ## Configuration @@ -26,18 +25,18 @@ Groups are used for tabs, where the group is determined by the tab name: @@@vars ```markdown 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$ 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 } ``` @@@ 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 } 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 } or by the group parameter on the snippet: @@ -47,24 +46,24 @@ example-first.java : @@snip [example-first.java](../../resources/tab-switching/examples.java) { #java_first group=java } $empty$ example-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 } ``` @@@ example-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 } example-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 } But tabs not associated with groups are left alone: 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 : Non-snippet tab body @@ -79,12 +78,12 @@ switching inline text: Text describing the @java[Java variant]@scala[Scala variant containing ***markdown*** and @ref:[Linking](linking.md)]. ``` -Text describing the @java[Java variant]@scala[Scala variant containing ***markdown*** and @ref:[Linking](linking.md)]. +Text describing the @java[Java variant]@scala[Scala variant containing ***markdown*** and @ref:[Linking](directives/linking.md)]. ### Directives -You can also use groups with directives such as `@@@ div` [(link)](http://developer.lightbend.com/docs/paradox/latest/features/css-friendliness.html#div) -and `@@@ note` [(link)](http://developer.lightbend.com/docs/paradox/latest/features/css-friendliness.html#div) as follows: +You can also use groups with directives such as @ref[`@@@div`](directives/css-friendliness.md#div) +and @ref[`@@@note`](directives/callouts.md#note) as follows: ``` @@@ div { .group-scala } diff --git a/docs/src/main/paradox/img/akka-paradox-theme.png b/docs/src/main/paradox/img/akka-paradox-theme.png new file mode 100644 index 00000000..bd44dc34 Binary files /dev/null and b/docs/src/main/paradox/img/akka-paradox-theme.png differ diff --git a/docs/src/main/paradox/img/first-docs.png b/docs/src/main/paradox/img/first-docs.png new file mode 100644 index 00000000..05456b66 Binary files /dev/null and b/docs/src/main/paradox/img/first-docs.png differ diff --git a/docs/src/main/paradox/img/material-theme.png b/docs/src/main/paradox/img/material-theme.png new file mode 100644 index 00000000..e7a89107 Binary files /dev/null and b/docs/src/main/paradox/img/material-theme.png differ diff --git a/docs/src/main/paradox/index.md b/docs/src/main/paradox/index.md index 9a75c1b4..f8adc41e 100644 --- a/docs/src/main/paradox/index.md +++ b/docs/src/main/paradox/index.md @@ -1,73 +1,20 @@ -Paradox -======= +# Paradox Paradox is a Markdown documentation tool for software projects. -The GitHub repo is [lightbend/paradox][repo]. -**Paradox is NOT supported under the Lightbend subscription.** - -### Setup - -Find [the latest](https://github.com/lightbend/paradox/releases) version, and create `project/paradox.sbt`: - -@@@vars -```scala -addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "$version$") -``` -@@@ - -Inside `build.sbt`, add `ParadoxPlugin` to a subproject: - -```scala -lazy val root = (project in file(".")). - enablePlugins(ParadoxPlugin). - settings( - name := "Hello Project", - paradoxTheme := Some(builtinParadoxTheme("generic")) - ) -``` - -Then call `paradox` which will generate the site in `target/paradox/site/main`. - -Your markdown documentation will go inside `src/main/paradox/`. For example, you can start with `src/main/paradox/index.md`. +@@toc { depth=1 } -### Key features - -- Supports Multi-configuration. -- Supports @ref[GitHub flavored Markdown](features/markdown.md). -- Principled markdown extension using generic directives syntax. -- GitHub-friendly Markdown source (links work). -- Code snippet inclusion for compilable code examples. -- Templating and theming. -- Documentation overlay. - -### Generic directive - -Paradox extends Markdown in a principled manner called generic directives syntax, -which basically means that all of our extensions would start with `@` (for inline), `@@` (leaf block), or `@@@` (container block). - -### License and credits - -- Copyright 2015-2018 Lightbend, Inc. Paradox is provided under the Apache 2.0 license. -- The markdown engine is based on Mathias's [Pegdown][]. +**Paradox is NOT supported under the Lightbend subscription.** @@@ index -* [Multi Configuration](features/multi-configuration.md) -* [Markdown flavour](features/markdown.md) -* [Organizing pages](features/organizing-pages.md) -* [Linking](features/linking.md) -* [Groups](features/groups.md) -* [Snippet inclusion](features/snippet-inclusion.md) -* [Callouts](features/callouts.md) -* [Library dependencies](features/dependencies.md) -* [CSS Friendliness](features/css-friendliness.md) -* [Templating](features/templating.md) -* [Version warning](features/version-warning.md) -* [Theming](features/theming.md) -* [Documentation Overlay](features/overlay.md) - +* [Overview](overview.md) +* [Getting Started](getting-started.md) +* [Configuration](configuration.md) +* [Markdown](markdown.md) +* [Directives](directives/index.md) +* [Variable Substitution](variable-substitution.md) +* [Groups](groups.md) +* [Customization](customization/index.md) + @@@ - - [Pegdown]: https://github.com/sirthias/pegdown/ - [repo]: https://github.com/lightbend/paradox diff --git a/docs/src/main/paradox/markdown.md b/docs/src/main/paradox/markdown.md new file mode 100644 index 00000000..733a9816 --- /dev/null +++ b/docs/src/main/paradox/markdown.md @@ -0,0 +1,14 @@ +Markdown +-------- + +Paradox source files are written in [Markdown](https://daringfireball.net/projects/markdown/syntax), and by convention we prefer the [GitHub-flavored style](https://help.github.com/articles/basic-writing-and-formatting-syntax/). + +We currently use the [Pegdown](https://github.com/sirthias/pegdown#introduction) processor to parse Markdown, +though this may not [remain the case](https://github.com/lightbend/paradox/issues/81). + +Some aspects of our Markdown dialect worth noting are: + +* Bulleted lists must always be preceded by an empty line (otherwise they'll be considered to be a 'normal' part of the previous paragraph) +* For references within a paradox tree, we prefer to use the `@ref` directive over Markdown links which introduces opportunities for + [validation](https://github.com/lightbend/paradox/issues/53) (i.e. use `@ref:[Link Text](../other-file.md#some-anchor)` instead of + `[Link Text](../other-file.html#some-anchor)`). diff --git a/docs/src/main/paradox/overview.md b/docs/src/main/paradox/overview.md new file mode 100644 index 00000000..d1ff0a64 --- /dev/null +++ b/docs/src/main/paradox/overview.md @@ -0,0 +1,30 @@ +# Overview + +Paradox is a Markdown documentation tool for sbt projects. It takes a directory tree of markdown files and generates a +static documentation site. + +It has several features that help to structure and build documentation sites easily. + + * Supports @ref[GitHub flavored Markdown](markdown.md) + * Pages can be @ref[organized](directives/organizing-pages.md) structured hierarchically. A sidebar with an index or an in-page table of contents + can be generated. + * @ref[Directives](directives/index.md) provide additional features over Markdown and allow custom extensions in a principled way + * @ref[Variable substitution](variable-substitution.md) allows configuring values from your sbt project to be used in the documentation + * @ref[Groups](groups.md) allow to create variants of the documentation where parts of pages are only shown when a + group is selected e.g. for switching between Scala and Java versions of documentation, snippets, etc. + * Various @ref[customization](customization/index.md) options allow tailoring Paradox' output to your needs. For example, + @ref[Themes](customization/theming.md) allow customizing the appearance of Paradox-generated documentation. Custom + directives and themes can be packaged and published as separate sbt plugin @ref[extensions](customization/extensions.md). + +### Source Code + +The GitHub repository can be found at [lightbend/paradox][repo]. + +### License and credits + + - Copyright 2015-2018 Lightbend, Inc. Paradox is provided under the Apache 2.0 license. + - **Paradox is NOT supported under the Lightbend subscription.** + - The markdown engine is based on Mathias's [Pegdown][]. + + [Pegdown]: https://github.com/sirthias/pegdown/ + [repo]: https://github.com/lightbend/paradox \ No newline at end of file diff --git a/docs/src/main/paradox/variable-substitution.md b/docs/src/main/paradox/variable-substitution.md new file mode 100644 index 00000000..9b1bb800 --- /dev/null +++ b/docs/src/main/paradox/variable-substitution.md @@ -0,0 +1,68 @@ +--- +key: This is my key value +--- + +# Variable Substitution + +Often it is necessary to transport values from the build into the documentation, like the current version of the project. +This can be done with properties. Properties can be defined with sbt settings and can then be accessed in documentation +Markdown files. + +## Defining Properties + + +### With Sbt Settings + +To define properties add a key / value tuple to the `paradoxProperties` setting. For example, to make the Scala version +of the build available to the documentation you can use this (in fact, this property is already [predefined](#predefined-properties)): + +``` +paradoxProperties += ("scala.version" -> scalaVersion.value) +``` + +### With Front-Matter + +You can set or override property values with "front-matter" on pages. At the beginning of a Markdown file, add a block + +``` +--- +key: This is my key value +--- +``` + +to change a property value just for this page. + +## Referencing Properties From Markdown + +In Markdown you can either directly reference properties using dollar notation `$property$`. + +For example, this snippet: + +``` +The scala version is "$scala.version$". +``` + +renders as: + +The scala version is "$scala.version$". + +Alternatively, you can also use the @ref[`@var`](directives/vars.md#var) or [`@@@vars`](directives/vars.md#vars) +directives to insert property values depending on the context. + +## Predefined Properties + + - `project.name`: Name of the project + - `project.version`: Project version + - `project.version.short`: Project version with `-SNAPSHOT` replaced by `*` + - `project.description`: Project description + - `scala.version`: Project Scala Version + - `scala.binary.version`: Project Scala binary compatible version (e.g. "2.12") + - `date`: Generation date in the form `MMM DD, YYYY` + - `date.day`: Generation day of the month + - `date.month`: Generation month + - `date.year`: Generation year + +## Special Properties + +Some properties have special meaning for the generation engine. See the @ref[Templating](customization/templating.md#properties-front-matter) +section for more information. \ No newline at end of file diff --git a/project/plugins.sbt b/project/plugins.sbt index 2a9a7cea..b7139936 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -20,7 +20,7 @@ addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.0.0") addSbtPlugin("org.foundweekends" % "sbt-bintray" % "0.5.1") addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "2.0") addSbtPlugin("com.jsuereth" % "sbt-pgp" % "1.1.0") -addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.3.4") +addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.3.6") libraryDependencies += "org.scala-sbt" %% "scripted-plugin" % sbtVersion.value diff --git a/tests/src/test/scala/com/lightbend/paradox/markdown/VarDirectiveSpec.scala b/tests/src/test/scala/com/lightbend/paradox/markdown/VarDirectiveSpec.scala index 23966559..9d6dc9b4 100644 --- a/tests/src/test/scala/com/lightbend/paradox/markdown/VarDirectiveSpec.scala +++ b/tests/src/test/scala/com/lightbend/paradox/markdown/VarDirectiveSpec.scala @@ -20,7 +20,7 @@ import com.lightbend.paradox.tree.Tree.Location class VarDirectiveSpec extends MarkdownBaseSpec { - val testProperties = Map("version" -> "1.2.3") + val testProperties = Map("version" -> "1.2.3", "scala.version" -> "2.12.6") implicit val context: Location[Page] => Writer.Context = { loc => writerContext(loc).copy(properties = testProperties) @@ -28,26 +28,38 @@ class VarDirectiveSpec extends MarkdownBaseSpec { "Var substitution" should "insert property values" in { markdown("$version$") shouldEqual html("

1.2.3

") + // work for dotted vars as well + markdown("$scala.version$") shouldEqual html("

2.12.6

") } it should "work within markdown inlines" in { markdown("Version is *$version$*.") shouldEqual html("

Version is 1.2.3.

") + // work for dotted vars as well + markdown("Version is *$scala.version$*.") shouldEqual html("

Version is 2.12.6.

") } it should "work within markdown blocks" in { markdown("- $version$") shouldEqual html("") + // work for dotted vars as well + markdown("- $scala.version$") shouldEqual html("") } it should "work within link labels" in { markdown("[Version $version$](version.html)") shouldEqual html("""

Version 1.2.3

""") + // work for dotted vars as well + markdown("[Version $scala.version$](version.html)") shouldEqual html("""

Version 2.12.6

""") } it should "work within other inline directives" in { markdown("@ref:[Version $version$](test.md)") shouldEqual html("""

Version 1.2.3

""") + // work for dotted vars as well + markdown("@ref:[Version $scala.version$](test.md)") shouldEqual html("""

Version 2.12.6

""") } it should "retain whitespace before and after" in { markdown("The $version$ version.") shouldEqual html("

The 1.2.3 version.

") + // work for dotted vars as well + markdown("The $scala.version$ version.") shouldEqual html("

The 2.12.6 version.

") } it should "support escaping the $ delimiter" in { diff --git a/version.sbt b/version.sbt index acfbdb67..edb9965e 100644 --- a/version.sbt +++ b/version.sbt @@ -1 +1 @@ -version in ThisBuild := "0.4.0-SNAPSHOT" +version in ThisBuild := "0.4.0-SNAPSHOT" \ No newline at end of file