Adds initial ion-1-1 mdbook

[zslayton]

This PR adds an mdbook port of our existing Asciidocs in a new folder called books. If we like the mdbook publishing experience we can eventually add others--cookbooks, a separate home for Macros by example, etc.

Note that this targets gh-pages rather than the ion-11-specification; this is in the hopes that we can incorporate it into our typical CI/CD build logic and have it auto-publish.

To view the rendered content locally, clone this branch and run:

cargo install mdbook
cargo install mdbook-alerts
mdbook serve

When you run mdbook serve it will run a local http server on port 3000 for you to explore the pages.

You can also view the rich diff for each page in GitHub using the button in the upper right of each file:

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[nirosys]

To view locally, I had to provide the book path: mdbook serve books/ion-1-1

[nirosys]

This is awesome. There's a plugin, mdbook-pandoc, if there's a need for auto-building pdfs or other formats too.

[popematt]

We can use this to build both the mdbook and the jekyll site and then publish them together.

[popematt]

Before I attempt to read this file, can you tell me—is this modified from the original in any way?

[popematt]

I double checked, and BSD-3-Clause license does allow redistribution with modifications, so there's no problems there. It would be nice if we could somehow put the Ion-specific changes in a separate file so that we can easily locate and identify what is ours and what is from the original.

[zslayton]

Per offline discussion: this copy of highlight.js includes a language entry for ion, allowing us to customize the syntax highlighting for macros. The current entry is pretty basic, but we can build on it.

I double checked, and BSD-3-Clause license does allow redistribution with modifications, so there's no problems there.

Thanks for confirming this. Copy/paste/edit to override is the customization approach prescribed by mdbook, but it's always good to double check.

It would be nice if we could somehow put the Ion-specific changes in a separate file so that we can easily locate and identify what is ours and what is from the original.

Agreed. Open to ideas here.

[popematt]

FYI—I don't think that any of my comments are necessarily blocking comments.