From 15772f41fbc46aea8ba65336fc5471dc2f81f14c Mon Sep 17 00:00:00 2001 From: Gabor Szabo Date: Wed, 2 Apr 2025 19:08:33 +0300 Subject: [PATCH 1/2] add the help button to the menu * connect to the help popup trigger code * add the configuration option to show the help icon * only set the event listener if the icon is there --- guide/src/format/configuration/renderers.md | 12 +++ src/config.rs | 18 +++++ src/front-end/js/book.js | 79 +++++++++++--------- src/front-end/templates/index.hbs | 5 ++ src/renderer/html_handlebars/hbs_renderer.rs | 1 + 5 files changed, 80 insertions(+), 35 deletions(-) diff --git a/guide/src/format/configuration/renderers.md b/guide/src/format/configuration/renderers.md index 7c1129e3af..831ba03ffd 100644 --- a/guide/src/format/configuration/renderers.md +++ b/guide/src/format/configuration/renderers.md @@ -301,6 +301,18 @@ The [`output.html.search.chapter`] table provides the ability to modify search s - **enable:** Enables or disables search indexing for the given chapters. Defaults to `true`. This does not override the overall `output.html.search.enable` setting; that must be `true` for any search functionality to be enabled. Be cautious when disabling indexing for chapters because that can potentially lead to user confusion when they search for terms and expect them to be found. This should only be used in exceptional circumstances where keeping the chapter in the index will cause issues with the quality of the search results. +### `[output.html.help]` + +The `[output.html.help]` table provides a way to configre the help menu. + +It currently has one field to disable the `?` icon on the menu by including the following: + +```toml +[output.html.help] +show-icon = false +``` + + ### `[output.html.redirect]` The `[output.html.redirect]` table provides a way to add redirects. diff --git a/src/config.rs b/src/config.rs index 7ef8bcef12..08588bc974 100644 --- a/src/config.rs +++ b/src/config.rs @@ -569,6 +569,8 @@ pub struct HtmlConfig { pub code: Code, /// Print settings. pub print: Print, + /// Help settings. + pub help: Help, /// Don't render section labels. pub no_section_label: bool, /// Search settings. If `None`, the default will be used. @@ -625,6 +627,7 @@ impl Default for HtmlConfig { playground: Playground::default(), code: Code::default(), print: Print::default(), + help: Help::default(), no_section_label: false, search: None, git_repository_url: None, @@ -655,6 +658,21 @@ impl HtmlConfig { self.smart_punctuation || self.curly_quotes } } +/// Configuration for how to handle help +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(default, rename_all = "kebab-case")] +pub struct Help { + /// Whether help icon should be displayed. + pub show_icon: bool, +} + +impl Default for Help { + fn default() -> Self { + Self { + show_icon: true, + } + } +} /// Configuration for how to render the print icon, print.html, and print.css. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] diff --git a/src/front-end/js/book.js b/src/front-end/js/book.js index de8219fdc2..42161bb884 100644 --- a/src/front-end/js/book.js +++ b/src/front-end/js/book.js @@ -643,6 +643,50 @@ aria-label="Show hidden lines">'; })(); (function chapterNavigation() { + function showHelp() { + const container = document.getElementById('mdbook-help-container'); + const overlay = document.getElementById('mdbook-help-popup'); + container.style.display = 'flex'; + + // Clicking outside the popup will dismiss it. + const mouseHandler = event => { + if (overlay.contains(event.target)) { + return; + } + if (event.button !== 0) { + return; + } + event.preventDefault(); + event.stopPropagation(); + document.removeEventListener('mousedown', mouseHandler); + hideHelp(); + }; + + // Pressing esc will dismiss the popup. + const escapeKeyHandler = event => { + if (event.key === 'Escape') { + event.preventDefault(); + event.stopPropagation(); + document.removeEventListener('keydown', escapeKeyHandler, true); + hideHelp(); + } + }; + document.addEventListener('keydown', escapeKeyHandler, true); + document.getElementById('mdbook-help-container') + .addEventListener('mousedown', mouseHandler); + } + function hideHelp() { + document.getElementById('mdbook-help-container').style.display = 'none'; + } + + + const helpicon = document.getElementById('show-help'); + if (helpicon) { + helpicon.addEventListener('click', () => { + showHelp(); + }, false); + } + document.addEventListener('keydown', function(e) { if (e.altKey || e.ctrlKey || e.metaKey) { return; @@ -664,41 +708,6 @@ aria-label="Show hidden lines">'; window.location.href = previousButton.href; } } - function showHelp() { - const container = document.getElementById('mdbook-help-container'); - const overlay = document.getElementById('mdbook-help-popup'); - container.style.display = 'flex'; - - // Clicking outside the popup will dismiss it. - const mouseHandler = event => { - if (overlay.contains(event.target)) { - return; - } - if (event.button !== 0) { - return; - } - event.preventDefault(); - event.stopPropagation(); - document.removeEventListener('mousedown', mouseHandler); - hideHelp(); - }; - - // Pressing esc will dismiss the popup. - const escapeKeyHandler = event => { - if (event.key === 'Escape') { - event.preventDefault(); - event.stopPropagation(); - document.removeEventListener('keydown', escapeKeyHandler, true); - hideHelp(); - } - }; - document.addEventListener('keydown', escapeKeyHandler, true); - document.getElementById('mdbook-help-container') - .addEventListener('mousedown', mouseHandler); - } - function hideHelp() { - document.getElementById('mdbook-help-container').style.display = 'none'; - } // Usually needs the Shift key to be pressed switch (e.key) { diff --git a/src/front-end/templates/index.hbs b/src/front-end/templates/index.hbs index 1be5bdb043..98fdd4c194 100644 --- a/src/front-end/templates/index.hbs +++ b/src/front-end/templates/index.hbs @@ -165,6 +165,11 @@ {{/if}} + {{#if help_show_icon}} + + {{/if}}

{{ book_title }}

diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index b1ea752053..768f52e8e0 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -608,6 +608,7 @@ fn make_data( data.insert("print_enable".to_owned(), json!(html_config.print.enable)); data.insert("fold_enable".to_owned(), json!(html_config.fold.enable)); data.insert("fold_level".to_owned(), json!(html_config.fold.level)); + data.insert("help_show_icon".to_owned(), json!(html_config.help.show_icon)); let search = html_config.search.clone(); if cfg!(feature = "search") { From cd26b56e7a3c2d2b74a4e13bd70c4a7112af17d7 Mon Sep 17 00:00:00 2001 From: Gabor Szabo Date: Tue, 22 Jul 2025 10:24:31 +0200 Subject: [PATCH 2/2] cargo fmt --- src/config.rs | 4 +--- src/renderer/html_handlebars/hbs_renderer.rs | 5 ++++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/src/config.rs b/src/config.rs index 08588bc974..720fd52115 100644 --- a/src/config.rs +++ b/src/config.rs @@ -668,9 +668,7 @@ pub struct Help { impl Default for Help { fn default() -> Self { - Self { - show_icon: true, - } + Self { show_icon: true } } } diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index 768f52e8e0..921a9ea9cc 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -608,7 +608,10 @@ fn make_data( data.insert("print_enable".to_owned(), json!(html_config.print.enable)); data.insert("fold_enable".to_owned(), json!(html_config.fold.enable)); data.insert("fold_level".to_owned(), json!(html_config.fold.level)); - data.insert("help_show_icon".to_owned(), json!(html_config.help.show_icon)); + data.insert( + "help_show_icon".to_owned(), + json!(html_config.help.show_icon), + ); let search = html_config.search.clone(); if cfg!(feature = "search") {