Open colin-bitterfield opened 4 years ago
@colin-bitterfield, there very few settings controlling how the heading id is genereated.
These are in Parser settings:
I duplicated the way GitHub does it by trial and error.
I added the extra settings as compatibility issues came up.
To generate the id, GitHub normally replaces non-letter characters with -
. Letter characters are lowercased.
The no duplicated dashes replaces multiple contiguous dashes by one dash. Some markdown processors do that.
The other is for non-ascii text. GitHub does not lowercase these when generating Ids. I think GitLab does.
Your question prompted me to test your exact case and I found that GitHub does not trim trailing spaces from Reference Link, while the plugin does trim the trailing spaces for ID generation. It is expected since the leading spaces are trimmed whether the text is explicit or implicit from the ref id, even by GitHub. So I suspect this is a GitHub bug, but I will have to add another option to make the plugin GitHub compatible.
## 2.0. References [ There is a {} reference showing but is not copy-able ]
## 2.0. References [ There is a {} reference showing but is not copy-able ]
## 2.0. References [ There is a {} reference showing but is not copy-able ][ There is a {} reference showing but is not copy-able ]
## 2.0. References [ There is a {} reference showing but is not copy-able ][ There is a {} reference showing but is not copy-able ]
[There is a {} reference showing but is not copy-able]: https://www.example.com/0
[ There is a {} reference showing but is not copy-able ]: https://www.example.com/1
[ There is a {} reference showing but is not copy-able ]: https://www.example.com/2
On GitHub all headings reference links resolve to https://www.example.com/0
so to me it made sense to trim the id when computing the heading id, also from the reference link text. However, the ids for the heading have trailing -
added for each trailing space.
The workaround is to not have trailing spaces in Reference Link ID or text
@colin-bitterfield, I forgot to mention that you can completions for anchor refs in links to have the plugin fill it in automatically.
You can also turn on a setting in Editor settings to show the heading ID in the editor after the heading to allow you to "debug" the ids:
@colin-bitterfield, I found more discrepancies with GitHub, mainly if an emoji shortcut is included in the heading. ## Heading :+1:
, GitHub includes the shortcut text as part of heading text used to generate the id.
I am addressing this and will release an EAP version with the fixes.
@colin-bitterfield, EAP update Version 3.0.201.81 with a fix for the issue is available.
Please note the change that EAP channel is for JetBrains licensed plugin and Legacy EAP is for legacy licensing by vladsch.com
I installed the latest EAP version.
The issue is some of our team members are using VS Code which adds these HTML type Achors.
1.1. Purpose — Idea does this. (Works fine)
How do I get the HTML based anchor to generate about the TOC (based on settings i.e. level 2 & 3 )
@colin-bitterfield,
The plugin does not need the a
tag and will do anchor ref completion and TOC based references on the automatically generated id based on the heading text. The plugin will also update any anchors which reference a heading if you use Rename Refactoring
on the heading text instead of just editing it.
There is no option to create a
tags in Markdown. These are added automatically to the the generated HTML when Parser option Anchor links
is enabled (it is by default).
The heading above generates the following HTML:
<h3><a href="#11-purpose" id="11-purpose">1.1. Purpose</a></h3>
Optionally, the plugin will recognize a
tags with id
or name
attribute defined, and will use it for anchor ref completions. To enable a
tag id
processing, enable the Inline HTML 'a' tag id attribute
in Parser settings.
ℹ️ a
tag extension only supports one of id
or name
attribute per tag, and prioritizes id
over name
if both are provided because name
is obsolete since HTML5.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
name
Obsolete since HTML5
Was required to define a possible target location in a page. In HTML 4.01,id
andname
could both be used on<a>
, as long as they had identical values.Note: Use the global attribute id instead.
a
tag needed for some reason by VS Code?What is the final Markdown processor used on these files?
The plugin has an Attributes
extension which can add arbitrary attributes to an element which will be used in the HTML. This can also be used to hard-wire the heading id which will then be used by completions and TOC.
The syntax is {attrName="attrValue" }
with double quotes optional if attrValue does not have spaces. You also have shortcuts for id
: #idValue
, and class
: .className
To override heading id using attribute syntax you would use:
This extension is not supported by many processors, including GitHub, GitLab so it will not work if intended markdown processor does not support it.
I need to understand the use case and its moving parts before I can help find a solution.
This is what I was told:
“It was used to provide the links before headers shown on Github.”
We opt’d for turning off the VS Code feature.
v/r
@colin-bitterfield, GitHub adds these automatically so you do not need to do it, as long as you know how GitHub generates the id from heading text.
What setting creates anchors?
like: