Considering using mdbook instead of gitbook

[japaric]

This would remove our dependency on node.js, which would let us get closer to make this repo cargo buildable.

[nathankleyn]

@japaric @steveklabnik Is this something you're still interesting in doing? It feels like something I might actually be able to work on.

[steveklabnik]

@nathankleyn absolutely. It's been too big of a project for me to try to tackle, but it's something I want for sure.

[nathankleyn]

@steveklabnik If that's the case, I might have a poke tonight and get a feel for what's involved - it's something I'd love to try my hand at, although I will almost certainly have questions for you along the way! 😀

[steveklabnik]

Sure thing, I'd be happy to answer any questions. It's certainly a project that's feasable, it's just a lot of grunt work, and I've been trying to focus on 'write more docs' and less 're-do the build system'

The key thing is the plugin that gives us the fancier "embed the result of running this in the page." it's mostly javascript, but would need adapted a little.

Also, if you need any improvements in rustbook to support it, I'm happy to walk you through those too

[mdinger]

I'm opposed to this without rustbook being upgraded to having dark theme support. I find light themes much much harder on the eyes and so I wouldn't ever move to where a dark theme isn't available (I really dislike the that the book and std docs are light themed only).

Also, it'd be worth considering using mdBook instead. He seems to be putting more effort into improving it than rustbook is seeing and it's independent of the rust repo which makes it simpler to hack on.

[steveklabnik]

If mdBook is really full featured, I'm actually happy to have it just eat rustbook entirely, frankly. And I mirror rustbook out of tree too.

[mdinger]

It isn't yet I don't think but it has a few niceties that rustbook doesn't have like a more proper sidebar toggling and next/previous arrows. It's still new though. We gotta give it time. He also has printing the entire book on the todo list. That would be nice.

[nathankleyn]

@mdinger @steveklabnik Given the above, let me wait on this for now - I'll familiarise myself with the differences between rustbook and mdBook and get an idea of what needs to be done. If anybody else wants to pick this up who knows what they're doing, feel free! 😀

[mdinger]

mdBook now has multiple themes included including a dark theme. See the example render though it hasn't been pushed to crates yet. I'm not opposed to this anymore.

Something else which I think would be convenient is if cargo could export the JSON or TOML from the Cargo.toml. Then the cargo framework could handle the testing of the files (I think) and the example structure could just be exported into a JSON file which the book generator could grab to build the docs. Also discussed #439 and rust-lang/cargo#1968 (comment) .

[brson]

Should be converted to mdbook at this point - rustbook is doomed. I don't think there's anything blocking this. Just do the conversion and change the CI.

[steveklabnik]

Yeah, the only blocking is the "just", there's a lot going on here.

[mdinger]

See https://github.com/azerupi/mdBook/issues/29 but unless something has changed, as far as I know we're still waiting for examples which are editable. It's also missing search but I think that's a more minor issue.

[mdinger]

BTW, I may have time coming up this 4th of July week so if mdbook was in good enough shape for this, I may attempt it. We'll see how it goes.

[steveklabnik]

Updated the title here; rustbook is mdbook these days.