Skip to content

Releases: lightbend/paradox

0.2.10

08 May 22:05
Compare
Choose a tag to compare

v0.2.9...v0.2.10

Fixes and enhancements

0.2.9

10 Feb 12:16
33ea652
Compare
Choose a tag to compare

Fixes and enhancements

  • Adds support for multiple ivy configurations and doc overlays. #54/#83 by @gsechaud
  • Add support for multiple snippet base directories via configurable placeholders. #60 by @sirthias
  • Deprecate @var[foo] directive in favor of $foo$. #85 by @sirthias

0.2.8

09 Jan 18:08
abc0a5a
Compare
Choose a tag to compare

Fixes and enhancements

Source origin url on GitHub

$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. If it doesn't, this field returns a null value; then a condition testing like $if(page.source_url)$ would be necessary in this case.
Provide a new template "source.st" available in the generic theme which allows to display a simple plain text with the link associated to the current file.

0.2.7

25 Nov 12:17
v0.2.7
0c82288
Compare
Choose a tag to compare

Fixes and enhancements

  • Support referenced source definitions. #59 by @sirthias
  • Add @javadoc parameterized link directive. #52 by @jonas
  • Provide ability to disable prettify code highlighting. #64 by @jonas
  • Consistently render content inside block directives. #51 by @jonas

Referenced source definitions

One core markdown feature is support for defining link targets in two
ways: either in parens directly following the link text or through a
reference key following the link text in brackets. The first way was always
supported and this addition allows the second way for Paradox's various
link directives, such as @ref, @extref and @scaladoc.

Before continuing please read @ref:[the best practices][best-practices] for
using actors as well as the @scaladoc:[Actor API docs][Actor].

  [Actor]: akka.actor.Actor
  [best-practices]: actor-systems.md#actor-best-practices

Disabling code highlighting

In certain cases, fenced code blocks were eagerly highlighted even when a
specific language was specified. This behaviour can be disabled by explicitly
specifying text as the language type. For example:

```text
Content which should not be highlighted.
```

@@snip [example.log](example.log) { #example-log type=text }

0.2.6

28 Oct 02:52
v0.2.6
Compare
Choose a tag to compare

Fixes and enhancements

0.2.5

24 Oct 18:04
v0.2.5
Compare
Choose a tag to compare

Fixes and enhacements

  • Fixes css/js theme generation. #30 by @gsechaud
  • Fixes ref bug with anchor. #34 by @gsechaud
  • snippet.base_dir. See below.
  • image.base_url. See below.

snippet.base_dir

In order to specify your snippet source paths off a certain base directory
you can define a snippet.base_dir property either in the page's front matter
or globally like this (for example):

paradoxProperties in Compile ++= Map(
  "snippet.base_dir" -> s"${(sourceDirectory in Test).value}/scala/org/example"
)

You can then refer to this snippet base directory by starting a snippet path with .../, e.g.

@@snip [Hello.scala](.../Hello.scala) { #hello_example }

image.base_url

When placing images via the standard markdown image syntax you can refer
to a configured base URL by starting the image href with .../, e.g. like this:

![logo](.../logo.png)

The ... prefix refers to a defined a image.base_url property that is
specified either in the page's front matter or globally like this (for example):

paradoxProperties in Compile ++= Map("image.base_url" -> ".../assets/images")

If the image base URL itself starts with three dots (...) then these in turn
refer to the root URL of the site.

NOTE: As with the other "Parameterized Links" directives this feature will not
allow GitHub to preview the images correctly on the web interface.

#39 by @sirthias

v0.2.4

21 Oct 19:45
v0.2.4
Compare
Choose a tag to compare
0.2.4

0.2.3

21 Oct 19:45
v0.2.3
Compare
Choose a tag to compare

Fixes and enhacements

  • Adds per-page properties front matter.
  • Adds parameterized links.
  • Disables pegdown HARDWRAPS option by default to ignore newlines. #32 by @jrudolph

Properties front matter

Paradox 0.2.3 adds properties front matter:

---
out : index.html
---

The out property allows to rename the target name of the current file.
And the layout allows to specify the layout we want to be used for the
particular page.

#28 by @gsechaud

Parameterized links

Parameterized link directives help to manage links that references external documentation,
such as API documentation or source code. The directives are configured via base URLs defined in paradoxProperties:

paradoxProperties in Compile ++= Map(
  "github.base_url" -> "https://github.com/lightbend/paradox/tree/${version.value}",
  "scaladoc.akka.base_url" -> s"http://doc.akka.io/api/${Dependencies.akkaVersion}",
  "extref.rfc.base_url" -> "http://tools.ietf.org/html/rfc%s"
)

After which the directives can be used as follows:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
"OPTIONAL" in this document are to be interpreted as
described in @extref[RFC 2119](rfc:2119).

...

Use a @scaladoc[Future](scala.concurrent.Future) to avoid that long
running operations block the @scaladoc[Actor](akka.actor.Actor).

...

Issue @github[#1](#1) was fixed in commit @github[83986f9](83986f9).

@scaladoc directive

Use the @scaladoc directives to link to Scaladoc sites based on the package prefix.
Scaladoc URL mappings can be configured via the properties scaladoc.<package-prefix>.base_url
and the default scaladoc.base_url. The directive will match the link text with the longest
common package prefix and use the default base URL as a fall-back if nothing else matches.

@github directive

Use the @github directive to link to GitHub issues, commits and files.
It supports most of GitHub's autolinking syntax.

The github.base_url property must be configured to use shorthands such as #1.

@extref directive

Use the @extref directive to link to pages using custom URL templates.
URL templates can be configured via extref.<scheme>.base_url and the template may contain
one %s which is replaced with the scheme specific part of the link URL.

#27 by @jonas

0.2.2

21 Oct 19:44
v0.2.2
Compare
Choose a tag to compare

Fixes and enhacements

  • Aggregates from multiple snip labels. #22 by @jonas

0.2.1

06 Sep 19:27
v0.2.1
Compare
Choose a tag to compare

Fixes with compatibility implications

  • paradoxTheme now defaults to Some(builtinParadoxTheme("generic")). To opt out of a theme you must set None explicitly. #19 by @eed3si9n

Fixes and enhacements

Leady McBreadcrumbs

If a documentation site is contained within an enclosing website it's very pleasant if the breadcrumbs
allows one to navigate back up.

lazy val docs = (project infile(".")).
  enablePlugins(ParadoxPlugin)
  settings(
    name := "Breadcrumbs Test",
    paradoxLeadingBreadcrumbs := List("Alphabet" -> "https://abc.xyz/", "Google" -> "https://www.google.com")
  )

#9 by @dwijnand.

Scalafiddle integration

Adds a variation of @@snip feature that works with Scalafiddle:

@@fiddle [Example.scala](./Example.scala) { #fiddle_code extraParams=theme=light&layout=v75 cssStyle=width:100%; }

#16 by @andreaTP