rust-lang / mdbook

Create book from markdown files. Like Gitbook but implemented in Rust

mdBook

mdBook is a utility to create modern online books from Markdown files.

Check out the User Guide for a list of features and installation and usage information. The User Guide also serves as a demonstration to showcase what a book looks like.

If you are interested in contributing to the development of mdBook, check out the Contribution Guide.

License

All the code in this repository is released under the Mozilla Public License v2.0, for more information take a look at the LICENSE file.

mdbook's Issues

Error in copy_files_except_ext

[fn] copy_files_except_ext
[*] Loop
[*] "/home/azerupi/ECAM/PH20/src/ondes_mecaniques"
[*] is dir
An error occured:
File exists (os error 17)

relative paths to js and css broken

In the output, the paths to the js and css files are broken in files that are in a directory.
The same directory structure as the source is used but the link to the static files stays the same...

Use the index finger icon on the menu toggle thing

This menu item uses the "text insertion mouse pointer" and not the click on things "index finger pointer". This should be fixed.

(the screengrab software seems to ignore the mouse)

Add logging to facilitate debugging

I would like to have a uniform way to write short output for the end user but be able to activate debugging output when I develop.

How should I handle this in rust ?

Highlight active chapter in toc

Highlight the currently viewed chapter in the sidebar table of content. (blue like hover)

Renderer

Renderer

• Generic Renderer trait
  • fn render(&self, &Vec<BookItem>, &BookConfig)
• MDBook method to change renderer (builder pattern)

Html Renderer using Handlebars as template engine (default renderer)

• book to json data
• create new html page for every BookItem
  • keep structure from source
• Render markdown to html
• Construct TOC

root url is not correct when index is created from file that is not at root

index.html is created by copying the first file in summary.md. But when that first file is not at the root level it has a base url that points to root <base href="../"> but index.html is placed at the root level, leaving base untouched. index.html will therefore try to fetch the css and js files from a different directory than root.

Don't include book output in repository

The book-example html output is modified a lot and there is no reason to have diffs of it...

Add it to .gitignore and modify Travis script to run mdbook before committing to gh-pages

SUMMARY.md support for non-list elements

In SUMMARY.md support non-list entries:

For example:

# Summary

[Introduction](README.md)
[Foreword](foreword.md)

- [chapter 1](chapter_1.md)
- [chapter 2](chapter_2.md)

[Appendix](appendix.md)
--------------------
[Contributors](contributors.md)
[License](license.md)

• non-list link would be rendered without the section (chapter number)
• separator to separate some parts

Sidebar scroll down to current chapter

When you load the page the sidebar should scroll down to the currently viewed chapter. This is especially important for large books. The reader shouldn't have to scroll manually.

This is probably best done with JavaScript

Complete documentation

Before release 0.0.1, write a complete documentation of how to use it, what features are available etc.

[Discussion] Add solid Error messages

When using the cli tool there should be solid error messages explaining exactly what went wrong, if it is a parsing error add line numbers, ...

Non-fatal errors should not cause mdBook to stop. They should be stored and reported at the end.

How can this be done? What would be a good design?

Inspiration

• Cargo

The sidebar come back after being hidden

If you're on a page and hide the sidebar, switching to the next page will bring the sidebar back. It shouldn't do that.

Expose coherent API

Expose the inner functionality without exposing everything. I should think carefully about what has to be exposed and what should not.

Maybe rewrite some parts for coherence, etc.

init --theme

The mdbook init --theme command should copy all the theme files over to src, so that the user can modify them without having to start from scratch.

I am not sure if it should also do the rest of the normal init, or not

Update doc for --theme flag

Change handlebars helpers for the navigation

Remove JavaScript block that handles the hiding of the navigation icons and modify the handlebars helper like explained here: sunng87/handlebars-rust#32.

Also expose the name of the previous / next chapter in addition the the link.

• Change handlebars helper
• Expose chapter name
• Remove JavaScript

Add tests

Add tests in the code.

I have never really used tests, if someone could help me make meaningful tests that would be wonderful!

Right left arrows overlap the text if the width is shunk too much

The arrows overlap the text when the width is too small. See the picture.

next arrow points to current page

I just noticed that even on this page for example, the next arrow points to the current page.

Add script to deploy demo book to gh-pages

I am now using Travis to run tests, it would be nice if it would push the demo book to the gh-pages branch on success

book.json should not be in src?

At the moment book.json (the config file) is placed in src but it is probably better to put it in the root directory (where you call build) to be able to specify a custom src folder...

Images are not copied

Images (and all other static files) are not copied to book/

Add setting to automatically add "fork me on github"

By having a link to the github repo you can probably automatically deduce the link to the current file and add the "github fork me" banner.

Support embedding of rust playpen examples which are runnable

For example, just like http://rustbyexample.com/

Clean output directory before rendering

Before rendering it would be good to clean the output directory to prevent "ghost files". Files that where rendered previously but are now renamed, rendered to another location or removed...

Math formula support ?

Great work with this project! I would love to see mathjax or katex integration. I use math formulas frequently and pandoc supports this. Here is a render from pandoc with mathjax integration

and the same thing in mdbook

I am using them in parallel for this reason right now.

Refactor the renderer

Currently the renderer is one big mess. It should be refactored, divided into smaller blocks and replace repetitive blocks if possible...

Add code highlight support

It looks like pulldown-cmark outputs code blocks to standard html5 code blocks. Therefore it would be trivial to add code highlighting with a JavaScript library like Prism.js

Add multilingual support

Add support for multiple languages.

Init -> create files in summary.md

When you use mdbook init and SUMMARY.md already exists:

Parse SUMMARY.md and create the files.

For example, SUMMARY.md contains:

# Summary

- [Chapter 1](chapter_1.md)
- [Chapter 2](directory/chapter_2.md)

Create

src/
├── chapter_1.md
├── directory
│   └── chapter_2.md
└── SUMMARY.md

Have a dark theme available which the user can enable

Dark themes are much easier on the eyes especially when the user finds them agitating and too bright. I actually wouldn't move away from gitbook without dark theme support because of it.

This pic is rustbyexample in dark theme mode:

Print friendly option

When you try to print now, you only print the current chapter. An option to print the whole book would be handy. Also currently the css is not print friendly...

How?
Render one big html page from all the chapters alongside the normal pages, specifically for printing?

To-Do

• Make print friendly css (no sidebar visible while printing, different margins etc...)
• Add an option to print the whole book at once

Add previous and next navigation

Their should be a previous and next link on the page.

First link in SUMMARY.md should be rendered as index.html

First item in SUMMARY.md should be rendered as index.html because the browser does not know what file to open...

The easiest method would be to render it once as index.html and once as the original name to prevent broken links.

The cleanest method would be to modify all links from the original name to index.html but we would have to go through all the content...

Alternative idea use JavaScript to redirect if the url is not pointing to any file

Use serde instead of rustc-serialize ?

I have heard good things about serde. At the moment I use rustc-serialize, should I use serde instead?

What are the differences?

Remove all unwraps

Should never use unwrap because mdBook should never panic. Instead the errors should be passed to the user and let him decide what to do.

Remove all unwraps and replace by a try! or a match

Menu bar is not pushed up when scrolling

The menu-bar stays fixed and is not pushed up when scrolling down, the content is therefore clipped under the menu-bar and it is not aesthetically pleasing.

Add possibility to change renderer

Add a way to change the renderer. The default renderer is the handlebars-html renderer but other people could implement their renderers and hook them in.

[TOC] with nested lists, toc comes back only one level

The table of content generated does not close the lists correctly when it has to come back from multiple levels:

- [1]()
    - [1.1]()
    - [1.2]()
        - [1.2.1]()
- [2]  <-- **Bug:** Is not aligned with 1 but with 1.1

Theme

Default theme

Html

• add Open Sans font
• add font-awesome icons
• menu bar
  • button to hide sidebar
• navigation to next and previous chapter

CSS

• Multiple css files for different parts so it's easy to selectively overwrite parts of the design. Concatenated into one file when build
  • book.css for general css
  • content.css for css that affects the content
  • sidebar.css

JavaScript

Custom theme

By having a theme directory in src your theme would be used instead of the default theme.

Let users define new handlebar helpers

Let user define their own handlebars helpers and load them before rendering the template.

I have to test if handlebars helpers can be used directly from in the markdown
If not, it has more limited usage

Links should have same color as sidebar links

At the moment links in the content have the ugly default browser style, they should have the same color as the sidebar links and should not be underlined.

Local fallback for CDN hosted ressources

• Font Awesome
• Google Fonts (Open Sans) Edit: maybe not that important, other (similar) fonts will be used instead
• JQuery
• MathJax

Are loaded from CDN's but should have a local fallback for offline use and for when the CDN is down.

Have a search bar

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)

book config file

There need to be a config file for the book where you can modify all the settings and attributes.

_Name of that config file?_

• .book hidden file may cause trouble, but could be an advantage also
• book.conf
• book
• book.json for compatibility with gitbook?

Chose book.json for a little compatibility with gitbook

_Parameters that can be read from the config file_

• title
• author
• destination _{note: source does not have to be specified because book.json is in the source directory...}

more can be added later

Parse SUMMARY.md

This issue tracks what is left to do to parse SUMMARY.md

• Check if SUMMARY.md exists at the given path

  not sure it is necessary, File::open will result in an error of it does not exist

• open the file

• parse list elements - [name](path)

• support for list elements beginning with - or *

• support nested elements

• support empty links

• support non-list elements (elements that will not be numbered)

Option to collapse elements in sidebar

Right now, all the elements of the sidebar are visible at all time. But if you have a large book the sidebar can become very crowded.

An option to collapse the sidebar elements would solve this problem.

There could be a config entry to set the default, but ultimately the end user should be able to decide if it's enabled or not. Therefore it should be done in JS.

To-Do

Overview of things to do

Build

Part that builds the book from the markdown files

• data structure for book --> BookItem
• parse SUMMARY.md #2 (Rudimentary implementation done)
• Create toc
• markdown support
• Multilingual support
• [ ]

Renderer

See issue #3

• html renderer (using handlebars)

Theme

Html, Css and JavaScript files that will be used to render the website.

See issue #4

• basic default theme
  • basic html
  • basic css
  • basic js
• use Handlebars for templating ?
• possible to have custom theme by adding a theme directory in src
  • only selectively overwrite files of the theme

Config

• create a BookConfig struct to store config parameters
• .book config file
• add function read_config (builder pattern)

Commands

mdbook init

Command to create boilerplate files and directory structure

• If it does not exist, create src folder
• If it does not exist, create book folder (output)
• If it does not exist, create src/SUMMARY.md with 1 example chapter
• Create the example chapter file src/chapter_1.md
• mdbook init [path] init the given directory by path instead of the current directory
• add a flag that creates the src/theme directory with the default theme for modification
• When SUMARRY.md exist, parse it and create the chapter files of they do not exist.

mdbook build

• mdbook build [path] builds the given directory by path instead of the current directory

mdbook watch

Command to watch the files and trigger a build when some files changed

• trigger build on file change