Using Widdershins in a JavaScript program gives you control over the full range of options.To use Widdershins from the CLI, see Converting an OpenAPI/Swagger file to Markdown with the Widdershins CLI.

OpenAPI / Swagger / AsyncAPI / Semoasa definition to Slate / Shins compatible markdown. Widdershins adverb: In a direction contrary to the sun's course; anticlockwise; helping you produce static documentation from your OpenAPI 3.0 / Swagger 2.0 / AsyncAPI 1.x / Semoasa 0.1.0 definition; News. Open-source Drive add-on that converts a Google Doc to simple, readable Markdown or HTML.

Prerequisites

• Install NodeJS and Node Package Manager (NPM).See nodejs.org.
• If you don’t already have an NPM project, run npm init from the folder in which you want to create the program.NPM walks you through the process of setting up an NPM project and creates a package.json file to store the project configuration.Most of the NPM settings are not relevant to Widdershins; the important part of the process is that it sets up a project that can install and manage NPM packages such as Widdershins so you can use those packages in your programs.
• From the root folder of your project (the folder that contains the package.json file), add Widdershins as a dependency by running this command:

Now you can use Widdershins in JavaScript programs in the project.

Converting files with JavaScript

1. Create a JavaScript program with the following general steps.You can name the file anything you want.
2. In the JavaScript file, import Widdershins so you can use it in the program:
3. Set up your options in an options object.Use the JavaScript parameter name from the README.md file, not the CLI parameter name.For example, these options generate code samples in Python and Ruby:
4. Import and parse the OpenAPI or Swagger file.This example uses the NodeJS FileSystem and JSON packages:
5. Use Widdershins to convert the file.Widdershins returns the converted Markdown via a Promise:
6. When the Promise resolves, write the Markdown to a file:
7. Run the JavaScript program:

The complete JavaScript program looks like this:

Now you can use the Markdown file in your documentation or use a tool such as Shins to convert it to HTML.

SublimeText3 plugin which generate a table of contents (TOC) in a markdown document.

Details

Installs

• Total30K
• Win13K
• Mac11K
• Linux5K

Readme

Source

raw.​githubusercontent.​com

Sublime Text 3 plugin for generating a Table of Contents (TOC) in a Markdown document.

Note: v3.0.0 has breaking changes. See Upgrade Guide for more detail.

Table of Contents

• Features
  • Automatic refresh of TOC when Markdown document is saved
  • Auto linking for clickable TOC
    • Lowercasing in ids
• Tips
• Limitations
• Installation
• Configuration
• References

Quick Start

1. Install the MarkdownTOC plugin
2. Open your Markdown file
3. Place the cursor at the position where you want to insert the TOC
4. Pick from menu: Tools > MarkdownTOC > Insert TOC
5. And the TOC is inserted in the Markdown document
6. Save the document and you are done

Now you can go on and edit your document further or you can customize you TOC, please read on.

Features

The MarkdownTOC plugin is rich on features and customization, useful for both work on a single Markdown document or if you have several Markdown documents that require special TOC generation.

• Auto linking for clickable TOC
  • Lowercasing in ids

Insertion of TOC based on headings in Markdown document

When you have completed the installation of the plugin, you can insert an automatically generated TOC based on your Markdown headings. See the Quick Start to get going or the Usage section for details on how to utilize customization and configuration.

For the following sample Markdown document:

The MarkdownTOC plugin will out of the box generate:

As you can read from the sample above:

1. Headings above the MarkdownTOC tag section are ignored, only the rest of the document is considered in scope

Automatic refresh of TOC when Markdown document is saved

If we edit the Markdown document some more and add an additional heading:

When we save the document, the TOC is automatically updated.

Same goes for deleted headings, these are cleared out.

Updating the TOC can also be accomplished without saving by picking from the menu: Tools > MarkdownTOC > Update TOC

Supported file extensions

Make sure your file's extension is in the following list.

.md.markdown.mdown.mdwn.mkdn.mkd.mark Download chic mice & touchpads driver.

Customizing generation of TOC using attributes

1. TOC tags can overwrite default attributes using local settings and influence the rendering of the TOC. See: Configuration on how to set your own defaults for the plugin
2. Headings can be automatically linked (see: auto link)
3. Headings can have anchors automatically linked (see: Auto anchoring when heading has anchor defined)

The default behaviour could also be described as:

Please see: Github Configuration for a guideline to configuring MarkdownTOC for Github use.

Auto anchoring when heading has anchor defined

You can add an HTML anchor (<a name='xxx'></a>) before your heading automatically.

The TOC generation can be specified to respect this and a TOC element of the following format is generated:

Please note that the default for the attribute: autoanchor is false.You can add an HTML anchor (<a name='xxx'></a>) before the heading automatically.

Please note that the default for autolink is false defined by the attributedefaults.autoanchor. See also: How to remove anchors added by MarkdownTOC.

Auto linking for clickable TOC

The plugin can be specified to auto link heading so you get a TOC with clickable hyperlink elements.

Chrome app installation. The following sample document:

With autolink set to true will render the following:

The auto link markup style can be one of:

• round, the default, the style supported on Github
• square, the “Markdown standard reference-style links” style.

Please note that the default for autolink is false defined by the attributedefaults.autolink.

round: according to Github style.

square: according to “Markdown standard reference-style links”.

Please note that the default for bracket is round defined by the attributedefaults.bracket.

Lowercasing in ids

By default the plugin lowercases ASCII based alphabets only (a to z) for auto links.

This is same as setting lowercase attribute to only_ascii.

Preserve case

You can disable the lowercasing capability by setting the lowecase attribute to false.

Lowercase all characters

Further more you can also expand the lowercasing capability by setting the lowercase attribute to all(or any values other than false and only_ascii).

You can also specify this in your configuration with key defaults.lowercase.

Manipulation of auto link ids

You can manipulate your link ids in your configuration using the key id_replacements.

1. Regular expression is allowed in each sets
   • It will be simply expanded into python's re.sub(pattern, replacement, id)
2. The replacement sequence executes from top to bottom

An example:

This heading link of this heading is changed to following id

Openapi Markdown Generator

• The ' ' (space) is replaced with - (dash), since ' ' is included in the first set
• The '™' is replaced with nothing, since '™' is included in the second set

URI encoding

By default non-ASCII characters in link ids are URL encoded.

As mentioned you can disable this by setting the uri_encoding attribute to false, like so: uri_encoding='false'.

Markdown Preview compatible

If you want to use MarkdownTOC with Markdown Preview, you should use markdown_preview attribute.You can set this attribute to either markdown or github.

When you set it to markdown, you can get same links rendered by MarkdownPreview's markdown parser.

When you set it to github, you can get same links rendered by MarkdownPreview's github parser.

Currently no other parsers are supported.

If you want to disable this feature, set it to false.

Link Prefix

You can also set prefix of links.

You can manipulate this in your configuration using the key defaults.link_prefix.

Control of levels listed in TOC

With default levels:

With levels set to 1,2:

Please note that the default for the attribute levels is '1,2,3,4,5,6', it means all heading sizes will be included.

You can also specify this in your configuration with key defaults.levels.

The maximum size for headings is 6 according to the Markdown specification

Ordered or unordered style for TOC elements

The plugin supports two styles of TOC element listing:

• unordered
• ordered

A Markdown document with the following contents:

Will with style unordered:

And with style ordered:

Please note that the default for the attribute is: unordered.

You can set your default style in your configuration with the key defaults.style.

Customizable list bullets in TOC

You can define the list items used for the TOC for each level. The first item is for the first level, the second for the second and so on until the last one of the list and then it starts over from the beginning.

You can set default list bullets in your configuration with the key defaults.bullets.

The example above could also be described as:

You can also set it in attribute. In this case the values type is 'conmma separated string'.

Specify custom indentation prefix

The indentation prefix is a specification of the string used to indent the TOC elements.

An ugly but demonstrative example could be to use an emoji.

Please note that the default for the attribute is: 't'.

You can set your default indentation in your configuration with the key defaults.indent.

Preserve images in headings

If you want to preserve images in headings, set remove_image to false.

Please note that the default for the attribute is: false.

You can change your default setting in your configuration with the key defaults.remove_image.

Excluded headings

You can exclude certain headings in the TOC by adding a special comment to the line above the line with the heading, as shown below.

Usage

1. Open your Markdown file
2. Set cursor to position where you want to insert a TOC
3. Pick from menu: Tools > MarkdownTOC > Insert TOC
4. TOC is inserted in document
5. Evaluate your TOC and customize using attributes or configuration
6. Update contents and save…
7. TOC has been updated

Don't remove the comment tags if you want to update every time saving.

Tips

How to remove anchors added by MarkdownTOC

If you want to remove the TOC again, you do not have to go through your complete Markdown and remove all tags manually - just follow this simple guide (see also: Auto anchoring when heading has anchor defined).

1. Open your Markdown file
2. Set the attribute autoanchor to false, this clears all anchors

Please see the below animation demonstrating the change

3. Now delete the TOC section from beginning to end and **MarkdownTOC** integration is gone

Ref: Github issue #76

Addressing issues with Github Pages

If you are using Github Pages you might experience that some themes do not render heading correctly.

This can be addressed simply by setting autoanchor to false

And when Jekyll is done, your headings should render correctly.

Markdown laravel editor. Ref: Github issue #81

Using MarkdownTOC with Markdownlint

If you are using Markdownlint (Node implementation), it will report several violations out of the box.

The basic configuration you can use to address these looks like the following:

• html set to false, to allow use of HTML since MarkdownTOC relies on HTML tags to assist the Markdown
• blanks-around-headings should be set to false, since anchors are places closed to the headings that are listed in the TOC
• ul-indent should have it's parameter indent set to 4 to adhere with the default of 4 used by MarkdownTOC, whereas Markdownlint defaults to 2

If you have configured MarkdownTOC differently, you can adjust your Markdownlint configuration accordingly.

Do note that this tip is based on the Node implementation, available on GitHub, which uses a project specific .markdownlint.json based configuration.

Limitations

MarkdownTOC does come with some limitations.

For more information on compatibility, please see the dedicated section.

Headings in lists are not included in the auto-generated table of contents

Example of Markdown heading in a Markdown listing, not being included in the auto-generated Table of Contents

Attributes

The following attributes can be used to control the generation of the TOC.

You can define your own default values via package preferences, Sublime Text's way of letting users customize package settings. Please see the Section on Configuration for more details for MarkdownTOC.

Installation

Using Package Control

1. Run “Package Control: Install Package” command, find and install MarkdownTOC plugin.
2. Restart Sublime Text

From Git

From downloadable archive

1. Download zip-file and unpack it.
2. Open the Sublime TextPackages/ directory (pick menu: Sublime Text > Preferences > Browse Packages).
3. Move the MarkdownTOC/ directory into the Packages/ directory.

Configuration

You can use attributes to customize a TOC in a single Markdown document, but if you want to keep the same TOC configuration accross multiple Markdown documents, you can configure your own defaults.

Pick: Sublime Text > Preferences > Package Settings > MarkdownTOC > Settings - User

Alternatively you can create the file ~/Library/Application Support/Sublime Text 3/Packages/User/MarkdownTOC.sublime-settings by hand.

Example: MarkdownTOC.sublime-settings

Please see the section on attributes for an overview of values and the section on customization.

Openapi To Markdown File

Configuration precendence is as follows:

1. Attributes specified in MarkdownTOC begin tag (see: Customizing generation of TOC using attributes)
2. MarkdownTOC Settings - user (this section)
3. MarkdownTOC Settings - default (see: Attributes)

For an overview of the specific behaviour behind an attribute, please refer to the below list.

• defaults.autolink, (see: Auto linking for clickable TOC)
• defaults.autoanchor, (see: Auto anchoring when heading has anchor defined)
• defaults.bracket, (see: Auto linking for clickable TOC)
• defaults.indent, (see: Specify custom indentation prefix)
• defaults.link_prefix, (see: Link Prefix)
• defaults.levels, (see: Control of levels listed in TOC)
• defaults.bullets, (see: Customizable list bullets in TOC)
• defaults.lowercase, (see: Lowercasing in ids)
• defaults.remove_image, (see: Preserve images in headings)
• defaults.style, (see: Ordered or unordered style for TOC elements)
• defaults.uri_encoding, (see: URI encoding)
• defaults.markdown_preview, (see: Markdown Preview compatible)
• id_replacements, (see: Manipulation of auto link ids)

Github Configuration

A configuration for writing Markdown primaily for use on Githubcould look like the following:

Configuration and Collaboration

You should be aware that if you collaborate with other Markdown writers and users of MarkdownTOC, you might have changes going back and forth simply due to differing configurations.

If that is the case and you cannot agree on a configuration, choose configuration using attributes specified in the document instead.

Example of attribute configuration for the above configuration settings in file:

Compatibility

This is by no means an exhaustive list and you are welcome to provide additional information and feedback. Here is listed what Markdown rendering platforms and tools where compatibility and incompatibily has been asserted with the MarkdownTOC plugin.

Contributing

Contributions are most welcome, please see the guidelines on contributing.

License

• MarkdownTOC is licensed under the MIT License

Author

References

Markdown Table of Contents Generators

Here follows a list of other Markdown Table of Contents generators, for inspiration and perhaps even use in the situation where the MarkdownTOC Sublime Text plugin is not the right tool for the job. Please note that the list is by no means authoritative or exhaustive and is not a list of recommendations, since we can only endorse MarkdownTOC our contribution to the Markdown Table of Content generators toolbox.

• doctoc Node (npm) implementation with CLI interface
• markdown-toclify Python implementation with CLI interface

Recommended plugins for use with MarkdownTOC

• Markdown Numbered Headers Sublime Text 3 plugin for Markdown, auto insert/update/remove header numbers