The generated toc provides links to the headers, but in some cases (e.g. pdf output) it could be desirable to ignore that output.

so instead of:

- [AAA](#aaa)
- [BBB](#bbb)
- [CCC](#ccc)

the output is:

- AAA
- BBB
- CCC

Note that I'm currently using toc.insert() and I don't know if currently is a way to modify the generated toc

I have a README with a section with a "-" in the title:

# Development - IntelliJ

The link generated by markdown-toc looks like:

https://github.com/me/myproject#development-intellij

But the link generated by GitHub when it renders the README needs to look like

https://github.com/me/myproject#development---intellij

"Highights"

Example:

# Header 1

## Description
blabla

## Examples
blabla

# Header 2

## Description
blabla

## Examples
blabla

In this example the sub headers of "Header 2" must get a numbered suffix in its link separated with a "-".

The resulting toc should look like:

- [Header 1](#header-1)
    - [Description](#description)
    - [Examples](#examples)
- [Header 2](#header-2)
    - [Description](#description-1)
    - [Examples](#examples-1)

The generate function sets this up as a remarkable plugin internally, but is not exported.

Is it possible to use this directly as a remarkable plugin ?

It would be nice if there was an option for supporting german umlauts in the links, e.g. this is what markdown-toc creates:

+ [Frachtaufträge](#frachtauftrage)

This is what I desire:

+ [Frachtaufträge](#frachtaufträge)

GitLab creates anchors with umlauts so currently I need to manually edit all anchors with umlauts.

This is less of an issue and more of a question. I'm using marked-toc as part of my process for generating documentation. My source is in Markdown which is then converted to HTML and then from HTML to PDF. The Markdown-to-HTML tool that I am using honors only a 4-space indent in Markdown.

Using marked-toc, an outline like

Introduction
============

Overview
--------

### Objectives

gets converted to HTML that looks like

• Introduction
• Overview
  • Objectives

because marked-toc uses two spaces. From Markdown Basics I know that four spaces is specified for code blocks, but I am not sure if this is a standard for nesting lists.

The code I use to correct the indentation is (in case other people run into the same issue)

var toc = require('marked-toc');
var fs = require('fs');
var args = process.argv.slice(2);
var str = fs.readFileSync(args[0], 'utf-8');

var strip = /<!-- toc -->[\s\S]+<!-- toc stop -->/;
var strWithTable = toc.insert(str, {firsth1: true});
var betterToc = strWithTable.match(strip)[0];
betterToc = betterToc.replace(/\n\s{10}\*/g,'\n                    *');
betterToc = betterToc.replace(/\n\s{8}\*/g, '\n                *');
betterToc = betterToc.replace(/\n\s{6}\*/g, '\n            *');
betterToc = betterToc.replace(/\n\s{4}\*/g, '\n        *');
betterToc = betterToc.replace(/\n\s{2}\*/g, '\n    *');
fs.writeFileSync(args[0], strWithTable.replace(strip, betterToc));

Any chance of being how to configure the indentation length in the future?

# hello/world

turns into

#hello-world

instead of

#helloworld

I built a little tool called markdown-index that depends on marked-toc. Unfortunately it's not fitting my use case perfectly: I want to build a TOC for all headings in a markdown file, including the first one.

Any bright ideas on how to make this possible without breaking backwards compatibility for your use cases?

Introduced in f4030e4, this behavior breaks existing code that don't assume the links are escaped (hence don't escape ids when they are rendering headings in the content).

Reading the doc and the code I couldn't find a way to tell markdown-toc not to escape these links, so things like toc('# 标题\n').content is always rendered to '- [标题](#%E6%A0%87%E9%A2%98)'.

I would like to request a feature like toc('# 标题\n', { escapeSlug: false }).content -> '- [标题](#标题)' which give users a choice to skip the escaping. If that sounds plausible I can open a PR.

Hi. Nice utility for my marked pages - thanks. When I run toc on my markdown I only get 3 levels of indention (from the md #, ##, ###) but I have more levels (####). firsth1 is set true. It is not obvious from the README level examples if or how I can control that (with the empty string depth prop of the json template?). I wanted to ask for clarification before digging deeper.

Looks like I found another one 😊

# Hello & World

should be

hello--world

instead of

hello-&-world

Looks like I found another edgecase :)

# main:hello_world

renders to

- [main:hello_world](#mainhello-world)   

instead of

- [main:hello_world](#mainhello_world)   

Again, as a result the anchor link doesn't match with the github generated one

Delete

In README:

• markdown-link: Micro util for generating a single markdown link.

=> 404

For example I have such structure:

# h1
blah

## h2
another blah

### h1
fatal blah

for this file the following toc will be generated:

<!-- toc -->

* [h1](#h1)
  * [h2](#h2)
    * [h1](#h1)

<!-- toc stop -->

But I 've expected to recieve this:

<!-- toc -->

* [h1](#h1)
  * [h2](#h2)
    * [h1](#h1-1)

<!-- toc stop -->

Yes, possibly, it is not a good style to generate such kinds of tocs, but such variants are possible!

Thank you.

Hi,

at first, great library! I'll use it for my little blog engine bloggy to generate TOCs.

I think I've found a minor bug.

A heading with a question mark (maybe if also occurs for other special characters) at the end (e.g.: "Neue Platte - Was ist zu tun?") gives these results:

The url in the TOC: #neue-platte-was-ist-zu-tun
The modified heading: <h2 id="neue-platte-was-ist-zu-tun-">Neue Platte - Was ist zu tun?</h2> (recognize the dash at the end of the anchor)

So, a user cannot navigate to this heading.

I think it's not a big change.

Maybe the library https://github.com/dodo/node-slug could help you to valid and consistent slugs.

Kind regards
Marcell

Currently, it looks like I need a <!-- toc --> delimiter in my source markdown file.
It may be nice if I could quickly generate a TOC for any random markdown file and just echo the TOC to stdout.

add a new CLI

From the Readme I can't tell what it is (function?) or how to use it, am I missing something? I'll look in the source for now but perhaps it could be documented better?

The https://github.com/jonschlinkert/marked-toc project had a command-line option to update the table of contents of a markdown file inline (i.e. to apply toc.insert to a named file).

This would be very useful in markdown-toc

I noticed that the contents in toc.insert look a bit "off" but they look fine in the .verb.md file...

README.md:

### toc.insert

Insert a table of contents immediately after an _opening_ `

` code comment, or replace an existing TOC if both an _opening_ comment and a _closing_ comment (`

`) are found.

.verb.md:

### toc.insert

Insert a table of contents immediately after an _opening_ `<!-- toc -->` code comment, or replace an existing TOC if both an _opening_ comment and a _closing_ comment (`<!-- tocstop -->`) are found.

Looks like somewhere in the verb->readme formatting, the HTML comments are getting parsed and stripped.

This is a great package, but I could only get it working once I had installed globally, using npm i -g marked-toc --save.

This is not currently reflected by the README. When I tried to use as per the instructions, I got "command not found: toc".

I am using ZSH but I do have my PATH configured in .zshrc

(Disclaimer: I'm reasonably new to the world of Node and NPM).

Thanks for your awesome library ;)

My question is that:

For example, I created 2 toc blocks like below

<!-- toc -->
- [hahaha](#hahaha)
<!-- tocstop -->

<!-- toc -->
- [hahaha](#hahaha)
<!-- tocstop -->

# hahaha
### yoooo

then I called toc.insert and I get the exception Uncaught Error: markdown-toc only supports one Table of Contents per file..

If there any way to handle such errors in callback function instead of try/catch?

Thank you

The generated TOC should not contain any "perceived" headings that were in code blocks. e.g.:

# coffee
math =
  root:   Math.sqrt
  square: square
  cube:   (x) -> x * square x

or

# A Markdown Heading

Hi.

I will be grateful for any hint how to use markdown-toc with markdown-pdf for dynamic table of content insertion using toc.insert() method.

The problem is that as far as I understand the logic, preProcessMd works with streams, but toc.insert needs to process full Markdown file first (to generate TOC and insert it in Markdown file on position defined by <!-- toc --> tag).

Thanks.

Hi,

I've followed the advice found at #39 and #44.
I managed to get unlazy-loader to work.

The error appears to be coming from function linkify in index.js.
Uncaught TypeError: querystring.escape is not a function

I don't see querystring listed as a dependancy. I tried to install it but it had no effect.

Traditionally, text files should end with a newline char.

The toc command strips the trailing newline from a README which has one.

I think that toc should either not change the presence or absence of a trailing newline, or if it does want to take an opinion on this issue, it should add one rather than remove one.

Generate TOC with the option firsth1:false outputs undefined. Btw, I would also suggest to use a more meaningful name like skipFirstHeadline

Noticed it before few mins.

having this heading

API

it generates

- [`API`](#-api-)

but the link should be #api only, not #-api-

working example

'use strict'

var toc = require('markdown-toc')
var res = toc('# `API`\n ## [letta](./index.js#L14)\nfoo bar\n## BBB\n## [.promisify](./index.js#L37)\n## CCC\nfoo')

console.log(res.content)

I tried this on several machines (Windows 7 + Windows 8), and the error is always the same:

>npm install marked-toc
npm WARN package.json [email protected] No repository field.
npm ERR! Error: ENOENT, chmod 'MyPath\node_modules\marked-toc\cli.js'
npm ERR! If you need help, you may report this *entire* log,
npm ERR! including the npm and node versions, at:
npm ERR!     <http://github.com/npm/npm/issues>

npm ERR! System Windows_NT 6.1.7601
npm ERR! command "C:\\Program Files\\nodejs\\\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "install" "marked-toc"
npm ERR! cwd MyPath
npm ERR! node -v v0.10.32
npm ERR! npm -v 1.4.28
npm ERR! path MyPath\node_modules\marked-toc\cli.js
npm ERR! code ENOENT
npm ERR! errno 34
npm ERR! not ok code 0

I have found that toc adds extra newlines to my README each time it is run.
This means that I can't add it as a build step.

I think that running toc multiple times on the same file should not result in any changes, i.e. it should be idempotent.

Repro at https://gist.github.com/RichardBradley/a72c644e0e09eb501f1f

# hello:world

renders to

   - [hello:world](#hello-world)   

instead of

   - [hello:world](#helloworld)   

Example:

> toc('# hello:world');
{ json:
   [ { content: 'hello:world',
       slug: 'hello-world',
       lvl: 1,
       i: 0,
       seen: 0 } ],
  highest: 1,
  tokens:
   [ { type: 'heading_open', hLevel: 1, lines: [Object], level: 0 },
     { type: 'inline',
       content: '[hello:world](#hello-world)',
       level: 1,
       lines: [Object],
       children: [Object],
       lvl: 1,
       i: 0,
       seen: 0,
       slug: 'hello-world' },
     { type: 'heading_close', hLevel: 1, level: 0 } ],
  content: '- [hello:world](#hello-world)' }

Because of the dash in between the anchor, the URLs don't match the github URL anchors and won't link to them

thlorenz/doctoc#79

The example in the README of using toc.plugin() doesn't seem to work as advertised and I can't for the life of me figure out a workaround.

var Remarkable = require('remarkable');
var toc = require('markdown-toc');

function render(str, options) {
  return new utils.Remarkable()
    .use(toc.plugin(options)) // <= register the plugin
    .render(str);
}

The first issue is that utils is not defined. Assuming that's a typo and removing it:

var Remarkable = require('remarkable');
var toc = require('markdown-toc');

function render(str, options) {
  return new Remarkable()
    .use(toc.plugin(options))
    .render(str);
}

console.log(render('<!-- toc -->\n\n# A\nfoo\n\n#B\nbar'));

I expected something like the following to be logged:

<!-- toc -->
<ul>
    <li><a href="#a">A</a></li>
    <li><a href="#b">B</a></li>
</ul>
<!-- tocstop -->

<h1 id="a">A</h1>
<p>foo</p>
<h1 id="b">B</h1>
<p>bar</p>

But I get an object back as though I had invoked toc() directly:

[object Object]

What am I missing? If I use toc.insert(), then pass the result to a Remarkable instance, I get the expected toc, but the <h1> tags don't have id attributes.

Like this extremely simplified markdown text, just for example:

# h1
## h2-1
### h3-1
### h3-2
## h2-2
## h2-3

if maxdepth is set to 2, then I will get a list like this:

- h1
  - h2-1

and if it is set to 3 will get this:

- h1
  - h2-1
    - h3-1

what is your definition of maxdepth? if the list above is also what you don't want to see, plz check your code.
It can be easily done, by modifying code in index.js at line 124
from

res.push(listitem(ele.content, ele.lvl, opts));
if (ele.lvl === opts.maxdepth) {
  break;
}

to

if (ele.lvl > opts.maxdepth) {
  continue;
}
res.push(listitem(ele.content, ele.lvl, opts));

then if maxdepth is set to 2, it will work out a list like:

- h1
  - h2-1
  - h2-2
  - h2-3

https://github.com/ahdinosaur/inu

^ pretty sweet

I was trying to see if there were any command line options, but it seems like it assumes everything is a file/input:

$ toc
fs.js:443
  return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
                 ^
Error: ENOENT, no such file or directory '/Users/peterdehaan/dev/github/README.md'
    at Error (native)
    at Object.fs.openSync (fs.js:443:18)
    at Object.fs.readFileSync (fs.js:309:15)
    at Object.file.readFileSync (/Users/peterdehaan/npm/lib/node_modules/marked-toc/node_modules/fs-utils/index.js:154:19)
    at Function.toc.add (/Users/peterdehaan/npm/lib/node_modules/marked-toc/index.js:130:22)
    at Object.<anonymous> (/Users/peterdehaan/npm/lib/node_modules/marked-toc/bin/toc:9:5)
    at Module._compile (module.js:449:26)
    at Object.Module._extensions..js (module.js:467:10)
    at Module.load (module.js:349:32)
    at Function.Module._load (module.js:305:12)

$ toc --help
fs.js:443
  return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
                 ^
Error: ENOENT, no such file or directory '/Users/peterdehaan/dev/github/--help'
    at Error (native)
    at Object.fs.openSync (fs.js:443:18)
    at Object.fs.readFileSync (fs.js:309:15)
    at Object.file.readFileSync (/Users/peterdehaan/npm/lib/node_modules/marked-toc/node_modules/fs-utils/index.js:154:19)
    at Function.toc.add (/Users/peterdehaan/npm/lib/node_modules/marked-toc/index.js:130:22)
    at Object.<anonymous> (/Users/peterdehaan/npm/lib/node_modules/marked-toc/bin/toc:9:5)
    at Module._compile (module.js:449:26)
    at Object.Module._extensions..js (module.js:467:10)
    at Module.load (module.js:349:32)
    at Function.Module._load (module.js:305:12)

Not sure if you want to throw a fs.exists() or fs.existsSync() into the mix to ensure that said file/path exists before trying to use it.

When using the script with keep-a-changelog, the links are generated wrong.

The links render fine:

The target is wrong: E.g., "unreleased" points to olivierlacan/keep-a-changelog@v0.3.0...HEAD instead of #unreleased

I assume that simply the the link brackets ( []) have to be removed from the output. E.g., [[Unreleased]](#unreleased) has to be [Unreleased](#unreleased)

The complete example is available at https://github.com/koppor/keep-a-changelog/blob/master/CHANGELOG.md

I've had success in the past using this module with webpack. I'm not sure when or which version the change occurred, but this is no longer the case.

I've setup a gist with the bare minimum code showing what I've been doing.

Output from webpack

WARNING in ./~/markdown-toc/lib/utils.js
Critical dependencies:
7:34-41 require function is used in a way in which dependencies cannot be statically extracted
 @ ./~/markdown-toc/lib/utils.js 7:34-41

Output from browser

bundle.js:10939 Uncaught Error: Cannot find module 'remarkable'.

I have tried process.env.UNLAZY = true; as suggested in lazy-loader
This results in a failure to resolve minimist

I have tried doowb/unlazy-loader
Though as I'm using babel on my own source files, I can't use unlazy-loader without running babel across all my node_modules which takes a long time.

I have tried using unlazy in my import statement

import toc from '!unlazy!markdowntoc';

This results in just markdown-toc/index.js being resolved with unlazy.

I understand there are a lot of parties involved here, so I thought I'd start here and hopefully involve others as the need arises.

These were the two related issues I found
jonschlinkert/lazy-cache#3
webpack/webpack#1763

I have a cyrillic symbols in headings and markdown-toc slugifying them into sequence of -----.
There are npm module transliteration.cyr, that converts cyrillic symbols into latin, but i can not use it because there is no custom slugifying support. It would be nice, if you will add it or share another solution.

I don't think it's a good idea to wrap require in any way, ever. Many libraries / tools are built on the assumption that it remains untouched, because it's pretty much a language construct by now (being an ES5 equivalent of import).

I've seen the Browserify trick in the lazy-cache readme, but it isn't implemented in markdown-toc, and it's not really a solution, but a hack. I want to use this in my client-side code, which involves putting everything through Webpack, and this is the only issue preventing me from having a warning-free build:

WARNING in ./~/markdown-toc/lib/insert.js
Critical dependencies:
4:33-40 require function is used in a way in which dependencies cannot be statically extracted
@ ./~/markdown-toc/lib/insert.js 4:33-40

I'm not a language expert, so I might be wrong and this is a valid use of require, and I should be looking into just suppressing Webpack instead, but, FWIW, I haven't seen any package do this before (i.e. cause warnings like the one above).

Is it possible to use without node?

It may be wanted, but for me not make sense. Actual working example

'use strict'

var toc = require('markdown-toc')
var res = toc('# API\n ## [letta](./index.js#L14)\nfoo bar\n## BBB\n## [.promisify](./index.js#L37)\n## CCC\nfoo')

console.log(res.content)

gives

- [API](#api)
  * [[letta](./index.js#L14)](#-letta---indexjs-l14-)
  * [BBB](#bbb)
  * [[.promisify](./index.js#L37)](#-promisify---indexjs-l37-)
  * [CCC](#ccc)

so render like

• API
  • [letta](#-letta---indexjs-l14-)
  • BBB
  • [.promisify](#-promisify---indexjs-l37-)
  • CCC

(huh, strange why github renders it here so indented but nevermind, that's not the case)

Are you noticing the [[letta](./index.js#L14)](#-letta---indexjs-l14-) thing? Which is not okey for table of contents. Because toc link will not redirect you to the section where's that heading, but to the link that heading redirects to, in case to index.js file.

If a heading contains HTML entities (e.g. >) only the & and the ; are stripped from the target URL. The text in-between is added to the link.

<test> is rendered as lttestgt, but should be test. The generated link is not valid.

The current linkify() code at https://github.com/jonschlinkert/markdown-toc/blob/master/index.js#L178

/**
 * Turn headings into anchors
 */

function linkify(tok, opts) {
  if (tok && tok.content) {
    var text = titleize(tok.content, opts);
    var slug = utils.slugify(tok.content, opts);
    if (tok.seen) {
      slug += '-' + tok.seen;
    }
    if (opts && typeof opts.linkify === 'function') {
      return opts.linkify(tok, text, slug, opts);
    }
    tok.content = utils.mdlink(text, '#' + slug);
  }
  return tok;
}

I think that the slug should be querystring.escape(slug), otherwise the CJK characters may not correctly escaped for the generated URL.