Generating markdown table of contents?

[Craig Heilman]

I see that there are various methods of generating a markdown table of contents (TOC) in markdown-specific editors or via plugins/scripts.

For example, if I include <!—TOC—> in my doc.md file, then open it in Marked 2, Marked 2 will generate and display a table of contents at the top of the document. Looking at the html generated by Marked 2 shows that it’s doing something fancy in that it’s adding ids to each heading (e.g., <h2 id="documents">Documents</h2>) and then has some magic (to me) at the top (<div class="mkrelocated-toc"></div>) to show the TOC.

What I’m really looking for is something (probably a script?) that I can run while editing the .md file in bbedit to generate the TOC directly in the .md file. I’m guessing that having the TOC update itself automatically is asking way too much but I’d be happy just being able to delete an old TOC and regenerate a new one manually.

Any suggestions?

Thanks,

Craig

--

Craig Heilman

Bugaboo Software

[jj]

Hi Craig,

Pandoc might help you if it is installed on your system.

Otherwise you can install it from the terminal with homebrew:

    % brew install pandoc


Configure a custom markdown processor in menu BBEdit > Preferences > BBEdit Language Preferences > Language-specific settings > Markdown > Markdown.

Once Pandoc and BBEdit are configured, the menu Markup > Preview in ... commands should generate a TOC at the start of the HTML.

HTH

Jean Jourdain

[Greg Raven]

Jean's idea looks pretty easy. I was wondering if you couldn't configure something using TOCjs?

[Craig Maynard]

The Jekyll gem uses a markdown processor called kramdown. When I want a table of contents, I add this two-line directive to my markdown file:

* TOC
{:toc}

I suppose you could take a look at the source code for kramdown to see how it works.

[Craig Heilman]

Thanks for the good ideas but all those solutions only seem to show the TOC in the markdown preview. I probably wasn’t clear enough that the main goal is to generate the TOC in the .md file and have it display in the .md file while still editing in BBEdit.

I’d prefer to not have to manually add any special attributes such as <a name=“my section name"></a> to each header as some tools require but that wouldn’t be a show stopper.

For example, after putting the insertion point at the start of my document (or not doing that if the script is smart enough to do it for me), then running the script/plugin/etc. I’d expect to see the TOC inserted at the start of the document or just below the “title” (H1 header). Something similar to the following...

Before

Document Title

==============

---

## Section One

Blah

---

## Section Two

Blah blah

After without clickable links

Document Title

==============

---

## Table of Contents

1. Section One

2. Section Two

---

## Section One

Blah

---

## Section Two

Blah blah

After with clickable links

Document Title

==============

---

## Table of Contents

1. [Section One](#section-one)

2. [Section Two](#section-two)

—

<a name="section-one"></a>

## Section One

Blah

---

<a name=“section-two"></a>

## Section Two

Blah blah

Thanks,

Craig

-- 
This is the BBEdit Talk public discussion group. If you have a feature request or need technical support, please email "sup...@barebones.com" rather than posting here. Follow @bbedit on Twitter: <https://twitter.com/bbedit>
--- 
You received this message because you are subscribed to the Google Groups "BBEdit Talk" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bbedit+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/bbedit/d349434f-6544-4090-a3ee-5e151c7dcaafn%40googlegroups.com.

[Greg Raven]

I was thinking you could have your Markdown window on one side of your screen and BBEdit's preview window (which is HTML) on the other side. Changes to the Markdown file show virtually immediately in the preview window. You could even create a preview template with the TOC tag in it so you wouldn't have to add that to each working file in order for it to appear in your preview window.

[Craig Heilman]

It looks like the default cmark preprocessor doesn’t include a “tag” for generating a table of contents? I have used MultiMarkdown in the past so I just installed v6.6.0 and inserted a {{TOC}} in my document - select MultiMarkdown as the Markdown processor in the BBEdit preferences and I get a clickable TOC in the preview. I believe this is similar to what Jean recommended except using MultiMarkdown instead of Pandoc.

Good idea on the use of a preview template but in the end, I would need to have the preview window open to see or make use of the TOC. I have too many windows open as it is so I’m trying to avoid that option.

Other options I’ve explored:

Joplin - I have a co-worker who’s a big fan but our setup has been unstable (server at his location, everything encrypted, lost some files, etc.) so I’m avoiding this at the moment. Also not a big electron-based app fan but that’s a minor point. I do like the fact that you can easily toggle between plain text and markdown preview in the editor via a “Toggle editors” button. It also supports automatic TOC generation via [[toc]].

Obsidian - similar to Joplin in that you can easily switch views between plain text and processed. You can also open a parallel pane to see the processed text. Requires a plugin for TOC generation but it does seem to work well. The plugin includes some support for external editors (e.g. [/toc/], {{doc}}, [[__TOC__]], and [toc]). If the editor pane is set to source mode, you can’t see the TOC but if set to live preview mode, the TOC is visible and clickable (need to click an edit button to edit the TOC when in this mode).

I’ve been a Bbedit user since the earliest days so hoping to find a workable solution. Maybe a simple request to BBEdit support for a “toggle view” button in the editor window to switch between plain text and markdown preview mode!

Thanks,

Craig

To view this discussion on the web visit https://groups.google.com/d/msgid/bbedit/42d62042-89c2-424a-99b1-01827061ce31n%40googlegroups.com.

[jj]

Sticking with Pandoc, you could use a BBEdit shell script to create a clickable table of contents at the beginning of the document.

Create script in ~/Library/Application Support/BBEdit/pandoc-toc.sh

    #!/usr/bin/env sh
   
    pandoc \
    --standalone \
    --from=markdown \
    --to=markdown \
    --table-of-contents \
    -V toc-title:"Table of Contents" \
    --template="${HOME}/.pandoc/template.markdown" \
    --toc-depth=4 \
    --reference-links \
    --reference-location=section \
    -o "${BB_DOC_PATH}" -
   
Create the following template in ~/.pandoc/template.markdown

    $if(titleblock)$
    $titleblock$

    $endif$
    $for(header-includes)$
    $header-includes$

    $endfor$
    $for(include-before)$
    $include-before$

    $endfor$
    $if(toc)$

    $if(toc-title)$
    # $toc-title$
    $endif$

    $table-of-contents$

    $endif$
    $body$
    $for(include-after)$

    $include-after$
    $endfor$

And use the straight Pandoc Markdown Processor in BBEdit's Preferences.

This is not exactly what you want, but maybe by reading the documentation and tweaking Pandoc a bit more you could get what you are after.

HTH

Jean Jourdain