Having a search bar would be very very useful. rustbyexample has one for example. I'm not sure how it would be implemented. I'm sure this has long been wanted by the rust book.

Being able to search for programming keywords would actually make it very unusual and better than most too (outside the scope of a regular search bar though)

Since last year, due to other projects, interests and scholar obligations, I have less and less time to maintain this project. I initially started this project to familiar myself with Rust and I think I achieved that goal. I now have different interests where I want to invest some time in. Therefore, I don't have the bandwidth anymore to maintain this project. In the last months, a lot of people have shown interest in this project and have contributed. I appreciate that a lot! But at this point, I feel like I can't devote enough time to review issues and PRs within a time frame that I still consider to be respectful to the persons that contribute.

I don't want to block progress and leave contributors hanging, so I think it is time that I pass over the role of main maintainer to one or more interested persons.

@steveklabnik @budziq @frewsxcv @Michael-F-Bryan

Repository was formatted using rustfmt-nightly. The max_width needed to be increased to remove errors of width being more than the default 120. Some error still persist like: error: left behind trailing whitespace ---> /mdBook/src/utils/mod.rs:178

and with the fix of code snippets being destroyed from doc comments.

This PR adds a new internal representation for the book, plus functionality for loading that book using the Summary we got when parsing SUMMARY.md.

It is part of a larger issue (#359) which is working towards refactoring the Book structure and decouple it from the other bits like rendering and configuration.

By default, mdbook includes tracking code from Google. See: https://github.com/rust-lang-nursery/mdBook/search?utf8=%E2%9C%93&q=google&type=

Can we please remove this so that books generated by mdbook do not expose the people who read them to surveillance by Google/Alphabet, Inc.

The toot that brought it to my attention: https://mastodon.host/@BartG95/101222458295737848 (after I hosted a render of The DAT Protocol book on my own site. (Thereby unknowingly exposing people to tracking from my personal site.)

Related issue on The DAT Protocol book’s issue tracker: https://github.com/datprotocol/book/issues/20

Many code snippets, which are supposed to run in the playground, simply do not work and render the "hidden" parts of their code, causing newbies like me great confusion.

# #![allow(unused_variables)]
#
#fn main() {

as found in enums.html, etc

When using private browsing on mobile safari (iphone) local storage is not available so: localStorage.setItem('theme', theme); throws an error. I think modernizr might have a check for this? ([https://github.com/Modernizr/Modernizr/blob/master/feature-detects/storage/localstorage.js](modernizr localstorage.js)

Also the hamburger menu does not click, which is probably because the localstorage thing.

I'd like to open a discussion on using a YAML list for the summary file, and an optional YAML header in the Markdown chapters.

I realize that this would effectively kill your work on parsing the Markdown summary, but this would pay off for more complex TOC structures, while still being easy to write for the simple case.

The thing is that things start to get complicated when you have to start to try and satisfy the EPUB and MOBI specifications.

I am not suggesting TOML because it is not good at representing these kind of nested hasmap types.

In the simplest case the list items are the source path, and you can parse the title from the first heading. In this case the Cover, Title Page and Contents pages for the ebook formats can take sensible defaults.

- part-1.md
  - nameless-labyrinth.md
  - glacial-surface.md
  - countless-windows.md
    - closed-shutters.md
- part-2.md
  - semblance-of-equilibrium.md

For the ebooks the <guide> tag is mandatory in OEBPS/content.opf:

 <guide>
    <reference href='chapters/cover.xhtml' title="Cover" type='cover' />
    <reference href='chapters/titlepage.xhtml' title="Title Page" type='title-page' />
    <reference href='chapters/toc.xhtml' title="Contents" type='toc' />
</guide>

And YAML really pays off when you have to manipulate chapter properties, or to indicate for the ebook <guide> what's what. Say, when your book has a special titlepage design or the 'Cover' is called 'Capa' (pt) or 'Borító' (hu).

- { title: "Cover", path: "cover.xhtml", type: cover, linear: no }
- { title: "Title Page", path: "titlepage.xhtml", type: title-page }
- { title: "Contents", path: "toc.xhtml", type: toc }
- part-1.md
  - { title: "The Nameless Stone Labyrinth", path: "nameless-labyrinth.md" }
  - nameless-labyrinth.md
  - glacial-surface.md
  - countless-windows.md
    - closed-shutters.md
- part-2.md
  - semblance-of-equilibrium.md

There is an example TOC here.

Until version 0.0.28, it was possible to have a SUMMARY.md like this:

# Summary

- [Real chapter](./real.md)
- [Empty chapter]()

While the "real chapter" was rendered and given a link in the summary on the left-hand side, the "empty chapter" was just given an entry in the summary without a link.

This behaviour was very helpful in lots of cases, e.g.

• when the book was not yet complete or
• to give the summary additional structure.

Since version 0.1.0, empty chapters are not longer supported. They result in the following error:

$ mdbook build
2018-01-24 16:08:20 [ERROR] (mdbook::utils): Error: Summary parsing failed
2018-01-24 16:08:20 [ERROR] (mdbook::utils): Caused By: There was an error parsing the numbered chapters
2018-01-24 16:08:20 [ERROR] (mdbook::utils): Caused By: Error at line 4, column 16: You can't have an empty link.

Is the new behaviour intended? If yes, is it possible to revert that decision since the old behaviour has practical benefits?

• PR 200
  • Does everything still work?
  • Features
    • Renderer
    • Static assets
    • chapter TOML headers
    • Multi-language books
      • translation cross-linking
      • book.toml
      • folder layout
  • Documentation
  • Structs
  • Catching up

See a demo: Alice's Adventures in Wonderland, in three languages with mdbook. Chapter excerpts for testing. Markdown sources here.

Use the gambhiro/mdbook/multilang branch for compiling or reading the code.

This PR is for reviewing and discussing a large refactoring which involves:

• #5 (multi-lingual support)
• #146 (book representation)
• #149 (separate renderer design)
• #96 (TOML format for config)
• #178 (custom.css)

This PR incorporates PR #147 (new book struct), as I started by merging that and working from there.

This also prepares the ground for #88 (ebooks), which after this can be implemented as another renderer.

Does everything still work?

Let's compose a list of user-level features that I can test and debug:

• [x] the Rust Book should build
• [x] CLI commands
• [x] single-language book
• [x] multi-language book
• any more?

Rust book

Move src/img to assets/img for the images to be copied. Paths in the Markdown source don't have to change.

CLI commands

init

• [x] SUMMARY.md is parsed and missing chapter files are created
• [x] .gitignore is created on confirmation

build

• [x] the html builds
• [x] custom template is used if found in assets/_html-template
• [x] book assets are copied if found in assets

watch

• [x] making a change in a chapter rebuilds the book

serve

• [x] book is served on :3000
• [x] making a change in a chapter updates the page in the browser

test

• [x] chapter files are tested with rustdoc

Single language book

See src/tests/book-minimal

Works as expected as far as I can tell.

Multi-language book

See src/tests/book-wonderland-multilang

Works as expected as far as I can tell.

Features

Renderer

Renderer is a trait expecting two functions, .build() and .render():

pub trait Renderer {

    /// When the output format is determined (by a CLI argument for example),
    /// call `.build()` of the selected Renderer implementation.
    ///
    /// Constructs an `MDBook` struct given the path of the book project,
    /// preparing the project and calling `render()`, doing what is necessary
    /// for the particular output format.
    ///
    /// This involves parsing config options from `book.toml` and parsing the
    /// `SUMMARY.md` of each translation to a nested `Vec<TocItem>`.
    ///
    /// Finally it calls `render()` to process the chapters and static assets.
    fn build(&self, project_root: &PathBuf) -> Result<(), Box<Error>>;

    /// Responsible for rendering the chapters and copying static assets.
    fn render(&self, book_project: &MDBook) -> Result<(), Box<Error>>;

}

The general idea is that a data structure (MDBook) is constructed by parsing the book's files, and this is given to the renderer's .render() function which does whatever it needs to do with it to produce its output format.

.build() is responsible for calling the necessary functions to construct MDBook, and .render() is responsible for writing the output based on that MDBook.

So MDBook is not responsible to rendering or writing anything, but it should represent all the information that the renderer might need to write all its output files.

MDBook has a .render_intent attribute that is a descriptive enum which internal functions can inspect if they need to make decisions based on what output format has been selected.

pub struct MDBook {
    ...
    /// Informs other functions which renderer has been selected, either by
    /// default or CLI argument.
    render_intent: RenderIntent,
    ...
}

pub enum RenderIntent {
    HtmlHandlebars,
}

Static assets

The application's static assets are embedded in the binary from data/ using includedir.

The book's static assets are expected in assets/. Everything will be copied to the book's output folder, except for folders which start with underscore (i.e. user might have _sass or _html-template and so on).

chapter TOML headers

TOML headers can be added at the beginning of a chapter file, these will be parsed into the attributes of the Chapter struct. See babel.md.

+++
title = "The Library of Babel"
author = "Jorge Luis Borges"
translator = "James E. Irby"
+++

# Babel

The universe (which others call the Library) is composed of an indefinite and
perhaps infinite number of hexagonal galleries, with vast air shafts between,
surrounded by very low railings. From any of the hexagons one can see,
interminably, the upper and lower floors.

Multi-language books

See src/tests/book-wonderland-multilang

translation cross-linking

Automatic chapter-to-chapter linking is implemented with incrementally trying harder to find a translation, but never refusing to build the book. I.e. something should always happen, whatever the author does, and more and more should happen as they keep working on their content.

• links to the top-level index pages of the translations are displayed above the TOC in the sidebar
• chapter translations are displayed in the title bar when the application can find a translation, otherwise it displays a grayed-out text of the language code

Buidling on the ideas described in #5, finding a translation works step by step this way:

• [x] taking the manual links are given in the TOML header (see alice/rabbit-hole)
• [x] finding a match by a specific chapter.translation_id string given in the TOML header (see alice/long-tale)
• [x] finding a match by chapter.src_path (see alice/tears)
• [x] finding a match by section number, if the TOC is structurally the same, checking by counting the number of sections

This covers the following scenarios:

If the translator copy-pastes the SUMMARY.md of the original, changing only the titles, translations will be identified by the .src_path.

If they rename the file names too, so that the URLs also are in the target language, but the TOC keeps the same sectioning structure, translations will be identified by section numbers.

If they change the sectioning structure too, they can insert a chapter.translation_id string in the original and the translation. Any string, not necessarily an UUID. This would maintain cross-links when the original changes file name.

If nothing else, they can provide the translation link directly in the TOML header. This breaks when the target file changes file name.

It has to be kept in mind that translations are projects on their own, and can even present the same material in a different structure than the original. The original and its translation are likely to be at different stages at various times. In addition, people have different workflows, they don't necessarily work in a one-two-three disciplined way either.

book.toml

The main language is recognized as the first given in the TOML. Otherwise it has to be marked with is_main_book = true.

The language code will always be the translation key, the language name can be set optionally.

[[translations.en]]
title = "Alice's Adventures in Wonderland"
author = "Lewis Carroll"

[[translations.fr]]
title = "Alice au pays des merveilles"
author = "Lewis Carroll"
language_name = "Français"

[[translations.hu]]
title = "Alice Csodaországban"
author = "Lewis Carroll"

folder layout

book-wonderland-multilang
├── book.toml
├── assets
│  └── images
│     ├── Queen.jpg
│     ├── Rabbit.png
│     ├── Tail.png
│     └── Tears.png
└── src
   ├── en
   │  ├── SUMMARY.md
   │  ├── long-tale.md
   │  ├── rabbit-hole.md
   │  ├── tears.md
   │  └── titlepage.md
   ├── fr
   │  ├── SUMMARY.md
   │  ├── cocasse.md
   │  ├── larmes.md
   │  ├── terrier.md
   │  └── titre.md
   └── hu
      ├── SUMMARY.md
      ├── cimoldal.md
      ├── konnyto.md
      ├── nyuszi.md
      └── tarka-farka.md

Documentation

• [x] update documentation in the code
• [x] update documentation in book-example

Structs

Catching up

The last common commit with master was 8a178e3, I will have to catch up with the updates since then.

• [x] catch up with updates
• [x] resolve conflicts with master

This PR introduces a Service Worker in order to dynamically cache the assets (only what the page requests, so respecting all the flags) and statically precache the chapters. The end result is that the resulting book would be available offline in supported browsers - Chrome (desktop and Android), Opera and Firefox (desktop and Android), for now, Edge and Safari later. As a bonus, if the book is used while offline, Google Analytics events are also cached and sent out when the user is back online.

Things intentionally left unaddressed (waiting for feedback):

• user notification/configuration - I personally think caching should be done in the background, with a small toast notification informing the user that the book is available offline.

A small caveat is that the book is not available offline after the first-page load, but only after the second one. This is because on first load we precache the chapters, but the assets will be cached only when they are requested the second time.

Alongside supporting offline usage, this will also introduce a massive performance boost on second visits, since there is no need to hit the network for any of the assets.

The Service Worker is not installed during development (same procedure as for Google Analytics).

If you want to test this:

• Add offline-support = true to the [output.html] section
• Disable the check for localhost at the end of book.js

Closes #546.

~~This PR adds support for an optional config option:~~ ~~"favicon": "path/image.png"~~ ~~Users can specify their own favicon and mdBook will copy it and set up the html for it.~~

This PR adds support for indicating a custom favicon.png via the theme folder.

This adds a few lines on how a custom version of highlight.js can be obtained and made available to mdbook. With that information available, all issues about adding support for a specific language should be safe to be closed because mdbook in its default setup probably does not need to support every possible language.

I have seen that there are ongoing efforts to move away from highlight.js but I guess this information may nevertheless be useful in the meantime.

https://github.com/rust-lang/mdBook/blob/41a6f0d43e1a2d9543877eacb4cd2a017f9fe8da/src/theme/index.hbs#L213

I was navigating through some books with short pages like https://google.github.io/comprehensive-rust/control-flow/break-continue.html, was trying to go through pages and pages through next button ]] using vimium extension, I find it a bit slow, maybe prefetching would help and loading the user waiting time for the next page? Like <a rel="next prefetch" ...>.

I think maybe the previous don't need it since the chance of reading the previous page over the next pages is lesser, and books are usually not expected to read in the reversed order.

If I have an API of the form MyType::my_special_func in a book, searching for my_special_func does not return any matches.

I must search for MyType::my_special_func instead. It seems like :: is considered part of the text.

It would be much better to treat :: as non-text characters and allow searching for both MyType and my_special_func.

I ran into a hang issue when running 'mdbook serve', where after touching any .md source file, the mdbook process will spin 100% CPU.

I think I have diagnosed it to a blank .gitignore file located a few parent directories above the book source tree (and no .gitignore file within the book tree).

The mdbook docs say this:

Note: Only the .gitignore from the book root directory is used. 
Global $HOME/.gitignore or .gitignore files in parent directories are not used.

However, I believe this code in watch.rs checks all parent hierarchies of the book for a .gitignore file (ie the ancestors() call)

fn find_gitignore(book_root: &Path) -> Option<PathBuf> {
    book_root
        .ancestors()
        .map(|p| p.join(".gitignore"))
        .find(|p| p.exists())
}

I'm not a rustacean, but is something like this a correct fix?

fn find_gitignore(book_root: &Path) -> Option<PathBuf> {
   let gitignore = book_root.join(".gitignore");
   gitignore.exists().then_some(gitignore)
}

Addresses https://github.com/rust-lang/mdBook/issues/1969.

This is intended to allow the user to browse the documents with the same convenience as mdbook build --open, but without building a book redundantly when it's already built. And without hijacking the terminal like mdbook watch and mdbook serve.

This is a rough first iteration. I have likely missed some details (I'm new to the codebase).

When I run mdbook build --open, then it lets me browse the documentation without having to keep the terminal busy/occupied. Just browse the docs and keep doing other stuff in the terminal.

But when I run mdbook watch --open, then the terminal becomes unavailable while the docs are open. If I run ctrl+C in the terminal, it will automatically close the documentation.

Please modify mdbook watch so that it can serve the documents without hijacking the terminal.