Add guide book and deploy script for it

[notriddle]

Fixes #863

You can see what it looks like at https://notriddle.github.io/pulldown-cmark/.

The final version would probably be at https://pulldown-cmark.github.io.

To make this work, you need to change the branch restrictions on deploying to github pages:

The action will then push a new version of the page whenever a release is made, or whenever a push is made to test-deploy.

[Martin1887]

I have to read it, but on a fast look it seems great, thanks!

[ehuss]

You may also want to remove guide/deploy.rs.

[notriddle]

Good call.

[chriskrycho]

First of all, this is a fantastic addition! It would be awesome if shipping this kind of thing just became a normal part of libraries in the Rust community. 💙

Second, content structure suggestion: move the CommonMark spec. My recommendation would be to either put it as an appendix at the end, or remove the content entirely in favor of a link. If someone is just coming to the library for the first time and wants a quick guide, the spec is… quite the second page to get to. 😂 More than that, though, I think for most people, the spec is actually irrelevant, and just linking to the spec (maybe links to both the copy in the repo and the upstream?) would be more than sufficient. Thoughts?

[notriddle]

I think the specifications, in general, are "too much" for ordinary users, but there's still value in having them as an appendix for anyone that wants a more detailed understanding.

So, to make this work better, I've added a cheat sheet section as the new second page, and explicitly reorganized all the detailed specs into their own appendix.

[Martin1887]

I have just read it and I find it really good! The cheat sheet chapter is very useful for new users.

However, I miss an introduction chapter (maybe just importing the README and/or docs.rs main page despite repeating them?) and a chapter to include the examples of the examples directory of the repository.

Also, the Math spec is missing in this book, and it is maybe the most important one, but only because it was not merged yet in the branch in which you are working. It should be in the cheat sheet however, although it makes more sense adding it when the Math spec is integrated in the book.

Thanks!

[notriddle]

It's weird that I click the examples, but the Files browser doesn't include them...

https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc

[notriddle]

Anyway, @Martin1887

I've added an

• introduction chapter (mostly copying the README)
• the Math extension (rebased onto the current branch)
• the example programs and API index of them (using rustdoc scraped examples)

[Martin1887]

Sorry for the delay, I'm been busy this week.

I see perfect the introduction and the introduction of the Math spec, but:

• In the cheat sheet, I think Math mode should not be under GFM features because we use another spec.
• The chapter 2 links seem to redirect to another subdomain, which feels weird and remove the mdBook theme (burning your eyes if you are using a dark theme 😜), could not the examples be transformed to mdBook chapters? For the API docs I think we can create a mini-chapter explaining that the API documentation is in docs.rs and indicating the link, so it is clear it is an external source.

Thanks!

[notriddle]

For the API docs I think we can create a mini-chapter explaining that the API documentation is in docs.rs and indicating the link, so it is clear it is an external source.

If we're going to link to docs.rs for the API docs, could we also link to there for the examples?