vscode-markdown
vscode-markdown copied to clipboard
Prefix to section headers
Proposal
I've been going through some of the issues that plague Azure Devops's wiki and the TOC.
As an alternate solution to the issue with Azure devops treating #
If there's already a solution to this, I'm happy to learn.
Example
Example doc with sectioning:
# 1. Introduction
# 2. Details
## 2.1. Details SubText1
## 2.2. Details SubText2
Current output as Github (default) slugs:
- [1. Introduction](#1-introduction)
- [2. Details](#2-details)
- [2.1. Details SubText1](#21-details-subtext1)
- [2.2. Details SubText2](#22-details-subtext2)
This is greats, unfortunately just doesn't render the links correct in azure devops due to the aforementioned #
Current output AzureDevops slugs
- [1. Introduction](#%31%2E%2D%69%6E%74%72%6F%64%75%63%74%69%6F%6E)
- [2. Details](#%32%2E%2D%64%65%74%61%69%6C%73)
- [2.1. Details SubText1](#%32%2E%31%2E%2D%64%65%74%61%69%6C%73%2D%73%75%62%74%65%78%74%31)
- [2.2. Details SubText2](#%32%2E%32%2E%2D%64%65%74%61%69%6C%73%2D%73%75%62%74%65%78%74%32)
While this works, it is practically unreadable, especially when you have to reference the headings again or when you have to fix heading reference due to heading name changes.
Personally, I definitely prefer the github style in favour of maintaining readability. As a workaround/alternative solution. I would like to have section prefix. So when we generate the ADD/Update section headers. It will generate the following instead.
# Section 1. Introduction
# Section 2. Details
## Section 2.1. Details SubText1
## Section 2.2. Details SubText2
Which then generates the TOC like so
- [Section 1. Introduction](#section-1-introduction)
- [Section 2. Details](#section-2-details)
- [Section 2.1. Details SubText1](#section-21-details-subtext1)
- [Section 2.2. Details SubText2](#section-22-details-subtext2)
Outcome Benefits
For my specific use case, it provides the following advantage
- It maintains its readability
- It utterly circumvents azure devops's (provided that your prefix doesn't start with number)
Others may have usages for section header prefixes being auto generated. For example they may be writing requirements doc
# Requirement 1
## Requirement 1.1 fine note 1
## Requirement 1.2 fine note 2
### Requirement 1.2.1 exclusion
When cross referencing documents, it's nice to see these headings presented as such.
Background details
#802 #1383
Thank you
Thanks for reading my request and more importantly the very useful extension to help with markdown writing.