This PR introduces new Helium configuration API for controlling the inclusion of script and CSS resources in the <head> section of HTML or EPUB output.
It further reduces the likeliness that custom templates need to be included for common tasks, as previously surfaced in discussion #497. It will also trivialise the implementation of the upcoming mermaid support (#331).
It adds the following new methods to the .site selector of the Helium API:
internalCSS
internalJS
externalCSS
externalJS
inlineCSS
inlineJS
It adds the same methods with the same signatures to the .epub selector except for the external... variants.
It also deprecates the following two methods on the .site and .epub selectors:
autoLinkCSS
autoLinkJS
This functionality was much more limited and also had defaults which were confusing for users (defaults are discussed further below). These method will be removed in version 1.0 like all other deprecated APIs.
Summary for the new functionality
(Code examples can be found in the new manual sections included in this PR)
internalCSS and internalJS
These are similar to the old deprecated methods in that they allow to define a local search path that will be scanned for CSS or JS files to be linked in the header. However, like most other new methods they receive two new parameters for setting attributes and/or conditions for inclusions as described below.
externalCSS and externalJS
Linking external resources previously required custom template, even though it is a fairly common task, e.g. for including render kits for math or diagrams for example. The methods take a string URL as well as the same attribute and condition parameters like the internal... variants.
inlineCSS and inlineJS
These methods allow the embedding of script and style directly in the head section.
Conditional Inclusions
All the listed methods support an optional filter parameter of type Document => Boolean that enables inspection of configuration and document AST before deciding on the inclusion of resources.
Tag Attributes
Most of the listed methods support and optional attributes parameter that allows to set some of the most common attributes for script or link elements (e.g. defer or async).
Changes in Default Behaviour
For backwards compatibility within the 0.19 series, the default behaviour remains exactly the same for existing applications unless any of the new methods is used in which case the global resource scanning will be disabled to avoid overlapping search paths.
In version 1.0 when the deprecated methods will be removed, no scanning will happen unless the user specifies at least one local search path.
This PR introduces new Helium configuration API for controlling the inclusion of script and CSS resources in the
<head>section of HTML or EPUB output.It further reduces the likeliness that custom templates need to be included for common tasks, as previously surfaced in discussion #497. It will also trivialise the implementation of the upcoming mermaid support (#331).
It adds the following new methods to the
.siteselector of the Helium API:internalCSSinternalJSexternalCSSexternalJSinlineCSSinlineJSIt adds the same methods with the same signatures to the
.epubselector except for theexternal...variants.It also deprecates the following two methods on the
.siteand.epubselectors:autoLinkCSSautoLinkJSThis functionality was much more limited and also had defaults which were confusing for users (defaults are discussed further below). These method will be removed in version 1.0 like all other deprecated APIs.
Summary for the new functionality
(Code examples can be found in the new manual sections included in this PR)
internalCSSandinternalJSThese are similar to the old deprecated methods in that they allow to define a local search path that will be scanned for CSS or JS files to be linked in the header. However, like most other new methods they receive two new parameters for setting attributes and/or conditions for inclusions as described below.
externalCSSandexternalJSLinking external resources previously required custom template, even though it is a fairly common task, e.g. for including render kits for math or diagrams for example. The methods take a string URL as well as the same attribute and condition parameters like the
internal...variants.inlineCSSandinlineJSThese methods allow the embedding of script and style directly in the head section.
Conditional Inclusions
All the listed methods support an optional filter parameter of type
Document => Booleanthat enables inspection of configuration and document AST before deciding on the inclusion of resources.Tag Attributes
Most of the listed methods support and optional
attributesparameter that allows to set some of the most common attributes forscriptorlinkelements (e.g.deferorasync).Changes in Default Behaviour
For backwards compatibility within the 0.19 series, the default behaviour remains exactly the same for existing applications unless any of the new methods is used in which case the global resource scanning will be disabled to avoid overlapping search paths.
In version 1.0 when the deprecated methods will be removed, no scanning will happen unless the user specifies at least one local search path.