mdBook v0.0.1 on Crates.io

announcements
1

I just published my first crate to Crates.io! Hooray :smile:

I present to you:

##mdBook

It's a utility to create a book from markdown files. Much like Gitbook but in Rust.

Here are link to the Github repo, the Documentation and Crates.io

Motivation behind the project

There are a couple of reasons why I started this project, but here are the main ones:

  • I needed a project to learn Rust
  • I wanted to contribute to Rustbook, but it's not that easy. You can't add whatever you want because it's a part of the rust official repo, you have to be careful not to break anything, it's pretty specific, ...
  • I wanted to use it for personal projects. And I want something very customizable. Where the look and feel can be completely changed.
  • Earlier this year, before I knew about Rust and before I knew about Gitbook I already thought about making a similar utility that would use markdown files to compile notes about my school classes. And eventually propose to teachers to compile their syllabi with it.

Structure

There are two main parts of this crate:

  • The library: the crate is structured so that all the code that actually does something is part of the library. You could therefore easily hook mdbook into your existing project, extend it's functionality by wrapping it in some other code, etc.
  • The binary: just provides a nice command line interface for the features in the library.

Feedback

This is my first real open source project, therefore I lack a bit of experience in many fields. Feedback, be it good or bad, is highly appreciated. Especially feedback about:

  • API design
  • Code style
  • Documentation

Feature requests, bugs and ideas can be submitted by creating a new issue

And of course everyone is welcome to improve project and submit pull-requests :blush:

Also, many thanks for all the awesome help I got from the marvelous rust community since I began to learn Rust in May! :kissing_closed_eyes:

5 Likes
2

I'm glad to see this using pulldown-cmark. Do you have examples of what it looks like in deployment? Do you have plans to replace upstream rustbook with this?

3

Yes the documentation is rendered with mdBook.

Well, I would be honored if this got used to render rustbook. And I would gladly work up to that. But that is not up to me to decide :blush:

4

Thanks for using handlebars. I wish there will be more and more cases with the library.

5

It looks like MkDocs, which is written in Python. You may want to steal some ideas from it? :slight_smile:

6

Thanks, I will take a look :wink: