What does HackerNews think of mdBook?
Create book from markdown files. Like Gitbook but implemented in Rust
Gitlab Pages + mdBook works well for more documentation or book-like sites. I could easily this working for certain types of project sites.
* Similar problem statement by Stavros in this website: https://notes.stavros.io/ He’s using Joplin [1] to write and then exports everything in an mdbook [2].
It's very easy to customize either via plugins with Rust or by overriding template files. While the linked article is cool, it seems like a lot of effort to maintain such a set up. Then again, if you're a Ruby expert I could see this being worth it.
Rust Book: https://doc.rust-lang.org/book
Rust Rand Book: https://rust-random.github.io/book
Rust WebAssembly Book: https://rustwasm.github.io/book
Rust Unstable Book: https://doc.rust-lang.org/beta/unstable-book/index.html
Rustonomicon: https://doc.rust-lang.org/beta/nomicon/index.html
Cargo Book: https://doc.rust-lang.org/cargo
Which seems to be generated by https://github.com/rust-lang/mdBook
Now, I don't see why "book" should seem so grand. Remember when reference books would come out as a "bible"?
As for bounds check, here's a relevant issue raised on rand crate: https://github.com/rust-random/rand/issues/592
One can dig for a kind of "unsafe assertions" with https://doc.rust-lang.org/std/hint/fn.unreachable_unchecked.... (so the random code, for example, could have before returning value 'if x >= upper { unsafe { unreachable_unchecked() } }')
It can do LaTeX and code, and be updated in real time so those were real time notes!
Some other examples
* https://briantliao.com/interviewing-notes/
[1] https://learnbyexample.github.io/py_resources/
[2] https://github.com/rust-lang/mdBook
[3] https://www.getzola.org/documentation/getting-started/overvi...
Or just publish it on GitHub? There's a discussions feature but I don't think it is out of beta yet. Until then you could use issues for discussions. Or reddit may be?
I use pandoc to convert markdown to pdf/epub and my initial learning with pandoc [1] resulted in single file usage. So, I kept it like that. I'm planning to create a separate chapter-wise branch so that I can publish a nicer web version with tools like mdBook [2]. This will require a bit of scripting to handle references across chapters.
[1] https://learnbyexample.github.io/tutorial/ebook-generation/c...
mdbook (https://github.com/rust-lang/mdBook) uses elasticlunr (http://elasticlunr.com/) as an inverted index and is generated statically.
The same is done for zola (https://www.getzola.org/documentation/content/search/).
I back everything up in a private git repo and then use various plugins built on top of mdbook to get all the functionality I want:
* rendering graphviz: https://github.com/dylanowen/mdbook-graphviz
* adding tags to the pages: https://github.com/dylanowen/mdbook-tag
* setting up sections to only render locally and not get published: https://github.com/dylanowen/mdbook-access
The plugin system is super easy to use and you don't need to code everything in rust. You can use any language.
I'm also working on a better renderer instead of just running the mdbook server all the time: https://github.com/dylanowen/mdnotes
I believe with plugins you can meet most of the requirements you have: * bidirectional: definitely could be a plugin
* math support: potentially this feature: https://github.com/rust-lang/mdBook/blob/master/book-example...
* customizable themes: you can completely overwrite the wrapping html and CSS
* rich formatting beyond markdown: mdbook supports inline html/js as it's based on commonmark
* WYSIWYG: this is the main missing piece, my strategy is to just run my mdnotes application next to my text editor.
It's great, the directory structure is straightforward and even supports search (through lunr.js) out of the box.