Suggestion: Mode to not start parsing tags before [toc]

[DigitalSorceress]

I'm probably going to see if I can patch this in to my local copy but I though this might be a useful tool for others

I kind of have a standard format I use for my "blog entry" md files that I parse with parsedown / parsedown-extra

I put one and only one level 1 heading in my markdown file which is the title
optioally a level 2 and then a level 3 date

Then and only then does my main article start and what I want to do is have a TOC that ignores any headings that are encountered BEFORE the TOC is placed.. so effectively

# Title (only ever one level1 for all the doc)
## Optional Subtitle
### YYYY Mon DD

[toc]

intro text here yada yada

## sub heading 1
subcontent

### Sub-Sub heading 1 etc
bla bla

### sub-sub heading 2

## subheading 2
bla bla content here

At present [toc] pares out to

- Title
  - optional subtitle
    - date
  - sub heading 1
    - sub sub heading 1
    - sub sub heading 2
  - sub heading 2

I was hoping to kind of tell toc to not start looking for headings until after it sees toc

so it would make aTOC like this

- sub heading 1
  - sub sub heading 1
  - sub sub heading 2
- sub heading 2

Since I am sure not everyone would want this, I guess this would need a config option

[DigitalSorceress]

I managed to hack together something halfway usefu,

I added these two lies in the constants section

const TOC_REACHED_ID = 'top';  
protected $tocReached = false; // set this to true to prevent skipping header items before TOC

then I replaced

$this->setContentsList(array(
                    'text'  => $text,
                    'id'    => $id,
                    'level' => $level
                ));

or rather wrapped it i guess with

          // We are NOT adding unless the "top" has been reached
            if ($this->tocReached ) {
             // Add/stores the heading element info to the ToC list
             $this->setContentsList(array(
                    'text'  => $text,
                    'id'    => $id,
                    'level' => $level
                ));
            } elseif ($id == self::TOC_REACHED_ID)
            {
                $this->tocReached = true;
            }

Finally, in my markdown file when I define the [toc] I give a heading the ID {#top}

# Title
### YYYY Mon DD

## CONTENTS   {#top}
[toc]

My hack is working well enough for my needs - I can disable it by setting $this->tocReached = true up in the config section.

[KEINOS]

I love your idea. I think the treatment of [toc], including #22, will bring freedom of usage.

Let me refactor the repository first to facilitate contributions and enhancements.

[DigitalSorceress]

I love your idea. I think the treatment of [toc], including #22, will bring freedom of usage.

Let me refactor the repository first to facilitate contributions and enhancements.

Thank you - I REALLY love the toc feature, and I just needed these tweaks to make it perfect for me

Feel free to use any of my suggested here or riff on it as you wish. (MIT license :) )

I made a few changes in my own version - used a "setter" to do the configuration (removing my constant) so that folks don't need to edit the code to use...

Swapped my constant with something I oculd update

protected $tocTopId = 'toctop';  
protected $tocReached = false; // set this to true to prevent skipping header items before TOC

added a setters section

    /**
     * ------------------------------------------------------------------------
     * SETTERS (custom config Parameters)
     * ------------------------------------------------------------------------
     */
    
    /**
     * ## When enabled, you can have the TOC Skip heading blocks that appear at 
     * above a preset {#tagId}
     * - Defaults work as the original ParsedownTocExtension works (all headings
     * from the beginning of the file are included)
     * - default tag is {#toctop} you can override by setting optional tagid
     * - set tagid to a string with no spaces and without the #
     * @param bool $enabled - default: false
     * @param string $customIdForTocStart - default: 'toctop'
     * @return void
     */
    function setDelayedToc($enabled, $customIdForTocStart = 'toctop')
    {
        $this->tocReached = !$enabled;
        $this->tocTopId = $customIdForTocStart;
    }

Finally down in the blockHeader override

// We are NOT adding unless the "frontmatter" is concluded
if ($this->tocReached ) {
    // Add/stores the heading element info to the ToC list
    $this->setContentsList(array(
        'text'  => $text,
        'id'    => $id,
        'level' => $level
    ));
} elseif ($id == $this->tocTopId) {
    //// NOTE we need to test this after the content list
    //// So that we don't start including till after that first h3
    $this->tocReached = true;
}

this allows me to configure it

$Parsedown= new ParsedownToc();

// This enables my custom delayed TOC feature
// $Parsedown->setDelayedToc(true);
$Parsedown->setDelayedToc(true, 'customTopIdIfIWish');

// ... rest of my code using it here

# Main Title
### YYYY mon dd

## CONTENTS {#customTopIdIfIWish}
[toc]

## Thing1

## Thing2

[KEINOS]

I am almost done with the refactoring of the repo!

Now I am working to re-create the tests. Which currently are redundant and not easy to add new ones.

I am still focusing to ease implement the feature of this issue. And, your forked-repo helped me a lot to imagine what direction we have to aim. Thank you!

[KEINOS]

I'm getting far-sighted, sorry if I miss aim here and there.

[DigitalSorceress]

KEINOS,

Thank you for your patched versions of Parsedown and PasedownExtra - I was running into those deprecations and manually fixing them (I'm testing on PHP 8.5 and ran into a few)

I noticed you've seriously refactored the code.

I'm going to poke at my extension to your extension to see if I need to make changes to keep the features I wanted.

I get far sight - you're doing this for free / out of the kindness of your heart - I'm in no rush:)