Confused by why remark-directives converts ':bar' in 'foo:bar'

[ExpHP]

See :ref[anm:rgbTime] for more details.

This gets parsed by remark-directives into

{
    "type":"textDirective",
    "name":"ref",
    "attributes":{},
    "children":[
        {
            "type":"text",
            "value":"anm"
        },
        {
            "type":"textDirective",
            "name":"rgbTime",
            "attributes": {},
            "children": []
        }
    ]
}

essentially treating :rgbTime as a directive, when I was hoping to get anm:rgbTime as a single text node. And as far as I can tell there's no way to configure this?

Apart from being annoying, it's not clear to me why this is even parsed this way to begin with. The language describing text directives in the proposal is vague and could be interpreted a number of ways, but the description for leaf directives makes a pretty clear distinction (emphasis added)

But as opposed to inline directives, there are two colons now, the brackets [] are optional as well, and spaces may be interspersed for readability.

Additionally, I find it fairly amusing that the latest commit to mdast-util-directive was related to changes to make :emoji: work, which further suggests to me that the syntax :bar lacks enough specificity and is too easily triggered by accident. (Kingdom Hearts Re:coded, anyone?)

[ChristianMurphy]

essentially treating :rgbTime as a directive, when I was hoping to get anm:rgbTime as a single text node.

An escape character can be used to ensure it is parsed as plain text

See :ref[anm\:rgbTime] for more details.

https://astexplorer.net/#/gist/29b7c8301b71d62fb63bd1d7438ebc1a/bd7bbdef62dc9e1ec50eca91086e1e3556ccbacd

[ExpHP]

So it is at least possible to escape this. That much is good.

Unfortunately, I don't think there is any way that I can automatically change all 453 currently existing instances of this syntax in my markdown snippets, as some of them are in locations like string template literals that would require a different number of backslashes to correctly escape the colon...

[ExpHP]

Okay. I added a preprocessing step that operates on the string before it is sent to the markdown parser, replacing the first : after :ref[ with \:.

Hmmm. Or maybe I should do this in a remark plugin that runs before remark-directive, so that I can have it only modify text nodes and not code/inline-code where the \ would be literal...

[wooorm]

The proposal is clear about [content] and {attributes} being optional in all cases.

In your case, it looks like you want an identifier in square brackets. The content slot is for nested markdown, similar to how there is markdown in [*here*](/url). Perhaps using an ID attribute is a better solution for your use case:

See :ref{#anm-rgbTime} for more details.