markdown: <TOC/> component, fix #1275 [WIP]

[shigma]

Summary

What kind of change does this PR introduce? (check at least one)

• Bugfix
• Feature
• Code style update
• Refactor
• Docs
• Build-related changes
• Other, please describe:

If changing the UI of default theme, please provide the before/after screenshot:

Does this PR introduce a breaking change? (check one)

• Yes
• No

If yes, please describe the impact and migration path for existing applications:

The PR fulfills these requirements:

• When resolving a specific issue, it's referenced in the PR's title (e.g. fix #xxx[,#xxx], where "xxx" is the issue number)

You have tested in the following browsers: (Providing a detailed version will be better.)

• Chrome
• Firefox
• Safari
• Edge
• IE

If adding a new feature, the PR's description includes:

• A convincing reason for adding this feature
• Related documents have been updated
• Related tests have been updated

To avoid wasting your time, it's best to open a feature request issue first and wait for approval before working on it.

Other information:

• Be compatible with old [[TOC]] syntax while enable new syntax <TOC/>. You can configurate TOC in markdown.toc or by directly passing props to <TOC/> component.
• BREAKING: slugify, format and forceFullToc are not supported at present.
• Documentation has been updated as well.

[shigma]

@ulivz could you have a review on this? The original issue is marked as contribution welcome.

[ulivz]

Thanks for the great work, but I don't want to introduce so much code to fix this issue.

[shigma]

Thanks for the great work, but I don't want to introduce so much code to fix this issue.

😢 I thought those addition could be compromised by removing a dependency.

[ulivz]

Another solution is that you can transform your code changes into an internal plugin, for now the code are too dispersed.

[shigma]

@ulivz I added TOC into built-in-components. What badge do you plan for the TOC component?

[shigma]

Breaking Changes and Migrations

slugify

• use markdown.slugify instead.

format

• currently not supported by $page.headers.
• also we cannot transfer function from server to client.
• future solutions: markdown.format: function for formatting headings.

forceFullToc

• currently not supported by $page.headers.

[lunaceee]

I'm not sure if this is relevant but before I create a new issue I'd like you guys to verify my question first:

I'd like to add a toc to the site level, instead of adding it to each markdown file.

I tried adding
<TOC :list-type="['ol', 'ul']"><p slot="header"><strong>Custom Table of Contents</strong></p</TOC>
to the Layout.vue file, got the following error message:
<TOC> - did you register the component correctly? For recursive components, make sure to provide the "name" option.

Any suggestions are highly appreciated!

[shigma]

@lunaceee I think it's not our problem.

https://www.meteorlxy.cn/posts/2018/11/06/koa-core-read-source-code-part-3.html

You see, this is a website powered by VuePress, which indeed has a TOC on the site level, and it works well.

[lunaceee]

Thanks @shigma, this is really helpful!