Need help with in-document link

Spec
1

I am finding the spec’s information about linking impenetrable – at least in the sense of making them work within a document.

I am looking at spec.txt which has “link reference definition” as the destination and numerous references to it like so: “[link reference definition]”. But that isn’t working for me, and the explanations are befuddling me. I need a simple example.
Tell me exactly what to type to accomplish: “I am here” linking to “there”.

Thanks.

2

Hmm…I need to explain more clearly.

In spec.txt I see left bracket then “link reference definition” (without the quotes) then right bracket, then left paren then @ then right paren. That is at the destination, which is a description of link reference definition. Then, in numerous locations I see left bracket, “link reference definition” and right bracket. Those are the links. When I view the spec online those links work fine. But when I copy those exact same things into dingus and generate html, and then copy that html fragment into an html skeleton that is lacking a just the body, it doesn’t work (and the html doesn’t look like it would work).

So, do I need to have a javascript enabled skeleton html file?
Or what.

I am also a little confused about the table of contents in the online spec which is not present in spec.txt, so where does that come from? Is the online spec html generated from spec.txt?

Thanks.

3

[foo](@) is a special convention used only within spec.txt (hence not spec.md) which is handled by a script that is run in addition to the normal parser.

Vanilla Markdown and Commonmark do not contain syntax for explicit link targets nor something that would map to the HTML <dfn> element type. Parsers may add implied targets, and many do for headings in particular.

A link reference definition looks like any of the following lines:

[label]: target
[label]: <target>
[label]: target "title" 
[label]: <target> "title" 
[label]: target 'title' 
[label]: <target> 'title'
[label]: target (title) 
[label]: <target> (title)

where target is a web address (URL) and it is used (i.e. referenced) like any of this:

[text][label]
[label][] 
[label]

It has been suggested that empty link reference definitions could be used as manually specified anchors:

[label]:
1 Like
4

@markus,

Just in case you find Crissov’s answer also “impenetrable” (with much respect @Crissov :slight_smile:), allow me to translate:

  • don’t look at spec.txt. It is not meant for end users. It is source code for generating the CommonMark spec page as well as for compliance tests. The spec page itself can be impenetrable; See my closing comment below.

  • Markdown simply provides a way to include a hypertext link in your text to a URI. It does not provide a way to define URIs, though you may use the ability to embed HTML, which does provide a way to define anchors, which is how you define URIs to specific locations in a pag, or you may use a Markdown tool which automatically creates HTML anchors, though they usually only do so for headers.

    In short, to answer your question:

    There is no standard way to do this in Markdown. I agree there should be, but there is not. As you can see from this web search, it’s an often asked question and there are so many different answers.

  • I think you misunderstand what a “Link Reference Definition” is. It is not a way to define a URI target. It is simply an optional way to insert links in your text without cluttering it with ugly and often long URIs. It allows you, for example, to put all your URIs at the end of the document, almost like footnotes.

The CommonMark spec is often impenetrable because it is written for people writing parsers (the software to interpret Markdown/CommonMark). A better layman’s description of links and reference links can be found in the original Markdown explanation of links.

Hope this helps.

1 Like
5

@vas and @Crissov – thank you.

I am writing documentation. Slowly. Taking about a month
to generate 1000+ lines because I am forcing myself to
test my assertions and claims :slight_smile: I decided to upgrade from
straight .txt so this will help a great deal. I considered writing
html but I think this will be a good choice. In theory I can
at some point generate html pages from the .md text files.
In the meantime I will add inline html for in-page links, primarily
for table of contents. And I will use Github to view the
documents because that is rather painless.

I appreciate your efforts to inform me.

1 Like