Skip to content

Latest commit

 

History

History
94 lines (57 loc) · 4.46 KB

README.md

File metadata and controls

94 lines (57 loc) · 4.46 KB
Raw

Create Markdown TOC README

Locates all Level 2 headings in the currently selected markdown file and creates a clean, orderly table of contents near the top of the document. As expected, the table of contents entries link to all discovered Level 2 heading labels within the document, simplifying navigation.

Features

  • Creates a table of contents in the currently open markdown file just prior to the first Level 2 heading.
  • Links to Level 2 headings are stored in the generated table of contents.
  • Supports standard Headings (Open ATX) that are only prefixed with # character(s).
  • Support Closed ATX Headings prefixed and suffixed with # character(s).
  • Supports alternate (Next Line) Headings syntax using = or - characters on nextline following heading title.
  • Generated Table of Contents uses same style of heading (Open, closed, ATX, etc) that it detects within your document.
  • If there is no first level heading, the generated Table of Contents will be inserted near the top of the document.
  • Unsupported link-fragment characters are removed.
  • Headings that contain characters other than alpha-numerics will likely be processed with the exception of unsupported characters such as <, >, and :.
  • Use the VSCode Command Palette to insert the new table of contents.
  • If a Table of Contents already exists, the extension will not make any changes.

See CHANGELOG.md for details.

About This Extension

Open a markdown file with headings in it

Open a Markdown File with Headings in it.

Open the Command Palette and find Create Table of Contents command

Open Command Palette to find "Create Table of Contents".

Select the command and all Level 2 headings will get linked using Heading IDs

Select the command and a Table of Contents will be created with Heading IDs linked up.

Requirements

Build: npm install

Test: npm test

Install: Open Extensions panel (ctrl+shift+x) in VS Code and search for "Create Markdown TOC".

For development:

Testing

Automatically run unit tests in a Terminal by using npm test.

Manual test files are located in the /test/manual-test-files/ directory. Run VS Code, Press F5 to execute the 'Run Extension' Launch Configuration, and then open the folder to get started. Avoid saving changes to the files.

Extension Settings

Contributes.Command: markdown-toc.createTOC "Create Table of Contents"

ActivationEvents: none.

Known Issues

  • Always use a Markdown Linter before running this tool for the best results.
  • A Level 1 Heading must be followed by a newline character or it will be ignored (note: Table of Contents generation does not depend on any Level 1 heading specifically).
  • Headings that start with a space may cause Create ToC to ignore the heading.
  • Level 2 headings that do not match Level 1 heading style will not be shown in the generated Table of Contents.
  • Using multiple headings types will produce unexpected results.
  • A user can create a Heading with many spaces in it that will Lint without error. Create ToC will generate a valid, Linted Link Fragment for that "spacey heading" but the link will be dead.

Note: See GitHub Issues List for the most current status.

Release Notes

This release adds the ability to detect both Standard (Open ATX and Closed ATX) style and Alternate (Next Line) style level 1 and level 2 headings. In all cases, the generated Table of Contents with link fragments will be inserted near the top of the existing markdown document under the first discovered Level 1 heading.

See CHANGELOG.md for detailed release notes.

Credits

Design, code, test, and publisher: Jon Rumsey GitHub LinkedIn

References