-
Notifications
You must be signed in to change notification settings - Fork 46
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
sbt plugin & preview server: allow to add custom renderers #588
Conversation
Thanks for the ping on this, hoping to test it out this week :) |
@valencik did you have any chance yet to have a look? The current status for 1.1 is that all planned PRs are open now, so it's now simply a matter of merging and cutting a release, which I'd love to do at some point in the coming 2 weeks. Bugs can be fixed in a 1.1 patch if needed, so as long as you think the new API is sufficient we can merge this. |
Hey @jenshalm, funny, I have an in progress review I started earlier this morning :) I was going to test this by publishing locally, and then adding basically the snippet you've shown in the description to a project's build.sbt. Presumably that would work, and then someone could in theory use our custom Additionally, I'm curious how this might simplify the protosearch-sbt plugin itself. Should I be able to use |
Yes, I generally wonder whether you publishing an sbt plugin will be necessary in the future. Because the UI bits can also be bundled up in the lib module (as a theme extension) and then users can install both, the index renderer and the search UI with the two corresponding sbt settings. Preparing everything within the lib module would also mean users can as easily use it with other build tools like Mill. I can do the search UI bundling in a PR in protosearch if you want, it's quite straightforward. |
Oh my goodness, that would be ⭐ amazing 🌟
Yeah perhaps protosearch could just publish a laika lib module, and then sbt-typelevel could do the plugin setup. |
Yes, that sounds like the simplest approach. sbt-tl depending on protosearch would probably be fine as both projects are in 0.x range. |
Converted back to draft. It turns out that not only the sbt plugin itself needs to move from hardcoding EPUB and PDF output to having flexible renderer configuration, the preview server (which is not part of the plugin project) needs to make the same move. This requires further changes to this PR:
|
@valencik this is back on track now, the preview server has been taught about custom binary renderers. This time I tested it myself with the protosearch integration and it's working when applied to the Laika manual (in both, If you want to save some time and test with a verified scenario first, here are the steps I took:
Changes to the First, I amended the open PR by copying the js generation in the build over to the Then I added a custom builder for creating the config for the renderer. I did this because I realized that most of the properties are not actually user-configurable. The user cannot choose the file path as the UI would stop working when things are not in the expected place. So I added a custom builder like this (which is used in one of the steps above): object IndexRendererConfig {
def apply(includeInSite: Boolean): BinaryRendererConfig = {
BinaryRendererConfig(
alias = "index",
format = IndexFormat,
artifact = Artifact(
basePath = Root / "search" / "searchIndex",
suffix = "idx"
),
includeInSite = includeInSite,
supportsSeparations = false
)
}
} I did not add this to the PR since it's somewhat unrelated to the theme bundling, but I'd recommend you add this to the Using protosearch with the Laika sbt plugin is now down to 2 single-line statements which imho makes your sbt plugin redundant. |
This is excellent! I think that's going to make testing out search so much easier! Just to double check,
I don't see a line 231 in either this branch or latest main That |
Oops, sorry, I had the |
I've run through the above test you detailed (thank you!) and everything worked swell. A tiny note, in case it's interesting, I did have to run docs/mdoc before docs/laikaSite as I was getting the following error:
Would you be willing to release a milestone once this PR lands? |
Co-authored-by: Andrew Valencik <valencik@users.noreply.github.com>
Co-authored-by: Andrew Valencik <valencik@users.noreply.github.com>
Ah, yes, sorry, I forgot, this is expected when you don't use
Everything merged to main should trigger a snapshot release. Sorry, I somehow managed to edit your comment instead of quote-replying, but I reverted everything back. |
@valencik snapshot is available here now: |
Introduces a new
laikaRenderers
setting for Laika's sbt plugin that allows to configure additional renderers. Previously, using your own or 3rd party renderers that don't come out of the box with Laika was trivial for API users, but very cumbersome for plugin users. This PR creates ease-of-use parity between these two user groups.There are no new scripted tests as Laika's built-in renderers now use the new setting themselves, so it is implicitly tested by the existing suite.
An example for adding the search index generator from protosearch which was the initial trigger for introducing this new mechanic:
With the configuration above, the search index can be generated by calling
laikaGenerate index
(or together with other formats in one transformation - e.g.laikaGenerate html index
).When the
includeInSite
property is true, the index will also be generated when callinglaikaSite
. This is ideally a decision left for the end user, which is what I indicated withsomeCustomSetting.value
above.@valencik / @samspills / @armanbilge: Since you are probably the first developers using this, it would be great if one of you could do a quick review for this. There is no urgency, this can be parked while I work on other little additions for 1.1.
The advantages of using it instead of your existing approach would be: