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

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

Good call.

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?

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.

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!

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

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)

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!

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?

We could do it, but examples are not currently in docs.rs and it seems a bit weird placing them there, no?

I think the best place for examples is the book, but other alternatives could be also good.

We could do it, but examples are not currently in docs.rs and it seems a bit weird placing them there, no?

The upshot is that it lets us use Rustdoc scraped examples to link these examples from the functions that use them.

Really interesting, I didn't know that. But this feature is not stable, could it be used in the official docs.rs documentation just publishing the crate as usual?

I was planning to pin a specific nightly, so that we wouldn't have to worry about future changes breaking our docs without us doing anything.

If you really want to stick to using docs.rs as the main rustdoc host, then I'll move the examples into mdBook. Here's a new commit that includes the examples into mdBook instead of using rustdoc.

I think that it is better to use docs.rs for a more standard use of docs, we can use scraped examples when that feature become stable.

I think the last commits make this pull request perfect, thanks!

I will wait a bit to merge it in case someone else has any comments.

@Martin1887 @notriddle

The deploy job seems to need fix: https://github.com/pulldown-cmark/pulldown-cmark/actions/workflows/pages/pages-build-deployment

  Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/style.scss':
                    No such file or directory @ dir_chdir - /github/workspace/docs

The workflow seems to be using very old versions of actions/upload-pages-artifact and actions/deploy-pages. I would suggest updating those to the latest.

I confirmed it was fixed after updating the actions. I created a PR #920.

What's the status of this? https://pulldown-cmark.github.io/pulldown-cmark is currently giving 404.

What would be involved in changing the URL to https://pulldown-cmark.github.io/? I guess there needs to be a repo pulldown-cmark/pulldown-cmark.github.io in the org and then some (??) adjustments to the Actions workflow to get it deployed there.

I tried pushing to test-deploy. It says this:

Error: Failed to create deployment (status: 404) with build version [..]. Request ID [..] Ensure GitHub Pages has been enabled: https://github.com/pulldown-cmark/pulldown-cmark/settings/pages

It is a bit weird, it was already configured but maybe it got reset after changing the version of the deployment module.

It is working again now. Thanks for reporting it.

The release deployment is giving this error:

Tag "v0.12.0" is not allowed to deploy to github-pages due to environment protection rules.

which is apparently related to https://github.blog/changelog/2023-10-06-actions-secure-deployment-rollouts-to-protected-environments-based-on-select-tag-patterns/

The thing is that a new tag should not trigger a book deploy I think, but I don't see why it is triggered.

https://pulldown-cmark.github.io/pulldown-cmark/ looks working fine to me. What is the problem being discussed here?

Okay, I understood that the latest release didn't deploy the book properly. https://github.com/pulldown-cmark/pulldown-cmark/actions/workflows/book.yml

The thing is that a new tag should not trigger a book deploy I think, but I don't see why it is triggered.

Yes, it is triggered on release event, not tag or branch creation.

Since I don't have the permission, I can't ensure but I guess the setting on this repository is not correct. The steps are:

1. Go to 'Settings' tab
2. Select 'Environments' item in the menu
3. Find 'Deployment branches and tags' section
4. Click 'Add deployment branch or tag rule' link
5. Select 'Ref type: Tag' in the pulldown menu
6. Add a pattern matching to any release tags

I had only set test-deploy and gh-pages branches, a pattern for all v* tags is already set.

Hmm, v* should matches to v0.12.0 🤔

I'm not sure, but this discussion may be related to this issue: https://github.com/orgs/community/discussions/39054

We deploy the page on release event. And the event is raised on the default branch (if my understanding is correct). How about adding master to the allowed branches?

It works (I have just re-executed the last job), the problem was the v* tags were not allowed when the releases were created.