Skip to content
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.

Sign up for GitHub

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

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

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a5ec0da
Add a config variable for a logo path
scattenlaeufer Jun 22, 2021
b391d93
Add a logo to the HTML template
scattenlaeufer Jun 24, 2021
bf5b900
Add informations about the logo to the guide
scattenlaeufer Jun 24, 2021
7a6f7c3
Fix a typo
scattenlaeufer Oct 24, 2021
ff42463
Add a SVG logo to the example configuration
scattenlaeufer Oct 24, 2021
db0499d
Fix the link to the logo so it worked on every page
scattenlaeufer Oct 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions guide/src/format/configuration/general.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,15 +46,19 @@ This is general information about your book.
`src` directly under the root folder. But this is configurable with the `src`
key in the configuration file.
- **language:** The main language of the book, which is used as a language attribute `<html lang="en">` for example.
- **logo:** Path to a logo to shown at the top of the navigation bar. If this
is given as a relative path, it's base directory is the source directory.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
is given as a relative path, it's base directory is the source directory.
is given as a relative path, its base directory is the source directory.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which content types do we support for the logo?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd have to further look into that, but it seems like pixel as well as vector graphics are supported.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, img supports SVG. You can simply reference the HTML spec for img to state which image formats are supported.


**book.toml**

```toml
[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
src = "my-src" # the source files will be found in `root/my-src` instead of `root/src`
language = "en"
logo = "static/logo.png"
Copy link

@sanmai-NL sanmai-NL Sep 5, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the SVG format is supported, I prefer to use an SVG example.
That way, we don't have to add a sample binary to the Git index, and save space, in addition to the general advantages of SVG logos (crispness, etc.).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A quick test showed that SVG seems to be supported. Is there a logo I could use as a sample? If not, I'd just reuse the favicon.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think MdBook doesn't have a product logo yet. Using the favicon as sample seems fine, though .ico files may not be rendered correctly as source image for img-elements sometimes.

```

### Rust options
Expand Down
6 changes: 6 additions & 0 deletions src/config.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -417,6 +417,9 @@ pub struct BookConfig {
pub multilingual: bool,
/// The main language of the book.
pub language: Option<String>,
/// A logo to be displayed on top of the navigation bar. The path is relative to the source
/// path
pub logo: Option<PathBuf>,
}

impl Default for BookConfig {
Expand All @@ -428,6 +431,7 @@ impl Default for BookConfig {
src: PathBuf::from("src"),
multilingual: false,
language: Some(String::from("en")),
logo: None,
}
}
}
Expand Down Expand Up @@ -761,6 +765,8 @@ mod tests {
multilingual: true,
src: PathBuf::from("source"),
language: Some(String::from("ja")),
// TODO: add a test logo
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could this comment be clarified further (in-source)?

logo: None,
};
let build_should_be = BuildConfig {
build_dir: PathBuf::from("outputs"),
Expand Down
4 changes: 4 additions & 0 deletions src/renderer/html_handlebars/hbs_renderer.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -603,6 +603,10 @@ fn make_data(
"description".to_owned(),
json!(config.book.description.clone().unwrap_or_default()),
);
data.insert(
"book_logo".to_owned(),
json!(config.book.logo.clone().unwrap_or_default()),
);
if theme.favicon_png.is_some() {
data.insert("favicon_png".to_owned(), json!("favicon.png"));
}
Expand Down
7 changes: 7 additions & 0 deletions src/theme/css/chrome.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -344,6 +344,13 @@ ul#searchresults span.teaser em {
right: 0;
padding: 10px 10px;
}
.sidebar .sidebar-scrollbox .sidebar-book-logo img {
Copy link

@sanmai-NL sanmai-NL Sep 5, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sort the property names below.

display: block;
margin-left: auto;
margin-right: auto;
width: 100%;
max-width: max-content;
}
.sidebar .sidebar-resize-handle {
position: absolute;
cursor: col-resize;
Expand Down
5 changes: 5 additions & 0 deletions src/theme/index.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,11 @@

<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
{{#if book_logo }}
<div class="sidebar-book-logo">
<img src="{{ book_logo }}">
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

</div>
{{/if}}
{{#toc}}{{/toc}}
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
Expand Down