Helium: new configuration options for including script or style resources. #511
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.