@jugglinmike if an update like this would break the docs, would we know without doing a lot of manual work?

@foolip We know that the build process exits successfully thanks to the GitHub Action which ran for this patch. It reported:

build succeeded.

The HTML pages are in _build/html.

Whether or not the resulting website is still acceptable is harder to say, but maybe not by that much. By building locally, one could compare the contents of the _build/html directory for both versions of recommonmark. There are many kinds of changes that would be acceptable but produce quite a lot of noise in the diff, but there's nothing in the release notes to suggest this will be the case.

That is pretty much what I suspected, a lot of manual work could reveal problems. Building regression testing is tricky if the output often change in ways that don't matter to users.

So... I guess we just merge and hope.

@foolip Now that we've merged this, we can review the precise changes to the built contents by taking a look at the commit history of the gh-pages branch, specifically commit 393028a

As we could expect from the aforementioned change log, images now have "alt" text. That's definitely an improvement and likely more in line with what people expect when using the corresponding Markdown syntax. The descriptions are now missing from the body of the guides, though, and I'm not sure if that might actually make it harder for people to use without assistive technology.

In any case, I've opened gh-19952 as a way to surface this information during the review process.

Thanks Mike!