Fix HTML comments bug - ignore headings inside HTML comments for TOC generation

[Copilot]

Fixes derlin#75 - Headings inside HTML comments were incorrectly being included in the Table of Contents.

Problem

When using HTML comments to temporarily hide sections or placeholder headings, BitDownToc was still extracting and including these headings in the generated TOC. For example:

# Example

[TOC]

## Section A

<!--
### Placeholder SubSection
-->

## Section B

Would generate a TOC containing the commented-out "Placeholder SubSection":

- [Section A](#section-a)
  - [Placeholder SubSection](#placeholder-subsection)  ← Should not appear
- [Section B](#section-b)

Solution

Implemented HTML comment detection and consumption logic similar to the existing code block handling:

• HTML Comment Detection: Added functions to identify HTML comments while excluding BitDownToc's own comments (which contain "TOC")
• Content Skipping: When processing lines for TOC generation, headings inside HTML comments are now ignored
• Content Preservation: HTML comments remain in the output - only their headings are excluded from TOC generation

Result

The same example now correctly generates:

- [Section A](#section-a)
- [Section B](#section-b)

Testing

• ✅ Multi-line HTML comments with headings
• ✅ Single-line HTML comments with headings
• ✅ Multiple headings within HTML comments
• ✅ BitDownToc comments continue to work normally
• ✅ All existing tests pass - no regressions

The fix follows the existing patterns used for code block handling and maintains backward compatibility while solving the reported issue.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• accounts.google.com
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=3659 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-82260745 --subproc-heap-profiling --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,9052427062256519235,14670934298629306201,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
  • Triggering command: /opt/google/chrome/chrome --user-data-dir=/tmp/karma-82260745 --enable-automation --no-default-browser-check --no-first-run --disable-default-apps --disable-popup-blocking --disable-translate --disable-REDACTED-timer-throttling --disable-renderer-REDACTEDing --disable-device-discovery-notifications --headless --disable-gpu --disable-dev-shm-usage --remote-debugging-port=9222 --noerrdialogs --ozone-platform=headless --ozone-override-screen-size=800,600 --use-angle=swiftshader-webgl http://localhost:9876/?id=82260745 (dns block)
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=4451 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-62918409 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,3817772509019066324,2868602956901213577,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
• clients2.google.com
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=3659 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-82260745 --subproc-heap-profiling --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,9052427062256519235,14670934298629306201,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=4451 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-62918409 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,3817772509019066324,2868602956901213577,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
  • Triggering command: /opt/google/chrome/chrome --user-data-dir=/tmp/karma-62918409 --enable-automation --no-default-browser-check --no-first-run --disable-default-apps --disable-popup-blocking --disable-translate --disable-REDACTED-timer-throttling --disable-renderer-REDACTEDing --disable-device-discovery-notifications --headless --disable-gpu --disable-dev-shm-usage --remote-debugging-port=9222 --noerrdialogs --ozone-platform=headless --ozone-override-screen-size=800,600 --use-angle=swiftshader-webgl http://localhost:9876/?id=62918409 (dns block)
• clientservices.googleapis.com
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=3659 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-82260745 --subproc-heap-profiling --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,9052427062256519235,14670934298629306201,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
  • Triggering command: /opt/google/chrome/chrome --user-data-dir=/tmp/karma-82260745 --enable-automation --no-default-browser-check --no-first-run --disable-default-apps --disable-popup-blocking --disable-translate --disable-REDACTED-timer-throttling --disable-renderer-REDACTEDing --disable-device-discovery-notifications --headless --disable-gpu --disable-dev-shm-usage --remote-debugging-port=9222 --noerrdialogs --ozone-platform=headless --ozone-override-screen-size=800,600 --use-angle=swiftshader-webgl http://localhost:9876/?id=82260745 (dns block)
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=4451 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-62918409 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,3817772509019066324,2868602956901213577,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
• redirector.gvt1.com
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=3659 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-82260745 --subproc-heap-profiling --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,9052427062256519235,14670934298629306201,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
  • Triggering command: /opt/google/chrome/chrome --user-data-dir=/tmp/karma-82260745 --enable-automation --no-default-browser-check --no-first-run --disable-default-apps --disable-popup-blocking --disable-translate --disable-REDACTED-timer-throttling --disable-renderer-REDACTEDing --disable-device-discovery-notifications --headless --disable-gpu --disable-dev-shm-usage --remote-debugging-port=9222 --noerrdialogs --ozone-platform=headless --ozone-override-screen-size=800,600 --use-angle=swiftshader-webgl http://localhost:9876/?id=82260745 (dns block)
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=4451 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-62918409 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,3817772509019066324,2868602956901213577,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
• safebrowsingohttpgateway.googleapis.com
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=3659 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-82260745 --subproc-heap-profiling --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,9052427062256519235,14670934298629306201,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
  • Triggering command: /opt/google/chrome/chrome --user-data-dir=/tmp/karma-82260745 --enable-automation --no-default-browser-check --no-first-run --disable-default-apps --disable-popup-blocking --disable-translate --disable-REDACTED-timer-throttling --disable-renderer-REDACTEDing --disable-device-discovery-notifications --headless --disable-gpu --disable-dev-shm-usage --remote-debugging-port=9222 --noerrdialogs --ozone-platform=headless --ozone-override-screen-size=800,600 --use-angle=swiftshader-webgl http://localhost:9876/?id=82260745 (dns block)
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=4451 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-62918409 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,3817772509019066324,2868602956901213577,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
• www.google.com
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=3659 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-82260745 --subproc-heap-profiling --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,9052427062256519235,14670934298629306201,262144 --disable-features=PaintHolding --variations-seed-version (dns block)
  • Triggering command: /opt/google/chrome/chrome --user-data-dir=/tmp/karma-82260745 --enable-automation --no-default-browser-check --no-first-run --disable-default-apps --disable-popup-blocking --disable-translate --disable-REDACTED-timer-throttling --disable-renderer-REDACTEDing --disable-device-discovery-notifications --headless --disable-gpu --disable-dev-shm-usage --remote-debugging-port=9222 --noerrdialogs --ozone-platform=headless --ozone-override-screen-size=800,600 --use-angle=swiftshader-webgl http://localhost:9876/?id=82260745 (dns block)
  • Triggering command: /opt/google/chrome/chrome --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --disable-dev-shm-usage --use-angle=swiftshader-webgl --crashpad-handler-pid=4451 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/karma-62918409 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,3817772509019066324,2868602956901213577,262144 --disable-features=PaintHolding --variations-seed-version (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[0xdevalias]

Superceded by:

• fix: skip headers in HTML comment blocks derlin/bitdowntoc#76