On extending mdBook

community
1

I think a good project would be to extend mdBook, with new features and less issues (I have a few personally.) Is there anything the community wants to see out of something like this? Currently I have these so far:

  • Significantly more thorough config file
  • Runnable code snippets (via play.rust-lang.org or a different service, through the config file)
  • Custom styles/themes (via CSS and YAML (marked as .book.theme) definitions)
  • Different markdown renderer (some things look incredibly strange)

If there’s anything you all want to see, please, let me know. I want to improve mdBook because I see it as heavily lacking, personally. There are more things I don’t like about mdBook, but I can’t remember all of them, hence the list being so short.

2

I assume you are not the original author of mdBook? So we might first ask them if they want any changes?

For your question: I generally like mdbook, I am using it for my "Rust for C-Programmers" book. Of course, compared to AsciiDoctor, which I used in 2020 for a different book, mdbook is very restricted -- which might be a result of MarkDown. One example is, that we have no numbered sections for the text. I created a plugin, see GitHub - StefanSalewski/mdbook-section-numbers: Preprocessor for mdbook to generate numbers for the section headings, which might work. But should every user have to manually install a plugin?

What is a bit ugly is currently, that with v0.43 and a dark theme the code segments flashes white. I have no idea if someone intends to fix that, I created a issue long time ago, but I think I finally closed it. What I generally would like to have is some semantic markup. Some way to mark a variable name, a inline code segment, and such with something like $var(i) or $code(i += 1;) and define elsewhere how that is rendered. In AsciiDoctor that is possible, in LaTeX of course too. And better support for references would be nice, e.g. to reference to captions of code segments, or to other chapters and sections. All that what is standard in LaTeX. But I don't think that someone intents to support that. Markdown is a very basic tool, not comparable with LaTeX. And the disadvantages of AsciiDoctor and LaTeX are, that they are more complicated to learn.

3

I just remembered two other features that I miss:

  1. An action to copy a Rust code example into the playground with a single click. I know that we can edit and run it in place. And we can copy the code into the clipboard, and then past into playground. But this is a multi-step action. I think it might be possible in one step, I think I have already seen a Rust page where it was possible.

A better working playground without the frequently "Timeout" messages would be nice as well. I recently tried to test a few code examples of my book, but after a dozen timeouts I gave up. I don't think this is a great experience for readers.

  1. Option to display a whole chapter as one large page. This default section view might be OK when we know exactly what we want to read. But to get an overview of a chapter it is ugly -- we need dozen of "next page" clicks, and might even have to scroll each displayed section to see all. Perhaps even an option to render the whole book as one large page would be nice.