Skip to content

Implementation for --no-code-tag-removal flag - #154

Open
jofas wants to merge 2 commits into
ekalinin:masterfrom
jofas:no-code-tag-removal
Open

jofas wants to merge 2 commits into
ekalinin:masterfrom
jofas:no-code-tag-removal

Conversation

@jofas

@jofas jofas commented Aug 4, 2024

Copy link
Copy Markdown
Contributor

Fixes #153.

@jofas jofas changed the title Implementation for #153 --no-code-tag-removal flag Implementation for --no-code-tag-removal flag Aug 4, 2024

@ekalinin ekalinin left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR. A few things need to be fixed before it can be merged:

  1. Conflicts with master. Since this PR, --depth (#174) and --numbered (#177) took the same argument slots: $8/$9 in gh_toc and $3/$4 in gh_toc_grab. Please rebase onto current master and move the flag to the next free slots. Watch out for local no_code_tag_removal=$3 in gh_toc_grab: it merges without a conflict, and since tags are only removed when the value is exactly "no", master's depth=0 there turns backticks on for everyone. Checking for "yes" instead would keep the default safe. Also, the blank line added in tests.bats conflicts with the "TOC for remote README.md" test, which is re-enabled on master, so please keep master's side there.
  2. The flag doesn't work with stdin. It's parsed after the - branch returns, so gh-md-toc - --no-code-tag-removal silently strips the backticks, and gh-md-toc --no-code-tag-removal - treats - as a file name (it prints the file header and footer and rm: illegal option -- ~). Parsing it together with --indent/--depth/--numbered, before the - check, would fix it. Please add a stdin test too.
  3. HTML entities end up inside the backticks. GitHub renders `a<b>` as <code>a&lt;b&gt;</code>, so the entry becomes [The `a&lt;b&gt;` case]. Entities aren't decoded inside code spans, so GitHub shows a&lt;b&gt; literally, while without the flag the same heading displays correctly. The entities need to be decoded when converting to backticks.
  4. Code that contains backticks breaks. Every <code> becomes a single backtick, so ``foo `bar` baz`` turns into `foo `bar` baz`, which is two code spans with a bare bar between them. The fence has to be longer than the longest run of backticks inside the code.

@jofas

jofas commented Oct 15, 2026

Copy link
Copy Markdown
Contributor Author

The entities need to be decoded when converting to backticks.

Do you have a proposal for how to implement this? The list of entities is huge and implementing this ourselves would be unfeasible. There are options available, but I'm not sure if adding a dependency for this is something you are willing to do / if you are, what dependency to choose.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] --no-code-tag-removal flag allowing to make removal of backticks in TOC entries optional

2 participants