diff --git a/docs/src/01-about-laika/01-features.md b/docs/src/01-about-laika/01-features.md index 0aaa1a8de..386f2f3a4 100644 --- a/docs/src/01-about-laika/01-features.md +++ b/docs/src/01-about-laika/01-features.md @@ -29,7 +29,7 @@ Laika can be used as: * A library on the JVM with Scala 3, 2.13 or 2.12. -* A library in Scala.js 1.5+ applications with all its features except File/Stream IO, EPUB and PDF output +* A library in Scala.js 1.13+ applications with all its features except File/Stream IO, EPUB and PDF output For getting started see the documentation of the [sbt Plugin] or [Library API]. diff --git a/docs/src/03-preparing-content/03-theme-settings.md b/docs/src/03-preparing-content/03-theme-settings.md index ff520e231..041037ec8 100644 --- a/docs/src/03-preparing-content/03-theme-settings.md +++ b/docs/src/03-preparing-content/03-theme-settings.md @@ -1071,7 +1071,7 @@ you can explicitly refer to it in the configuration header of the markup documen ```laika-html {% - helium.templates.head = ../my-custom-head.template.html + helium.site.templates.head = ../my-custom-head.template.html %} ``` @@ -1080,7 +1080,7 @@ but has to be somewhere within one of the specified input directories, as templates are parsed and cached upfront before getting applied to documents. All HTML templates must have a name with the pattern `.template.html`. -The configuration key to assign them to has the format `helium.templates.` +The configuration key to assign them to has the format `helium.site.templates.` where `` is again one of `head`, `topNav`, `mainNav`, `pageNav` or `footer`. Finally, like with all Laika configuration, you can also use different scopes than just the current document. diff --git a/docs/src/05-extending-laika/02-creating-themes.md b/docs/src/05-extending-laika/02-creating-themes.md index b5a8122ae..b5781ecb4 100644 --- a/docs/src/05-extending-laika/02-creating-themes.md +++ b/docs/src/05-extending-laika/02-creating-themes.md @@ -160,12 +160,15 @@ their inputs. @:callout(warning) While Laika offers the full API as for user inputs for maximum flexibility and consistency, -it is recommended to avoid any file system resources by using `addFile` or `addDirectory`. +it is recommended to avoid using `addFile` or `addDirectory` to add any file system resources. This might be acceptable for a library shared in-house where you can rely on a specific project setup, but for a public library it is most convenient for users when the theme is just an additional dependency and does not require any additional setup. +For this reason the best option is usually to either generate resource in memory and/or load them +as resources from the JAR, both of which is directly supported by the APIs. + @:@ @@ -422,9 +425,8 @@ As a minimum set of documentation it's recommended to include: but if you want to focus on fewer or different formats, let your users know. * Document the compatible Laika versions. - Laika is still in the 0.x version range, so some breaking changes are still expected before reaching the 1.0 milestone. - But the big rewrite phases are a thing of the past now, so you won't be exposed to massive disruptions. - A 1.0 version is expected at some point after the 0.19 release. + It will most likely be compatible with all 1.x versions, but there may be exceptions when you build on a feature + introduced in a minor 1.x release. * Document your theme configuration API. diff --git a/docs/src/05-extending-laika/06-adding-syntax-highlighters.md b/docs/src/05-extending-laika/06-adding-syntax-highlighters.md index afffc589e..130708126 100644 --- a/docs/src/05-extending-laika/06-adding-syntax-highlighters.md +++ b/docs/src/05-extending-laika/06-adding-syntax-highlighters.md @@ -86,8 +86,8 @@ def spanParsers: Seq[CodeSpanParser] when syntax like fenced code blocks are used. Concretely this means that if you specify `python` and `py` as the names for example, - the implementation will be used for any fenced code block that starts with either - ```` ```py ```` or ```` ```python ````. + the implementation will be used for any fenced code block that starts with + either ```` ```py ```` or ```` ```python ````. It's not tied to Markdown syntax though. reStructuredText has its own way of specifying a code block with language identifier, @@ -180,7 +180,7 @@ val spanParsers: Seq[CodeSpanParser] = Seq( Here we are defining two types of number literals: hexadecimal and decimal integers. -In both cases we allow the use of underscores as separators (e.g. `1,000,000`). +In both cases we allow the use of underscores as separators (e.g. `1_000_000`). We also define which kinds of type indicators we allow as a suffix and again use existing parsers for widely used syntax (`NumericSuffix.long` parses `L` or `l` for example). diff --git a/docs/src/07-reference/07-migration-guide.md b/docs/src/07-reference/07-migration-guide.md index adcbdef5c..4e971943b 100644 --- a/docs/src/07-reference/07-migration-guide.md +++ b/docs/src/07-reference/07-migration-guide.md @@ -25,12 +25,16 @@ Changed Behaviour for Including CSS/JS This is a breaking change the compiler does not help with detecting. If you previously had custom CSS or JavaScript files auto-linked to your pages, you need to adjust your configuration (see the PR for more details). -The old default of using a global search path for automatically linking all CSS and JS files from the input sources is no longer active. Users need to explicitly configure at least one search path (via .site.internalCSS or .site.internalJS) for a resource scan to happen. +The old default of using a global search path for automatically linking all CSS and JS files from the input sources is no longer active. Users need to explicitly configure at least one search path (via `.site.internalCSS` or `.site.internalJS`) for a resource scan to happen. The old behaviour was often unexpected (and users had to search for ways to disable it) and also came with the risk of overlapping search paths where a theme or extension adds their own resources. The new API allows more control in general (e.g. setting a condition per document for whether resources are linked or not). See the [corresponding PR](https://github.com/typelevel/Laika/pull/511) for additional details. +When not using the Helium theme, users are required to include their own custom template anyway, +so the simplest option to migrate might be to just hard-code all file inclusions in the `` section +of the template or, if more flexibility is required, use some of the templating features described in [Creating Templates]. + Breaking API Changes -------------------- diff --git a/project/ManualSettings.scala b/project/ManualSettings.scala index 05df554f9..84dab7809 100644 --- a/project/ManualSettings.scala +++ b/project/ManualSettings.scala @@ -80,10 +80,10 @@ object ManualSettings { val logo = images / "site" / "laika-dog-big@1.5x.png" val favicon = images / "site" / "laika-favicon.png" val siteBaseURL = "https://typelevel.org/Laika/" - val apiURL = "https://javadoc.io/doc/org.typelevel/laika-docs_2.12/latest/" - val srcURL = "https://github.com/typelevel/Laika" - val docsSrcURL = s"$srcURL/tree/main/docs/src" - val chatURL = "https://discord.gg/XF3CXcMzqD" + val apiURL = "https://javadoc.io/doc/org.typelevel/laika-docs_2.12/latest/laika/index.html" + val srcURL = "https://github.com/typelevel/Laika" + val docsSrcURL = s"$srcURL/tree/main/docs/src" + val chatURL = "https://discord.gg/XF3CXcMzqD" } private object text {