Internal references (anchors) with multiple types

Extensions
1

This is to bring the extension discussion from this issue into the CommonMark fold:

The problem:

In a document, you might want to reference locations in the document (anchors) of different types things like images, tables, and equations. The reference might need to be formatted in various ways in the rendered document:

  • numbered with a separate sequence for each type (you would have Fig 1,2,3, Eqn 1,2,3, etc).
  • text associated with some link types.
  • reference with no text to be converted according to template rules, e.g. text-less link becomes “Eqn.1”.

This would also provide a generic anchor syntax. It is particularly important for writing academic documents.

The gist of the solution:

A syntax extension where you can define a reference anchor location with a given type and a way to reference that anchor, which a parser could choose to format accordingly.

Suggested syntax:

Reference/Anchor definition

![Optional link text](optional url){anchortype:anchorname}

Link to Reference:

[Optional reference text](#anchortype:anchorname)

Examples:

Generic anchor reference

![This is an internal anchor](){someanchor}
[link to that anchor](#someanchor)

Figure/Image
![A voyage to the moon](moon.jpg){fig:themoon}
[This figure](#fig:themoon)

-> the template decides whether to render the text or to use e.g. Fig.1

Equation - only want an anchor with no text, so empty brackets are allowed
![](){eqn:firsttheorem}
[](#eqn:firsttheorem)

-> could render link as Eqn.1

2

This conflicts with the syntax proposed in Consistent attribute syntax.

3

This appears to be better off as a generic extension http://talk.commonmark.org/t/generic-directives-plugins-syntax

@name[content](arg){#myId .myClass key=val key2="val 2"}

@@@name[content](arg){#myId .myClass key=val key2="val 2"}
      \*Content to pass to extension*\
@@@

For consistency, with http://talk.commonmark.org/t/consistent-attribute-syntax . Note that we refer to id based anchors in {} as {#id} not {id}

!mediaType[description](url){#myId .myClass key=val key2="val 2"}
  • assumed to be image if mediaType left blank

So therefore:

 Singular figure:
 @figure[ ![A voyage to the moon](moon.jpg) ]{ #themoon }
 
 Block figure:
 @@@figure{ #themoon }
    ![A voyage to the moon](moon.jpg)
 @@@

 This links to the figure:
 @figure( #themoon )

Where @figure( #themoon ) prints out the current figure name/number .

Or if we are adopting multiple levels of specification Optional syntax

We could use your suggested syntax (fixed for consistancy with other threads)

![A voyage to the moon](moon.jpg){#fig:themoon}
[This figure](#fig:themoon)

But make it part of CommonMark Scholar Extension

BTW: Do you know that HTML now supports a figure tag & figure caption tag?

http://www.w3schools.com/tags/tag_figure.asp
http://www.w3schools.com/tags/tag_figcaption.asp

1 Like
5

Sounds reasonable, would empty braces be accepted - So an item with no description or argument would be:

@equation[]()(#equation_label)

And the link:

@equation(#equation_label)

Note that I focus on equation because it’s a little different from figure and table, since it would generally be a tag next to an equation block (defined in latex between $$ … $$ or similar) rather than part of the block itself, and not usually have any associated text.

Did not know html supported fig and caption, though I my case I compile markdown to PDF via LaTeX so not much focused on html side