# DEVONthink Markdown Table-of-Contents generator

I really love how MultiMarkdown (MMD) automatically generates a Table-of-Contents (TOC) by simply adding the {{TOC}} command to your Markdown files. It’s indeed practical as it updates the TOC after every change you apply to the headings of your document, without any further user-interaction being required. However, there is drawback of how MMD version 6 internally generates the TOC while rendering the Markdown file.

In the example in the screenshots above, the second TOC-entry gets split into

"Section title with a" + "link" + "and some more text"

A solution to this miss-behavior could simply be to stop adding links to the headings. Indeed, I never add links to the headings of my Markdown files. However, the problem re-occurs when you use DEVONthink with its automatic WikiLinks function in combination with the “Names and Aliases” option.

DEVONthink’s automatic WikiLinks function with the selected “Names and Aliases” option.

Having this option selected, DEVONthink automatically converts name and alias mentions within your document into links to the mentioned files. I.e., you don’t have to manually add WikiLinks by enclosing the word with straight brackets (e.g., [[The Wikilink]]), they automatically occur while writing the text.

While being so useful within the contents of your document, automatic WikiLinks get in conflict with the MMD TOC generation in headings due to the miss-behavior explained above. When DEVONthink renders the Markdown document, it internally converts the WikiLinks into html-links. You can’t control, when DEVONthink converts a name and alias mention into a WikiLink and when it should avoid doing it: all mentions are converted automatically.

In the example in the screenshots above, the second TOC-entry gets again split as in the previous example:

"Section with a WikiLink:" + "Some Test File" + "and some more text"

“Some Test File” is not a manually added Markdown reference link, but a detected automatic WikiLink that links to the file Some Test File. When you now click on the TOC-link part “Some Test File”, the linked file opens instead of jumping to the corresponding headline within the current document.

As mentioned above, you can’t turn off the automatic WikiLinks for specific mentions. The only workaround here would be to rewrite the mention in the heading so that it won’t match the corresponding name and alias anymore. E.g., “Some Test File” rewritten as “S0me Tes7 F1le” would deactivate the WikiLink. However, I don’t really like the idea of intentionally adding typos and blemish to my documents.

You can find the script including the Python files and an additional script to remove the TOC on GitHub. Please let me know if you notice any bugs or flaws by reporting them in the issue section of the repository. Please, also read the warning carefully and create backups of your files before applying the script.

I just discovered, that encapsulating headings, that contain links and DEVONthink’s auto-WikiLinks, by angle brackets (<,>) also bypasses the MMD TOC-link problem. E.g., in my example from above, I have to encapsulate the heading “Section 1.1 …” (which contains an auto-WikiLink),

"<Section 1.1 with Some Test File in heading>",

and the TOC-links generated by the {{TOC}} command will still work:

The bypass with the angle brackets also works in DEVONthink To Go (DTTG). While this seems to be a trivial notice, other solutions to suppress auto-WikiLinks in headings by, e.g., placing a soft-hyphen somewhere in the auto-linked name/alias only worked in the desktop app, but not in DTTG (clicking on the corresponding TOC-link became effectless).

Tags:

updated: