Published HTML version of specification is out of date with spec.txt
thewoolleyman opened this issue · 5 comments
The published HTML version of the GFM specification at https://github.github.com/gfm is not up to date with the test/spec.txt source as of https://github.com/github/cmark-gfm/blob/cedbeb7dc8005e54b8bdfe4cf442752b742be3f6/test/spec.txt.
It is at least multiple commits and years (2019) behind at this point.
There are also examples in the HTML version such as https://github.github.com/gfm/#example-493 which do not seem to have ever been part of the spec.txt commit history.
This is the most problematic thing, because the sequential numbers of the examples in the HTML are no longer in sync with the spec.txt, which is a problem when trying to programatically generate links to the canonical HTML examples.
Also, the version numbers for the spec are not being kept in sync - the latest commit didn't bump the version in spec.txt, and the full version from some commits (e.g. cedbeb7) are not reflected in the spec.
If these are "prerelease" versions, and not intended to be published to the HTML version, then this versioning strategy should be clearly documented.
It's also not clear where https://github.github.com/gfm is being hosted or published from - is this a separate open source repo somewhere? If not, can it be?
In any case, it seems like this publishing process should be automated via a pipeline or GitHub Actions, to prevent it from becoming out of date, or, as is the case with https://github.github.com/gfm/#example-493, containing something that was apparently never part of spec.txt. And ideally this process would be open source so it is transparent and can benefit from community support.
CONTEXT: I'm finding these inconsistencies as part of GitLab's work on our own GitLab Flavored Markdown Specification, which is an extension of GitHub Flavored Markdown. See these links for more context:
- https://docs.gitlab.com/ee/user/markdown.html
- https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide
Thanks!
@thewoolleyman thank you for taking the documentation seriously with Gitlab Flavored Markdown. 💯
Based on #271, it sounds like https://github.com/github/gfm may contain the spec.txt used to generate the current HTML. If somebody from GitHub could confirm that and copy it into this repo I think that would at least address the current mismatch.
I've stumbled upon outdated-ness of the GitHub's spec at https://github.github.com/gfm (at the time of writing – Version 0.29-gfm (2019-04-06)) because I couldn't find documentation of footnote syntax, which was added in September 2021.
@kevinbackhouse @anticomputer, as apparent maintainers tagging you for a quick FYI, and hoping for at least a response.