Add a logo to the navigation bar of the HTML rendered book

[Chocorean]

Supersedes #1584, fixes #877

I added the option to add an image as logo to the navigation bar by adding a configuration parameter to the book table of the book.toml. This resolves #877

I also thought about adding the option of a project logo to the bottom of the navigation sidebar, but wanted to wait for feedback to this first edit before adding more code.

---

I have not addressed the comments (I have just rebased the original commits on top of main and fixed the failing tests, preserving the original author's contribution):

• logo = "static/logo.png"

An SVG would be prefered; maybe mdbook-html/front-end/images/favicon.svg could be a good candidate

• // TODO: add a test logo

Also there is no test at all at the moment.

• Please sort the property names below.

Done during rebase

• Please add an alt attribute for e.g., accessibility. Although its content could be generated, because of language differences and because of the principle of least surprise, I propose to add a config field containing the alt title.

This has not been addressed further ; a simple default value could be alt="{{ book_title }}"

[GuillaumeGomez]

So it's still waiting for you to fix the review comments, right?

[Chocorean]

Yes, although it does not look great right now, I will try to add it the the scrollbox of the sidebar

Any suggestion regarding position/size? maybe ~30/40% of the sidebar width, centered?
I took inspiration from rustdoc

And I will add some tests

[Chocorean]

I think I am good feature-wise, I'll write some tests next. I am not familiar with goml at all, but I will try to take care of that soon

[Chocorean]

So if I understand correctly, goml is used here to simulate user input? In that case I assume I should only need to write tests under tests/testsuite, am I correct?

[GuillaumeGomez]

It's used for GUI tests more globally. It allows you to query HTML states. It's easier to read than comparing plain HTML.

[Chocorean]

@GuillaumeGomez I believe it is ready for review

Another thing that I am not sure about is, if the logo does not exist, the book will still build without a warning

[GuillaumeGomez]

If it's a local file, we should definitely fail the build.

[Chocorean]

@GuillaumeGomez I have addressed your comments, and added a check command to the Config struct, which will crash the process if the logo file does not exist.

check is called after the config is loaded and updated by the envvars

[GuillaumeGomez]

One question I just stumbled upon: is the logo image copied to the generated book? Because if not, it should (and it should be tested of course :3).

[shenef]

How does this currently handle wide images? Could it function as a banner above the book title?

[GuillaumeGomez]

Oh that's actually a good point: how do we handle images too big?

[Chocorean]

How does this currently handle wide images? Could it function as a banner above the book title?

Currently logo width is set at a fixed 20%, and the title's max width to 70%, wrapping if too long ; check above to see what it looks like

Could be an option, let me know what you think!

One question I just stumbled upon: is the logo image copied to the generated book? Because if not, it should (and it should be tested of course :3).

Nice catch, I am adding it to the static files

[GuillaumeGomez]

Image not visible. Please add a test with a very large image too (doesn't need to be a big image, just one with like 1px of width/height and like 1000px of height/width).

[Chocorean]

I have added tests for very large/tall images:

Right now, logo's max-height is set at 8rem and its width at 20% of the toc width. Title width is set at 70%, and vertically centered on the logo

One question I just stumbled upon: is the logo image copied to the generated book? Because if not, it should (and it should be tested of course :3).

However I think I lost my way here. If the logo lives in src/, it will be copied with the rest, so I guess there was no need to add the logo to the static files. I spent quite some time trying to understand how to make it work because the resource helper is not available when the toc's template gets processed...
Anyway, I guess I'm going to drop my implementation and let the logo live as is.

[GuillaumeGomez]

However I think I lost my way here. If the logo lives in src/, it will be copied with the rest, so I guess there was no need to add the logo to the static files. I spent quite some time trying to understand how to make it work because the resource helper is not available when the toc's template gets processed...
Anyway, I guess I'm going to drop my implementation and let the logo live as is.

And what happens if the logo doesn't live in the src folder?

[Chocorean]

Right now, just like regular pictures, if it lives outside of src, then it won't be copied to the output directory, which kind of makes sense to me - my way to go is to make projects "self-contained", without links to the outside

However if you prefer to force copy it, I have a implementation ready for review leveraging StaticFiles. It leads to duplicated logos when it is existing under src/

And if this is overkill, maybe we can just copy it to the root of the book with a name unlikely to make a collision, such as mdbook_logo.

[GuillaumeGomez]

Huuuuum... Can we error instead if the picture is not part of the src folder?

[Chocorean]

@rustbot ready

Full recap:

• add an optional logo key in the book's config. it is a path relative to <book_root>/<book_config.src>/
  if found, the logo is added at the top of the toc, and the book title next to the logo. the logo takes 20% of the sidebar width, and title gets 70%. logo max height is 8rem.
• adds a config.check() after the config is loaded and envvars are injected
  this allows to check valid config values that could fail, such as incorrect paths. it is the case for logo
• update existing examples
• update guide: add logo, and documentation
• add rust tests and gui tests

and I think that is pretty much it!