vscode-markdown icon indicating copy to clipboard operation
vscode-markdown copied to clipboard

Prefix to section headers

Open Yakyyaky opened this issue 2 months ago • 3 comments

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 # as task item. I was hoping that we can have prefixes to Add/Update section header function.

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 # issue.

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.

Yakyyaky avatar May 27 '24 00:05 Yakyyaky