Create mdbook-tera-backend renderer

[sakex]

Here is the prototype, it does almost everything we want already, I just need to port the actual LanguagePicker

You can see that the code to create a custom component is pretty straightforward (see the test component in src/custom_components/test_component.rs).

You can check the test in src/custom_component_renderer/book_directory_renderer.rs to see how it all works.

Fixes #70.

[mgeisler]

Hey @sakex, thanks for putting this up! I think my only major concern is how people (myself included! 🙂) will create and modify the custom components?

I had hoped they would be defined in the theme, just like I see Tera allows you to create new macros in a template file.

I feel this is crucial since I need a way of looking at the output when modify the templates. So I need to be able to run mdbool serve and see the output right away.

[sakex]

A separate custom-made component is definitely doable.

It could look like

book.toml

[output.i18-helper.components]
MyCustomComponent = "path/to/comp.html"

comp.html

<div>
some stuff in there, maybe tera templates too
</div>

index.html
...
<MyCustomComponent />
...

[sakex]

Because in my test component, I'm generating the HTML using DOM manipulations with the scraper crate. But we don't have to do it that way, we can also do HTML::parse on a string and then inject the parsed node to the original tree.

[sakex]

For complex and common components, we will create them inside of the crate. Otherwise, users will be able to create their own. I'll add that feature in a further CL though, if that works for you.

LanguagePicker should definitely live here for instance. Also I'd really like to create an <ExercizeCodeBlock /> and a <WasmCodeBlock /> in the future. Because the components created here don't need to be used in the template, they can also be added to the markdown directly

[mgeisler]

A separate custom-made component is definitely doable.

It could look like

book.toml

[output.i18-helper.components]
MyCustomComponent = "path/to/comp.html"

comp.html

<div>
some stuff in there, maybe tera templates too
</div>

This is the main question: how do I create a component with custom logic? With loops, variables, if statements, etc? I have the impression that I need to write Rust code for that?

I liked using Tera much more: there we can keep our code to a minimum. I don't really like code: more code is normally more trouble 😄 Put differently, I don't want us to maintain a template system here. Pushing all logic to the template library should make our life easier.

It also makes things clearer for downstream users: just modify index.hbs to hook in the call that loads a macro from mdbook-i18n-helpers.html and then use those macros where you like. I think it would even be possible to let downstream users override parts of the macros using the inheritance system in Tera, but I'm not 100% sure.

[sakex]

Let's do it that way then, I think it will look pretty goodOn Sep 16, 2023 16:54, Martin Geisler ***@***.***> wrote: A separate custom-made component is definitely doable. It could look like book.toml [output.i18-helper.components] MyCustomComponent = "path/to/comp.html" comp.html <div> some stuff in there, maybe tera templates too </div> This is the main question: how do I create a component with custom logic? With loops, variables, if statements, etc? I have the impression that I need to write Rust code for that? I liked using Tera much more: there we can keep our code to a minimum. I don't really like code: more code is normally more trouble 😄 Put differently, I don't want us to maintain a template system here. Pushing all logic to the template library should make our life easier. It also makes things clearer for downstream users: just modify index.hbs to hook in the call that loads a macro from mdbook-i18n-helpers.html and then use those macros where you like. I think it would even be possible to let downstream users override parts of the macros using the inheritance system in Tera, but I'm not 100% sure. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[mgeisler]

Is get_context still there? I think it got removed and that this can be replaced with

Suggested change

	{% for identifier, language_name in get_context(key="output.i18n.languages")
	%}
	{% for identifier, language_name in get_context(key="ctx.config.output.i18n.languages") %}

I don't think you show the corresponding book.toml for this anywhere? This makes the example a bit complicated in my opinion.

[mgeisler]

We can fix this before/after merging this PR — we'll have time to go over the documentation before we release this on crates.io.

[mgeisler]

Hey @sakex, I think this has been cooking more than needed now!

Thank you for fixing many small thing. From my testing, I can see that this is a huge step forward! It allows us to solve some very long-standing and important problems in Comprehensive Rust (as shown in #35 (comment)).