mirror of https://github.com/rust-lang/mdBook synced 2024-12-14 14:52:37 +00:00

No description

Find a file

Sorin Davidoi 61fad2786b Improve accessibility (#535 ) * fix(theme/index): Use nav element for Table of Content * fix(renderer/html_handlebars/helpers/toc): Use ol instead of ul Chapters and sections are ordered, so we should use the appropriate HTML tag. * fix(renderer/html_handlebars/helpers/toc): Hide section number from screen readers Screen readers have this functionality build-in, no need to present this. Ideally, this should not even be in the DOM tree, since the numbers can be shown by using CSS. * fix(theme/index): Remove tabIndex="-1" from .page Divs are not focusable by default * fix(theme): Make sidebar accessible Using aria-hidden (together with tabIndex) takes the links out of the tab order. http://heydonworks.com/practical_aria_examples/#progressive-collapsibles * fix(theme/index): Wrap content inside main tag The main tag helps users skip additional content on the page. * fix(theme/book): Don't focus .page on page load The main content is identified by the main tag, not by auto-focusing it on page load. * fix(theme/index): Make page controls accessible * fix: Make theme selector accessible - Use ul and li (since it is a list) - Add aria-expanded and aria-haspopup to the toggle button - Use button instead of div (buttons are accessible by default) - Handle Esc key (close popup) - Adjust CSS to keep same visual style * fix(theme/stylus/sidebar): Make link clickable area wider Links now expand to fill the entire row. * fix(theme): Wrap header buttons and improve animation performance Previously, the header had a fixed height, which meant that sometimes the print button was not visible. Animating the left property is expensive, which lead to laggy animations - transform is much cheaper and has the same effect. * fix(theme/stylus/theme-popup): Theme button inherits color Bug introduced while making the popup accessible * fix(theme/book): Handle edge case when toggling sidebar Bug introduced when switching from animating left to using transform.		2018-01-15 21:26:53 +08:00
book-example	Override configuration using environment variables (#541 )	2018-01-14 02:38:43 +08:00
ci	Workaround for travis-ci/travis-ci#4704 (#529 )	2018-01-06 04:47:59 +08:00
src	Improve accessibility (#535 )	2018-01-15 21:26:53 +08:00
tests	Made it so the CmdRenderer writes directly to the child's stdin (#544 )	2018-01-14 19:14:27 +08:00
.gitattributes	add a .gitattributes to ensure proper line ending settings	2017-03-28 09:50:57 -04:00
.gitignore	ignore vscode dir in git	2017-09-01 08:22:01 +02:00
.travis.yml	Update travis CI (#516 )	2017-12-30 19:15:17 +08:00
appveyor.yml	fixed `cargo build --features=regenerate-css` on windows 10	2017-08-12 13:20:26 +02:00
build.rs	Fix typo	2017-11-27 13:18:51 +01:00
Cargo.toml	Made it so the CmdRenderer writes directly to the child's stdin (#544 )	2018-01-14 19:14:27 +08:00
CONTRIBUTING.md	updated links from azerupi to rust-lang-nursery (#489 )	2017-11-22 11:35:18 +01:00
LICENSE	Create LICENSE	2015-07-29 01:11:30 +02:00
README.md	Reformatted the README and added a link to the `master` docs (#525 )	2018-01-05 11:32:54 +08:00
rustfmt.toml	run rustfmt on the repository #398(Updated) (#438 )	2017-10-03 13:40:23 +02:00

README.md

mdBook

Linux / OS X
Windows

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

What does it look like?

The User Guide for mdBook has been written in Markdown and is using mdBook to generate the online book-like website you can read. The documentation uses the latest version on GitHub and showcases the available features.

Installation

There are multiple ways to install mdBook.

Binaries

Binaries are available for download here. Make sure to put the path to the binary into your PATH.
From Crates.io j This requires Rust and Cargo to be installed. Once you have installed Rust, type the following in the terminal:
```
cargo install mdbook
```
This will download and compile mdBook for you, the only thing left to do is to add the Cargo bin directory to your PATH.

Note for automatic deployment

If you are using a script to do automatic deployments using Travis or another CI server, we recommend that you specify a semver version range for mdBook when you install it through your script!

This will constrain the server to install the latests non-breaking version of mdBook and will prevent your books from failing to build because we released a new version. For example:
```
cargo install mdbook --vers "^0.1.0"
```
From Git

The version published to crates.io will ever so slightly be behind the version hosted here on GitHub. If you need the latest version you can build the git version of mdBook yourself. Cargo makes this super easy!
```
cargo install --git https://github.com/rust-lang-nursery/mdBook.git
```
Again, make sure to add the Cargo bin directory to your PATH.
For Contributions

If you want to contribute to mdBook you will have to clone the repository on your local machine:
```
git clone https://github.com/rust-lang-nursery/mdBook.git
```
cd into mdBook/ and run
```
cargo build
```
The resulting binary can be found in mdBook/target/debug/ under the name mdBook or mdBook.exe.

Usage

mdBook will primarily be used as a command line tool, even though it exposes all its functionality as a Rust crate for integration in other projects.

Here are the main commands you will want to run. For a more exhaustive explanation, check out the User Guide.

mdbook init

The init command will create a directory with the minimal boilerplate to start with.
```
book-test/
├── book
└── src
    ├── chapter_1.md
    └── SUMMARY.md
```
book and src are both directories. src contains the markdown files that will be used to render the output to the book directory.

Please, take a look at the CLI docs for more information and some neat tricks.
mdbook build

This is the command you will run to render your book, it reads the SUMMARY.md file to understand the structure of your book, takes the markdown files in the source directory as input and outputs static html pages that you can upload to a server.
mdbook watch

When you run this command, mdbook will watch your markdown files to rebuild the book on every change. This avoids having to come back to the terminal to type mdbook build over and over again.
mdbook serve

Does the same thing as mdbook watch but additionally serves the book at http://localhost:3000 (port is changeable) and reloads the browser when a change occurs.

As a library

Aside from the command line interface, this crate can also be used as a library. This means that you could integrate it in an existing project, like a web-app for example. Since the command line interface is just a wrapper around the library functionality, when you use this crate as a library you have full access to all the functionality of the command line interface with an easy to use API and more!

See the User Guide and the API docs for more information.

Contributions

Contributions are highly appreciated and encouraged! Don't hesitate to participate to discussions in the issues, propose new features and ask for help.

If you are just starting out with Rust, there are a series of issus that are tagged E-Easy and we will gladly mentor you so that you can successfully go through the process of fixing a bug or adding a new feature! Let us know if you need any help.

For more info about contributing, check out our contribution guide who helps you go through the build and contribution process!

There is also a rendered version of the latest API docs available, for those hacking on master.

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.