In the GFM spec, it is said that:
This document is generated from a text file,
spec.txt
, written in Markdown with a small extension for the side-by-side tests. The scripttools/makespec.py
can be used to convertspec.txt
into HTML or CommonMark (which can then be converted into other formats).
I was unable to find a public repository containing these files, but spec.txt
can be found under the same web
directory as the spec itself. This is not my main question, but I would be happy if someone could point out a repository where these files are officially maintained.
According to the above quote, I assume that all code in spec.txt
, aside from the code dedicated to side-by-side tests, is legitimate GFM.
In spec.txt
, there is the following code:
## Characters and lines
Any sequence of [characters] is a valid CommonMark
document.
A [character](@) is a Unicode code point. Although some
code points (for example, combining accents) do not correspond to
characters in an intuitive sense, all code points count as characters
for purposes of this spec.
In the rendered spec, the link [characters]
and also the link [character](@)
have been converted to this cross reference link:
https://github.github.com/gfm/#character
Does this syntax implement cross references (aka named anchors) in GFM? There is a popular question about such a feature which suggests that no pure Markdown solution for cross references exists - however, if this (@)
-based syntax is implemented in the parser that parsed spec.txt
, why is it not specified in the spec?
The official repo for the Commonmark spec can be found at commonmark/commonmark-spec (copies of the spec in other repos are copied from here). We can see that the file spec.txt
in that repo also contains the same syntax. Therefore, this is not specific to GFM, but to Commonmark in general (of which GFM is an extension).
As explained in commonmark/commonmark-spec#578 (and possibly other places) regarding the spec.txt
file:
Note: this is NOT a standalone commonmark file. It is in a special format which is designed to be processed using
tools/make_spec.lua
.
In fact, if we look at tools/make_spec.lua in the repo, we see that it is a wrapper script which preprocesses the spec.txt
file before outputing the spec in one of multiple supported formats. Note that one of those output formats is Commonmark. If you run the script with commonmark
as the output format, you will get a Commonmark document with regular Commonmark links in place of the special syntax. In fact, if you feed the spec.txt
file directly to Commonmark (without the preprocessing in tools/make_spec.lua
) you will not get a document with correctly formatted links in return. Therefore, we can conclude that the syntax in question is not Commonmark, but some custom add-on which is only used for authoring the spec. That would explain why it is not specified in the spec.
Unfortunately, I am unable to find any documentation of how the syntax works anywhere. The Readme for the spec briefly mentions the special codeblock syntax used in the spec, but does not touch on internal links.