Anchors and tapping into the expressiveness of undefined shortcut reference links

1

Hello,

I’d like to ask if there is a syntax more popular than others for anchoring headings that people would recommend ?

GitHub generates the anchors itself based on the heading inline content but that’s no so great for your links’ stability.

Also in light of this proposal for anchors. I thought that a simple scheme for identifying blocks is to use undefined shortcut reference links:

The first shortcut reference link that occurs in a block whose label starts with a # and that is undefined in the document is removed from the text flow and defines the identifier for the block.

So you would have:

# My heading [#heading-id]      | <h1 id="heading-id">My heading </h1>
# My [#heading-id] heading      | <h1 id="heading-id">My  heading</h1>
# [#heading-id] My heading      | <h1 id="heading-id"> My heading</h1>
                                |
This is an [#pid] important     | <p id="pid">This is an  important 
paragraph it deserves an        | paragraph it deserves an
[#notanid] an id.               | [#notanid] an id.</p>

But I wonder what all the people here much more versed in that than me would think of that.

In fact this came to me while thinking about (ab)using markdown as a templating system. By using the luckily very unconstrained label of undefined shortcut reference links as a DSL to bind data (e.g. [article.name], [article.date|yyyy-mm-dd]) and/or invoke other template fragment.

For that usage the spec doesn’t have to say anything about this, it’s a matter of allowing your parser API to do fancy stuff on unknown link resolution. But I wonder is anyone aware of such a markdown template based system ? No CMS or website generation system I had to surrender to ever had markdown as the templating system itself. But I’m a bit toying with that idea now.

1 Like
2

Pandoc uses

# My heading {#heading-id}

In fact you can specify arbitrary attributes this way:

# My heading {.class #ident key="value"}

But I’ve come to prefer the idea of allowing attributes to be assigned to arbitrary block-level items by putting them on the line before:

{#heading-id}
# My heading

{#para-id}
My paragraph

{#code-id caption="foobar"}
```
code
```

Similarly, attributes may be added to arbitrary inline-level items by putting them immediately after:

![image](my.jpg){#image-id}

mot{lang="fr}

That makes everything uniform and predictable. This is already implemented as an extension to pandoc’s commonmark parser:

pandoc -f commonmark+attributes
3 Likes
3

Thanks ! Certainly nicer than my abuse of shortcut reference links which was semantically dubious for defining anchors :–)

In terms of block level semantics would it be accurate to say that it has the semantics of a blank line and simply pushes the given attributes in the next block ?

4

In terms of block level semantics would it be accurate to say that it has the semantics of a blank line and simply pushes the given attributes in the next block ?

Correct. Indeed, you can have several lines of attributes, and
they all combine:

{#id}
{.class key=value}
> blockquote
3 Likes