Following on from #2 (Commenting standards), I'd like to propose an alternative comment format that renders natively — no extension required — using standard HTML and GFM footnotes:
...vast and varied. <mark>In my case, puffy eyes are what signal the beginning of the week.</mark>[^comment-1]
[^comment-1]: aaa
lll
How it renders on GitHub today, without any tooling:
<mark> highlights the annotated span in yellow[^comment-1] becomes a superscript link jumping to the note at the bottom- Multi-line comment content works natively via GFM's two-trailing-spaces line break — no
__NEWLINE__ escaping needed
Why this matters
The current :comment[text]{#id text="..."} directive is powerful inside the extension, but:
- Renders as raw noise on GitHub, in standard VS Code preview, and in any other Markdown tool
- Requires
__NEWLINE__ escaping for multi-line comment content — a limitation footnotes solve natively
- Creates vendor lock-in — files are only useful with Markdown Docs installed
Proposed feature
Add an Export to portable format option (or a toggle in Settings) that converts :comment[] directives to <mark> + footnote pairs, so files remain readable and reviewable anywhere. Optionally, support importing <mark> + footnote pairs back into the extension's comment UI.
Trade-offs acknowledged
|
:comment[] |
<mark> + footnote |
| Sidebar/navigation UI |
✅ |
❌ |
| Renders on GitHub |
❌ |
✅ |
| Round-trip editable |
✅ |
Partial |
| Multi-line content |
Escaped (__NEWLINE__) |
✅ Native (trailing ) |
| Unique ID |
✅ |
Manual |
This wouldn't replace the directive format — just give users a way to produce files that are portable beyond the extension.
An example
this is a normal paragraph
Here is a simple footnote1. this is a normal sentence.
this is a normal paragraph
A footnote can also have multiple lines2.
this is a normal paragraph
Following on from #2 (Commenting standards), I'd like to propose an alternative comment format that renders natively — no extension required — using standard HTML and GFM footnotes:
How it renders on GitHub today, without any tooling:
<mark>highlights the annotated span in yellow[^comment-1]becomes a superscript link jumping to the note at the bottom__NEWLINE__escaping neededWhy this matters
The current
:comment[text]{#id text="..."}directive is powerful inside the extension, but:__NEWLINE__escaping for multi-line comment content — a limitation footnotes solve nativelyProposed feature
Add an Export to portable format option (or a toggle in Settings) that converts
:comment[]directives to<mark>+ footnote pairs, so files remain readable and reviewable anywhere. Optionally, support importing<mark>+ footnote pairs back into the extension's comment UI.Trade-offs acknowledged
:comment[]<mark>+ footnote__NEWLINE__)This wouldn't replace the directive format — just give users a way to produce files that are portable beyond the extension.
An example
this is a normal paragraph
Here is a simple footnote1. this is a normal sentence.
this is a normal paragraph
A footnote can also have multiple lines2.
this is a normal paragraph
Footnotes
My reference. ↩
To add line breaks within a footnote, add 2 spaces to the end of a line.
This is a second line. ↩