Add mdbook for chapters

[arthmis]

Thanks for writing about ImmutableData. It's helped me learn a lot more about Redux and its motivations, which I use for work. I created an mdbook for the chapters. Would you be open to adding that to this repo or linking to the book? The main reason I wanted to add it, was the rendered markdown on github had line lengths that were too long for me. Reading it is fine but I prefer the length used by mdbook. One other advantage is mdbook provides search.

I've hosted the book here if you want to take a look.

[vanvoorden]

Wow! I'll take a look. Thanks!

I have no experience with mdbook… was it difficult to get started with that? We sort of talked about maybe using a solution like docusaurus at some point in the future. How do you think mdbook compares to docusaurus?

[arthmis]

I haven't used docusaurus before so I can't provide a comparison. Looking at this comparison provided by docusaurus https://docusaurus.io/docs/#comparison-with-other-tools, these documentation tools, including docusaurus, appear to be a lot more powerful and featureful than mdbook. They build full fledged documentation websites. I chose mdbook because it's simple and works as only a book, and most importantly, aligned with how you wrote the book—needing to read from beginning to end—and required minimal changes to the structure documents.

I forgot to link the fork which can be found here. The changes weren't huge. I moved the Assets folder into the Chapters folder so that that the images can be linked correctly. I had to add an extension to support rendering mermaid diagrams and that was enough to render similarly to the github markdown.

Getting started wasn't bad, here are the docs for mdbook which uses itself to build its docs. You can either download the binary from github releases or, if you have rust and cargo, you can install and compile it with cargo install.

SUMMARY.md, found in the Chapters folder, tells mdbook the structure of the documents and the names you want to use for each chapter. book.toml, at the root, provides configuration options for where the source files and other metadata, like author and book title.

[vanvoorden]

@arthmis Ahh… interesting!

One thing I noticed from looking at the rendered output is that the footnote web links are no longer detected as links that can be clicked in my browser. The GH reader prints the links as links that can be clicked. Is there something about the markdown source itself that should be improved or is there an option to support that from mdbook?

[arthmis]

Ah, it seems with mdbook you need to add < > brackets around a bare url. The docs state that here. I don't think there is anything wrong with the markdown source. Github's markdown flavor is a superset of the CommonMark spec (which mdbook uses). Mdbook does have some extensions built in which are in the page I linked earlier.

Edit: I've fixed the links in the footnotes.

[vanvoorden]

I think as of right this moment I'm not sure if there is any one specific choice for deploying the "raw" book contents that we must choose at the level of this specific repo. I could see how some engineers might prefer reading the book contents from docusaurus. Some other engineers might prefer swift-docc. And here we see mdbook which also looks like a good choice. I'm not sure I have a ton of context right now to decide which choice needs to ship at the level of this repo.

But I would be happy to add a header link in our readme forwarding your mdbook. And if more engineers come forward with alternatives we can also link those.

What I think would be very interesting would be to find out how possible it is for this raw book to serve as the "backing store" that can then be used to build across all these different choices. So my question then is do these raw chapters make it easy for an engineer that wants docusaurus to then build docusaurus? Can an engineer that wants swift-docc build swift-docc? And what did your experience building mdbook teach us about anything we can do better at the level of this repo to build the markdown in a way we could potentially support as many new platforms as possible?

This repo "implicitly" chooses GitHub markdown as our "platform". This drives our choice of syntax and the specific flavor of markdown we choose. But if there's something we can do in this repo that enables engineers to then deploy those chapters across solutions like mdbook then I would like to have both: optimizing for the raw experience here in GitHub markdown and optimizing for the ability to pick another solution for displaying and rendering.

One example might be places where I used GitHub flavored markdown as a "shortcut" when stricter canonical markdown might take more time to write but also supports more markdown flavors.

Edit: I've fixed the links in the footnotes.

Ahh… Wow! Would you have any availability to submit that commit in its own diff to merge back into main? If I confirm that the angle brackets do not break the existing GitHub markdown then this looks like an impactful change we can merge in for all readers. Thanks!

[arthmis]

I think as of right this moment I'm not sure if there is any one specific choice for deploying the "raw" book contents that we must choose at the level of this specific repo. I could see how some engineers might prefer reading the book contents from docusaurus. Some other engineers might prefer swift-docc. And here we see mdbook which also looks like a good choice. I'm not sure I have a ton of context right now to decide which choice needs to ship at the level of this repo.

But I would be happy to add a header link in our readme forwarding your mdbook. And if more engineers come forward with alternatives we can also link those.

Yeah that's fair. Having the mdbook book linked would be enough anyways. I just wanted a slightly more pleasant way to read it. I'll try and keep up with updates to the book. I can update the name used for the author's section for the book in the repo(this doesn't get displayed on the website, just in the git repo), if you want. I have it set to ImmutableData at the moment.

What I think would be very interesting would be to find out how possible it is for this raw book to serve as the "backing store" that can then be used to build across all these different choices. So my question then is do these raw chapters make it easy for an engineer that wants docusaurus to then build docusaurus? Can an engineer that wants swift-docc build swift-docc? And what did your experience building mdbook teach us about anything we can do better at the level of this repo to build the markdown in a way we could potentially support as many new platforms as possible?

This repo "implicitly" chooses GitHub markdown as our "platform". This drives our choice of syntax and the specific flavor of markdown we choose. But if there's something we can do in this repo that enables engineers to then deploy those chapters across solutions like mdbook then I would like to have both: optimizing for the raw experience here in GitHub markdown and optimizing for the ability to pick another solution for displaying and rendering.

One example might be places where I used GitHub flavored markdown as a "shortcut" when stricter canonical markdown might take more time to write but also supports more markdown flavors.

From my shallow look at docusaurus and swift-docc it might be possible, if you restrict yourself to the commonmark spec, to be compatible with each. They all use their own dialect, docusaurus uses mdx and swift-docc uses its own custom dialect. Going all in on swift-docc might be worth it. It has an option to create an interactive tutorial which could work well for the example apps, though it would be a lot of work.

Ahh… Wow! Would you have any availability to submit that commit in its own diff to merge back into main? If I confirm that the angle brackets do not break the existing GitHub markdown then this looks like an impactful change we can merge in for all readers. Thanks!

I've just put out a PR for the change.

[vanvoorden]

@arthmis I added a link to the mdbook from our README. Thanks!