mdbook build never ends #2900
Description
Problem
I'm evaluating MdBook vs TypeDoc to build the documentation for a large data model. Unfortunately build that takes a few minutes for TypeDoc never ends when using MdBook.
In a smaller setup covering only a small data model fragment, MdBook builds everything correctly, however to cover the entire data model I'm creating around 25K markdown files nested in different directories and subdirectories. (A good stress test for any framework.)
There is no single error message, but the build runs forever showing slow increment in the number of files created in book/ directory.
Here is a comparison of total markdown files number to files created in book/ after a few minutes(!) run:
$ find mdbook/src -type f | wc -l
25091
$ find mdbook/book -type f | wc -l
3457This is taken from my MacBook. And the 2nd number is slowly incrementing.
Originally I was suspecting container workspace mount performance issues, but this seems to be not the case as:
- TypeDoc is able to finish the build without any problems
- GH Actions pipeline runs for ~40 min on a standard Ubuntu runner without finishing the build until cancelled.
Steps
No response
Possible Solution(s)
No response
Notes
When checking the log, it looks like MdBook keeps building files while spending some time rendering.
This looks similar to #2348 but as it supposed to be fix, could be a different thing.
2025-10-22 13:50:39 [DEBUG] (mdbook::utils::fs): Creating /workspaces/avd/mdbook/book/core_interfaces/p2p_links/port_channel_structured_config/switchport/port_security/mac_address_maximum/limit.html
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::hbs_renderer): Render template
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("language")], "language")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("default_theme")], "default_theme")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("text_direction")], "text_direction")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("title")], "title")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("is_print"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("base_url"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("description")], "description")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("favicon_svg"), value: Context(String("favicon.svg"), ["favicon_svg"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("favicon.svg")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("favicon_png"), value: Context(String("favicon.png"), ["favicon_png"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("favicon.png")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("css/variables.css")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("css/general.css")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("css/chrome.css")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("print_enable"), value: Context(Bool(true), ["print_enable"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("css/print.css")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("FontAwesome/css/font-awesome.css")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("copy_fonts"), value: Context(Bool(true), ["copy_fonts"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("fonts/fonts.css")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("highlight.css")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("tomorrow-night.css")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("ayu-highlight.css")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "each", params: [PathAndJson { relative_path: Some("additional_css"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("mathjax_support"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("path_to_root")], "path_to_root")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("default_theme")], "default_theme")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("preferred_dark_theme")], "preferred_dark_theme")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("search_js"), value: Context(Bool(true), ["search_js"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("searchindex.js")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("toc.js")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("search_enabled"), value: Context(Bool(true), ["search_enabled"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("default_theme")], "default_theme")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("path_to_root")], "path_to_root")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("search_enabled"), value: Context(Bool(true), ["search_enabled"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("book_title")], "book_title")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("print_enable"), value: Context(Bool(true), ["print_enable"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("path_to_root")], "path_to_root")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("git_repository_url"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("git_repository_edit_url"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("search_enabled"), value: Context(Bool(true), ["search_enabled"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("content")], "content")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "previous", params: [], hash: {}
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::helpers::navigation): Get data from context
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::helpers::navigation): Search for chapter
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("path_to_root")], "path_to_root")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("link")], "link")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "next", params: [], hash: {}
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::helpers::navigation): Get data from context
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::helpers::navigation): Search for chapter
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("path_to_root")], "path_to_root")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("link")], "link")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "previous", params: [], hash: {}
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::helpers::navigation): Get data from context
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::helpers::navigation): Search for chapter
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("path_to_root")], "path_to_root")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("link")], "link")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "next", params: [], hash: {}
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::helpers::navigation): Get data from context
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::helpers::navigation): Search for chapter
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("path_to_root")], "path_to_root")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("link")], "link")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("live_reload_endpoint"), value: Context(String("__livereload"), ["live_reload_endpoint"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering value: Path(Relative(([Named("live_reload_endpoint")], "live_reload_endpoint")))
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("google_analytics"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("playground_line_numbers"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("playground_copyable"), value: Context(Bool(true), ["playground_copyable"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("playground_js"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("search_js"), value: Context(Bool(true), ["search_js"]) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("elasticlunr.min.js")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("mark.min.js")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("searcher.js")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("clipboard.min.js")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("highlight.js")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "resource", params: [PathAndJson { relative_path: None, value: Constant(String("book.js")) }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "each", params: [PathAndJson { relative_path: Some("additional_js"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("is_print"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (handlebars::render): Rendering helper: "if", params: [PathAndJson { relative_path: Some("fragment_map"), value: Missing }], hash: {}
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::hbs_renderer): Creating core_interfaces/p2p_links/port_channel_structured_config/switchport/port_security/violation.html
2025-10-22 13:50:39 [DEBUG] (mdbook::utils::fs): Creating /workspaces/avd/mdbook/book/core_interfaces/p2p_links/port_channel_structured_config/switchport/port_security/violation.html
2025-10-22 13:50:39 [DEBUG] (mdbook::renderer::html_handlebars::hbs_renderer): Render template
Version
mdbook v0.4.52
tested on ARM (DevContainer on MacBook) and x86 (Github Actions)