+
// extension host makes it always accessible to extensions:
var vscode = require('vscode');
@@ -147,7 +147,7 @@ Note that the function setting up `markdownIt` also loads *additional plug-ins*.
Another interesting point is using *lazy evaluation*. The extension itself is loaded lazily, only on the events when it is really required. It would be tempting to perform relatively long operations, such as [markdown-it](https://www.npmjs.com/package/markdown-it) setup and processing of the setting, during extension activation, and not during execution of each commands. It won't work correctly though, because between commands the use can enter some changes rendering current state of [markdown-it](https://www.npmjs.com/package/markdown-it) or settings data invalid. In particular, the user can edit settings or simply one or another CSS file. Lazy evaluation combined with some invalidation mechanism solves this problem. This is how:{id=src..lazy.js}
-
+
const lazy = { markdownIt: undefined, settings: undefined };
// ...
@@ -253,7 +253,7 @@ Auto-numbering "start" option can be any integer number or a string representing
In implementation, an interesting point here is the universal `Iterator` covering all these cases:
-
+
function Iterator(first) {
if (first.constructor == Array) this.array = first;
this.counter = this.array ? 0 : first;
@@ -284,7 +284,7 @@ function Iterator(first) {
Let's see how it works.
Let's say, we have the following Markdown fragment, included in other Markdown files, different in auto-numbering options:
-
+
## Contents
[](toc)
@@ -301,7 +301,7 @@ Let's say, we have the following Markdown fragment, included in other Markdown f
To enable default auto-numbering include it in this way:
-
+
[](=numbering {
enable: true
}=)
@@ -314,7 +314,7 @@ It will give as the following TOC:
- 1. Contents
- 2. Introduction
- 3. Something Else
- 1. Section
- 2. Another Section
- 3.2.1. Sub-Section
Now, let's use some advanced auto-numbering options:
-
+
[](=numbering {
enable: true
defaultSuffix: " "
@@ -347,7 +347,7 @@ Also note heading number 1, 2 and "a)". This is where the "standAlong" option is
The object `additionalPlugins` is constructed from the settings data in conservative manner: if something goes wrong, plug-in data is not added:{id=src..additional.plugins.js}
-
+
const additionalPlugins = (function () {
let result = [];
if (!settings.additionalPlugins) return result;
@@ -418,7 +418,7 @@ For other implementation detail, please see [original source code](https://githu
All settings can be customized either globally (per user), or per *workspace*. We can use it to customize markdown preview and behavior (first of all, IntelliSense) to become suitable for the workspace used for article authoring. To do it per workspace, we need to create a file ".vscode/settings.json":{id=src..settings.json}
-
+
{
"markdown.extension.convertToHtml.reportSuccess": true, // default
"markdown.extension.convertToHtml.showHtmlInBrowser": false, // default
@@ -634,9 +634,9 @@ Updated documentation
## Conclusions
-After few prototypes of the solution and creation of the fully-fledged extension, I feel the result is pleasing.
+After few prototypes of the solution and creation of the fully-fledged extension, I feel the result is pleasing. Since the first version, I already wrote many CodeProject articles, including the present article, and other documents. For the CodeProject publications during last years, I never touched the article text manually on the CodeProject article submission page. Instead, I only used copy and paste of the HTML, produced by this extension.
-Even though Visual Studio Code looks still needs some stabilization time, it looks like its code and API are quite healthy and maintainable. It already gives us a great development tool, which now can be also used for article writing, with pleasure and piece in mind.
+Since the first version of Extensible Markdown, Visual Studio Code seriously matured and now looks stabe, healthy and maintainable. It makes a great development tool, which can be used for article writing, with pleasure and piece in mind.
Happy writing!
diff --git a/docs/index.html b/docs/index.html
index 672fe9e..fc5d131 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -81,7 +81,7 @@ Usage by Plugin
The markup should go without blank spaces, no blank spaces in the file name are accepted. If the is found, the Markdown content of the file is rendered, otherwise, the detailed error message is rendered.
IDs and TOC
In all cases, id attributes are generated for all headings (#, ##, and so on).
This markup is the placeholder for TOC:
@toc
Any heading can be excluded from TOC. Usually, it is used for the heading “Contents”. To exclude a heading from TOC, the markup {no-toc} can be added on the same line, for example:
## Some Heading{no-toc}
-Also, the headings of certain levels can be excluded from TOC. It is useful for deeper nesting levels. For example, in this settings.json file only the headers of two levels are included in TOC, ## and ###:
{
+Also, the headings of certain levels can be excluded from TOC. It is useful for deeper nesting levels. For example, in this “settings.json” file only the headers of two levels are included in TOC, ## and ###:
{
"markdown.extensibleMarkdown.TOC.includeLevels": [ 2, 3 ]
}
For the implementation, see id.toc.js.
Attribution
@@ -144,28 +144,28 @@ Usage
Extending of Markdown Syntax
Markdown syntax can be extended. With the extension “Extensible Markdown”, all of them are user-configurable. At the very minimum, each extension can be enabled and disabled, and some extensions allow for detailed configuration. All configurations can be modified on the user or workspace level or their combination.
They can be classified into two parts: in the first part, extensions are based on the predefined VSCode setting. They come with Visual Studio Code installation but are not fully exposed to the end user. The new “Extensible Markdown” extension exposes most of them to user-defined “settings.json” files, so they are made configurable.
In the second part, new extensions are added by Extensible Markdown. Some are embedded, others can be installed and then configured by the user.
Markdown-it Extensions
-VSCode uses embedded “markdown-it” code. The extension “Extensible Markdown” exposed the following extended features: Typographer, “smart quotes” (can used when Typographer is enabled), enabled or disabled HTML formatting in an input Markdown document, “linkify”, generation of br attributes. The configuration parameters are described in the section Markdown-it Options.
Extensible Markdown Embedded Extensions
+VSCode uses embedded “markdown-it” code. The extension “Extensible Markdown” exposed the following extended features: Typographer, “smart quotes” (can used when Typographer is enabled), enabled or disabled HTML formatting in an input Markdown document, “linkify”, generation of br attributes. The configuration parameters are described in the section Markdown-it Options.
Extensible Markdown Embedded Extensions
Extensible Markdown adds three syntax elements to Markdown:
In addition to these syntactic extensions, version 5.0.0 introduces two new TOC features enabled through configuration options, without any addition to the Markdown syntax. The rendering of list items of the TOC can be defined for the whole document, or separately per level of TOC. This way, the choice between ul (default) or ul list element can be done globally or per TOC level. Also, each of these elements can be given a global or level-dependent set of HTML attributes. One of the uses of these attributes is setting the attribute class. However, attributes are not limited to the classes. The possibility of adding arbitrary attributes is very important for the not-uncommon situation where the document hosting does not provide access to CSS. Instead, the inline style attribute can solve the problem. The configuration setting for these is described below.
By default, both elements use pseudo-link form based on Markdown link syntax. They take the form: {{d=some-ID}. The user can create/modify “settings.json” to describe any other suitable syntax, which is done in the Regular Expression form.
Document title needs detection because HTML requires a text value for the title element of the element head. The idea is to use some available Markdown element, which is rendered on the HTML page, without replacing it, but by just tagging it as a title text.
The default syntax for title detection is:
The Name of The Document{title}
+By default, both elements use pseudo-link form based on Markdown link syntax. They take the form: {{d=some-ID}. The user can create/modify “settings.json” to describe any other suitable syntax, which is done in the Regular Expression form.
Document title needs detection because HTML requires a text value for the title element of the element head. The idea is to use some available Markdown element, which is rendered on the HTML page, without replacing it, but by just tagging it as a title text.
The default syntax for title detection is:
The Name of The Document{title}
In this example, the text “The Name of The Document” is copied to the HTML title.
The default syntax for the file include is:
# File "c:/sa/papers/My/GitHub/vscode-extensible-markdown/docs/file-name" not found
// file-name expression should come without blank space characters
A new feature in version 5.0.0 is the “no toc” tag. It is used to exclude some headings from the TOC. It can be important for headings like “Contents” or “Table of Contents”. The default syntax for this tag is:
{notoc}
-This tag works if it is placed at the end of a heading line.
Again, the user can use any other syntax.
Only the first occurrence of the document title tag is taken into account. In the Markdown view, it can be seen in the syntax coloring of this element. Other elements, including TOC, can appear multiple times. Note that the TOC feature works in collaboration with the automatic generation of the id attributes for all heading elements (h1… h6), which is also embedded in the extension.
All these elements are emphasized in the source Markdown document by syntax coloring with a coloring style configured by the user. Please see the description of the settings.
Extensible Markdown User-Installed Extensions
-The configuration option “markdown.extension.convertToHtml.options.additionalPlugins” is used for adding the references to additional “markdown-it” plug-ins which can be installed by the user. Please see the section Customization of Additional Plug-Ins for the details.
Settings
+This tag works if it is placed at the end of a heading line.
Again, the user can use any other syntax.
Only the first occurrence of the document title tag is taken into account. In the Markdown view, it can be seen in the syntax coloring of this element. Other elements, including TOC, can appear multiple times. Note that the TOC feature works in collaboration with the automatic generation of the id attributes for all heading elements (h1… h6), which is also embedded in the extension.
All these elements are emphasized in the source Markdown document by syntax coloring with a coloring style configured by the user. Please see the description of the settings.
The configuration option “markdown.extension.convertToHtml.options.additionalPlugins” is used for adding the references to additional “markdown-it” plug-ins which can be installed by the user. Please see the section Customization of Additional Plug-Ins for the details.
There are three levels of settings. The user of this extension can control them all.
General options control the behavior of command and detail of the HTML output unrelated to Markdown formatting.
The extension is based on the node.js package “markdown-it”. This module has its own options. Markdown-it options define how the mark-down module should be set up before parsing.
+
General options control the behavior of command and detail of the HTML output unrelated to Markdown formatting.
The extension is based on the node.js package “markdown-it”. This module has its own options. Markdown-it options define how the mark-down module should be set up before parsing.
These options are classified into two sets: a) embedded set of options, and b) what plug-ins should be used.
-Markdown-it can use other node.js packages as plug-ins, each defining custom or extended parsing and rendering rules. See customization of Additional Plug-Ins.
Some of the “markdown-it” plug-in packages have their own options. For example, see the package “markdown-it-table-of-contents”. The example of setting its options in “settings.json” is shown in the settings sample.
Some of the “markdown-it” plug-in packages have their own options. For example, see the package “markdown-it-table-of-contents”. The example of setting its options in “settings.json” is shown in the settings sample.
| markdown.extension.convertToHtml.titleLocatorDecoratorStyle | -see “settings.json” sample | +see “settings.json” sample | CSS style for syntax coloring of the title extended Markdown tag element | |
| markdown.extension.convertToHtml.excludeFromTocLocatorDecoratorStyle | -see “settings.json” sample | +see “settings.json” sample | CSS style for syntax coloring of the tag marking a heading to be excluded from TOC | |
| markdown.extension.convertToHtml.tocDecoratorStyle | -see “settings.json” sample | +see “settings.json” sample | CSS style for syntax coloring of the title extended Markdown tag marking the TOC placing | |
| markdown.extension.convertToHtml.includeLocatorDecoratorStyle | -see “settings.json” sample | +see “settings.json” sample | CSS style for syntax coloring of the file include extended Markdown tag element | |
| markdown.extension.convertToHtml.autoNumbering | { enable: false } |
-Structure of auto-numbering; see Auto-Numbering; with default value null the effective options are taken from the embedded plugin default |
+Structure of auto-numbering; see Auto-Numbering; with default value null the effective options are taken from the embedded plugin default |
|
| markdown.extension.convertToHtml.autoNumberingRegex | \[\]\(\=numbering([\s\S]*?)\=\) |
-Defines Regex pattern for the tag used to define the structure of auto-numbering at the document level. See Auto-Numbering. This tag should come at the first position of the Markdown document file. | +Defines Regex pattern for the tag used to define the structure of auto-numbering at the document level. See Auto-Numbering. This tag should come at the first position of the Markdown document file. | |
| markdown.extension.convertToHtml.autoNumberingDecoratorStyle | @@ -350,7 +350,7 @@||||
| markdown.extension.convertToHtml.options.typographer | true | -Typographer option is used | +Typographer option is used | |
| markdown.extension.convertToHtml.options.smartQuotes | @@ -359,8 +359,8 @@||||
| markdown.extension.convertToHtml.options.additionalPlugins | -see below | -Descriptor of additional markdown-it plug-ins | +see below | +Descriptor of additional markdown-it plug-ins |
The extension also uses “markdown.styles” option related to the extension “VS Code Markdown”.
If one or more CSS files are defined, they are used in the generated HTML files as external or embedded style sheets, depending on the option “markdown.extension.convertToHtml.embedCss”. The user is responsible for supplying the CSS files themselves.
To use the typographer, “markdown-it” option “markdown.extension.convertToHtml.options.typographer” should be set to true (default).
Typographer substitution rules:
To use the typographer, “markdown-it” option “markdown.extension.convertToHtml.options.typographer” should be set to true (default).
Typographer substitution rules:
+- → ±... → … (single character, ellipsis)--- → — (em dash)'…': depends on “markdown.extension.convertToHtml.options.smartQuotes” value, two last charactersThe two last patterns are more complicated. They match the text taken in a pair of quotation marks, either "" or ''. Importantly, they should be balanced, to get processed.
The value of the option “markdown.extension.convertToHtml.options.smartQuotes” should be a string with four characters. If the values resolved to false in a conditional expression (undefined, null) or contain less than four characters, no replacement is performed — this is the way to turn the feature off, even if other typographer substitutions are enabled. For languages such as English, Hindi, Indonesian, etc., it should be “”‘’ (default); for many European languages and languages using the Cyrillic system, it’s «»‹›, «»“” or the like (second pair highly polymorphic and rarely used), and so on.
To use the typographer, “markdown-it” option “markdown.extension.convertToHtml.titleLocatorRegex” should define the regular expression pattern used to detect some fragment of the input Markdown text which should be interpreted as the title of the document.
+
To use the typographer, “markdown-it” option “markdown.extension.convertToHtml.titleLocatorRegex” should define the regular expression pattern used to detect some fragment of the input Markdown text which should be interpreted as the title of the document.
If the pattern match is successfully found in the Markdown document, it is written to the title element of the HTML head element. If the match is not found, the text “Converted from: /
It’s important to understand that detection never modifies input Markdown text. The idea is to detect a specific text fragment present in the document. If Markdown rules rendering this text fragment are applied to the output HTML, it will be rendered, and the copy of this fragment will be written in the title element.
The user can introduce alternative syntax for this feature by modifying the option “markdown.extension.convertToHtml.titleLocatorRegex”.
The File Includes feature allows including an external file in the source Markdown document before it is parsed. The file path is relative to the current document where the include element is placed.
Syntax coloring can be defined using a pair of configuration settings a Regular Expression and a set of CSS properties. A regular expression should contain an additional group marked by round brackets (), according to the Regular Expression syntax. This group is used in the text of the tooltip shown by the matching text fragment when a mouse cursor hovers over it. The matching text is styled according to the provided CSS style set. Please see the properties *Regex* and style in the “settings.json” sample.
Syntax coloring can be defined using a pair of configuration settings a Regular Expression and a set of CSS properties. A regular expression should contain an additional group marked by round brackets (), according to the Regular Expression syntax. This group is used in the text of the tooltip shown by the matching text fragment when a mouse cursor hovers over it. The matching text is styled according to the provided CSS style set. Please see the properties *Regex* and style in the “settings.json” sample.
Version 5.0.0 introduced an optional user-configurable auto-numbering option. Auto-numbering can be configured either at the level of Visual Studio Code settings options markdown.extension.convertToHtml.autoNumbering and markdown.extension.convertToHtml.autoNumberingRegex, or at the document level, in the extension tag matching the Regular Expression defined by markdown.extension.convertToHtml.autoNumberingRegex, by default: \[\]\(\=numbering([\s\S]*?)\=\). If used, this tag should come at the first position of the Markdown document file.
By default, auto-numbering is not used. This is the case when both the auto-numbering tag is not present in the document and the option markdown.extension.convertToHtml.autoNumbering. If both conditions are met, document-level specification of auto-numbering takes precedence.
This is the representative sample of the fragment of the Markdown code using the extended syntax for passing the auto-numbering option. This is a tag that should come in the first position of the document file:
&;atnumbering {
"enable": true,
"defaultPrefix": "",
@@ -519,7 +519,7 @@ Simplified Auto-Number
Since v. 2.0.0, additional “markdown-it” plug-ins can be installed by the users of the extension and configured for use with Visual Studio Code.
Installation
All “markdown-it” plug-ins can be installed using node.js npm without installation of the “markdown-it” module itself, as it is already installed with Visual Studio Code. It is assumed that all such plug-ins are installed in the same "node_modules" directory. The “convert-markdown-to-html” does not require the installation of plug-ins to the same directory as any of the “markdown-it”. It is recommended to install the plug-ins separately.
Initial installation of plug-ins requires the installation of node.js, but node.js is not required after the plug-ins are installed. Plug-ins can be installed locally (recommended):
npm install --save a-name-of-markdown-it-plug-in
Customization of Additional Plug-Ins
-Additional plug-ins are set up with one single “setting.json” option: markdown.extension.convertToHtml.options.additionalPlugins.
This is how the default value is shown in “package.json”:
// ...
+Additional plug-ins are set up with one single “setting.json” option: markdown.extension.convertToHtml.options.additionalPlugins.
This is how the default value is shown in “package.json”:
// ...
"default": {
"absolutePath": "",
"relativePath": "",
diff --git a/docs/index.md b/docs/index.md
index f5132df..9c41740 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -82,7 +82,7 @@ Any heading can be excluded from TOC. Usually, it is used for the heading "Conte
## Some Heading{no-toc}
```
-Also, the headings of certain *levels* can be excluded from TOC. It is useful for deeper nesting levels. For example, in this settings.json file only the headers of two levels are included in TOC, `##` and `###`:
+Also, the headings of certain *levels* can be excluded from TOC. It is useful for deeper nesting levels. For example, in this "settings.json" file only the headers of two levels are included in TOC, `##` and `###`:
```
{
@@ -228,7 +228,7 @@ In the second part, new extensions are added by Extensible Markdown. Some are em
### Markdown-it Extensions
-VSCode uses embedded ["markdown-it"](https://www.npmjs.com/package/markdown-it) code. The extension "Extensible Markdown" exposed the following extended features: Typographer, "smart quotes" (can used when Typographer is enabled), enabled or disabled HTML formatting in an input Markdown document, "linkify", generation of `br` attributes. The configuration parameters are described in the section [Markdown-it Options](#heading.markdown-it-options).
+VSCode uses embedded ["markdown-it"](https://www.npmjs.com/package/markdown-it) code. The extension "Extensible Markdown" exposed the following extended features: Typographer, "smart quotes" (can used when Typographer is enabled), enabled or disabled HTML formatting in an input Markdown document, "linkify", generation of `br` attributes. The configuration parameters are described in the section [Markdown-it Options](#heading-markdown-it-options).
### Extensible Markdown Embedded Extensions
@@ -239,8 +239,6 @@ Extensible Markdown adds three syntax elements to Markdown:
* Table of Contents (TOC) tag
* Exclude from TOC tag
-In addition to these syntactic extensions, version 5.0.0 introduces two new TOC features enabled through configuration options, without any addition to the Markdown syntax. The rendering of list items of the TOC can be defined for the whole document, or separately per level of TOC. This way, the choice between `ul` (default) or `ul` list element can be done globally or per TOC level. Also, each of these elements can be given a global or level-dependent set of HTML *attributes*. One of the uses of these attributes is setting the attribute `class`. However, attributes are not limited to the classes. The possibility of adding arbitrary attributes is very important for the not-uncommon situation where the document hosting does not provide access to CSS. Instead, the inline `style` attribute can solve the problem. The configuration setting for these is described [below](#heading.extensible-markdown-converter-extension-options).
-
By default, both elements use *pseudo-link* form based on Markdown *link* syntax. They take the form: `{{d=some-ID}`. The user can create/modify "settings.json" to describe any other suitable syntax, which is done in the Regular Expression form.
Document title needs detection because HTML requires a text value for the `title` element of the element `head`. The idea is to use some available Markdown element, which is rendered on the HTML page, without replacing it, but by just tagging it as a title text.
@@ -272,11 +270,11 @@ Again, the user can use any other syntax.
Only the first occurrence of the document title tag is taken into account. In the Markdown view, it can be seen in the *syntax coloring* of this element. Other elements, including TOC, can appear multiple times. Note that the TOC feature works in collaboration with the automatic generation of the `id` attributes for all heading elements (`h1`.. `h6`), which is also embedded in the extension.
-All these elements are emphasized in the source Markdown document by [syntax coloring](#heading.syntax-coloring) with a coloring style configured by the user. Please see the description of the [settings](#heading.extensible-markdown-converter-syntax-extension-options).
+All these elements are emphasized in the source Markdown document by [syntax coloring](#heading-syntax-coloring) with a coloring style configured by the user. Please see the description of the [settings](#heading-extensible-markdown-extension-options).
### Extensible Markdown User-Installed Extensions
-The configuration option ["`markdown.extension.convertToHtml.options.additionalPlugins`"](#heading.markdown-it-options) is used for adding the references to additional ["markdown-it"](https://www.npmjs.com/package/markdown-it) plug-ins which can be installed by the user. Please see the section [Customization of Additional Plug-Ins](#heading.customization-of-additional-plug-ins) for the details.
+The configuration option ["`markdown.extension.convertToHtml.options.additionalPlugins`"](#heading-markdown-it-options) is used for adding the references to additional ["markdown-it"](https://www.npmjs.com/package/markdown-it) plug-ins which can be installed by the user. Please see the section [Customization of Additional Plug-Ins](#heading-customization-of-additional-plug-ins) for the details.
## Settings
@@ -284,13 +282,13 @@ The configuration option ["`markdown.extension.convertToHtml.options.additionalP
There are three levels of settings. The user of this extension can control them all.
-1. [General options](#heading.general-options) control the behavior of command and detail of the HTML output unrelated to Markdown formatting.
+1. [General options](#heading-general-options) control the behavior of command and detail of the HTML output unrelated to Markdown formatting.
-1. The extension is based on the [node.js](https://nodejs.org) *package* ["markdown-it"](https://www.npmjs.com/package/markdown-it). This module has its own options. [Markdown-it options](#heading.markdown-it-options) define how the mark-down module should be set up before parsing.
+1. The extension is based on the [node.js](https://nodejs.org) *package* ["markdown-it"](https://www.npmjs.com/package/markdown-it). This module has its own options. [Markdown-it options](#heading-markdown-it-options) define how the mark-down module should be set up before parsing.
These options are classified into two sets: a) embedded set of options, and b) what plug-ins should be used.
-Markdown-it can use other [node.js](https://nodejs.org) packages as plug-ins, each defining custom or extended parsing and rendering rules. See [customization of Additional Plug-Ins](#heading.customization-of-additional-plug-ins).
+Markdown-it can use other [node.js](https://nodejs.org) packages as plug-ins, each defining custom or extended parsing and rendering rules. See [customization of Additional Plug-Ins](#heading-customization-of-additional-plug-ins).
-1. Some of the ["markdown-it"](https://www.npmjs.com/package/markdown-it) plug-in packages have their own options. For example, see the package ["markdown-it-table-of-contents"](https://www.npmjs.com/package/markdown-it-table-of-contents). The example of setting its options in "settings.json" is shown in the [settings sample](#heading.settings-sample).
+1. Some of the ["markdown-it"](https://www.npmjs.com/package/markdown-it) plug-in packages have their own options. For example, see the package ["markdown-it-table-of-contents"](https://www.npmjs.com/package/markdown-it-table-of-contents). The example of setting its options in "settings.json" is shown in the [settings sample](#heading-settings-sample).
### General Options
@@ -311,13 +309,13 @@ The option "`markdown.extension.convertToHtml.outputPath`" is ignored if its val
| Name | Default | Description |
| --- | --- | --- |
| markdown.extension.convertToHtml.titleLocatorRegex | `^(.*?)\[\]\(title\)` | Defines Regex pattern used to parse some fragment of Markdown text as title, to be used as HTML `head` `title` element |
-| markdown.extension.convertToHtml.titleLocatorDecoratorStyle | see ["settings.json" sample](#heading.special-settings.json) | CSS style for syntax coloring of the title extended Markdown tag element |
+| markdown.extension.convertToHtml.titleLocatorDecoratorStyle | see "settings.json" sample | CSS style for syntax coloring of the title extended Markdown tag element |
| markdown.extension.convertToHtml.options.headingId | true | Enables or the generation of the `id` attributes for `h1`.. `h6` elements |
| markdown.extension.convertToHtml.options.headingIdPrefix | `heading.` | If the generation of the `id` attributes is enabled, the heading is added to each `id` value of each `h1`.. `h6` element |
| markdown.extension.convertToHtml.tocRegex | `^\[\]\(toc\)` | Defines Regex pattern used to recognize the location where Table Of Contents (TOC) is placed |
| markdown.extension.convertToHtml.excludeFromTocRegex | `\\[\\]\\(notoc\\)` | Marks the heading elements to be excluded from TOC |
-| markdown.extension.convertToHtml.excludeFromTocLocatorDecoratorStyle | see ["settings.json" sample](#heading.special-settings.json) | CSS style for syntax coloring of the tag marking a heading to be excluded from TOC |
-| markdown.extension.convertToHtml.tocDecoratorStyle | see ["settings.json" sample](#heading.special-settings.json) | CSS style for syntax coloring of the title extended Markdown tag marking the TOC placing |
+| markdown.extension.convertToHtml.excludeFromTocLocatorDecoratorStyle | see "settings.json" sample | CSS style for syntax coloring of the tag marking a heading to be excluded from TOC |
+| markdown.extension.convertToHtml.tocDecoratorStyle | see "settings.json" sample | CSS style for syntax coloring of the title extended Markdown tag marking the TOC placing |
| markdown.extension.convertToHtml.tocIncludeLevels | [1, 2, 3, 4, 5, 6] | Defines the level of the headers to be included in TOC |
| markdown.extension.convertToHtml.defaultListElement | `ul` | Default HTML element for all TOC list elements. This option is ignored if one or more elements are defined on a per-level basis (see below) |
| markdown.extension.convertToHtml.listElements | `[]` | Array of strings each defining an HTML element for a TOC list on each TOC level (see above) |
@@ -328,9 +326,9 @@ The option "`markdown.extension.convertToHtml.outputPath`" is ignored if its val
| markdown.extension.convertToHtml.includeLocatorRegex | `\[\]\(include\(([^\s]+?)\)\)` | Defines Regex pattern used to define file include Markdown syntax extension |
| markdown.extension.convertToHtml.includeLocatorInvalidRegexMessageFormat | `!!! invalid Regular Expression of include: "%s` | Message format for the message produced in the output HTML in case of invalid Regular Expression |
| markdown.extension.convertToHtml.includeLocatorFileReadFailureMessageFormat | `!!! failed to read file "%s" !!!` | Message format for the message produced in the output HTML in case of the file reading failure |
-| markdown.extension.convertToHtml.includeLocatorDecoratorStyle | see ["settings.json" sample](#heading.special-settings.json) | CSS style for syntax coloring of the file include extended Markdown tag element |
-| markdown.extension.convertToHtml.autoNumbering | `{ enable: false }` | Structure of auto-numbering; see [Auto-Numbering](#heading.auto-numbering); with default value `null` the effective options are taken from the embedded plugin default |
-|markdown.extension.convertToHtml.autoNumberingRegex | `\[\]\(\=numbering([\s\S]*?)\=\)` | Defines Regex pattern for the tag used to define the structure of auto-numbering at the document level. See [Auto-Numbering](#heading.auto-numbering). This tag should come at the first position of the Markdown document file. |
+| markdown.extension.convertToHtml.includeLocatorDecoratorStyle | see "settings.json" sample | CSS style for syntax coloring of the file include extended Markdown tag element |
+| markdown.extension.convertToHtml.autoNumbering | `{ enable: false }` | Structure of auto-numbering; see [Auto-Numbering](#heading-auto-numbering); with default value `null` the effective options are taken from the embedded plugin default |
+|markdown.extension.convertToHtml.autoNumberingRegex | `\[\]\(\=numbering([\s\S]*?)\=\)` | Defines Regex pattern for the tag used to define the structure of auto-numbering at the document level. See [Auto-Numbering](#heading-auto-numbering). This tag should come at the first position of the Markdown document file. |
| markdown.extension.convertToHtml.autoNumberingDecoratorStyle | see default settings | CSS style for syntax coloring of the auto-numbering extended Markdown tag element (above) |
### Markdown-it Options
@@ -342,9 +340,9 @@ The extension is based on the node.js module ["markdown-it"](https://www.npmjs.c
| markdown.extension.convertToHtml.options.allowHTML | true | If true, allows HTML formatting, otherwise, HTML code is rendered as text |
| markdown.extension.convertToHtml.options.linkify | false | Renders "Link-like" text as link |
| markdown.extension.convertToHtml.options.br | true | [New line](https://en.wikipedia.org/wiki/Newline) handling: if true, line separators are replaced with the HTML *element* `br` |
-| markdown.extension.convertToHtml.options.typographer | true | [*Typographer*](#heading.Typographer) option is used |
+| markdown.extension.convertToHtml.options.typographer | true | [*Typographer*](#heading-typographer) option is used |
| markdown.extension.convertToHtml.options.smartQuotes | `“”‘’` | If typographer option is true, replaces `""` and `''` characters |
-| markdown.extension.convertToHtml.options.additionalPlugins | see [below](#heading.customization-of-additional-plug-ins) | Descriptor of [additional markdown-it plug-ins](#heading.additional-plug-ins) |
+| markdown.extension.convertToHtml.options.additionalPlugins | see [below](#heading-customization-of-additional-plug-ins) | Descriptor of [additional markdown-it plug-ins](#heading-additional-plug-ins) |
The value of the option "`markdown.extension.convertToHtml.options.smartQuotes`" should have four characters, otherwise the characters `""` and `''` are rendered as is, as if the option value was `""''`. It can be used to turn off the "smart quotes" feature when other typographer processing is enabled.
@@ -363,7 +361,7 @@ If one or more CSS files are defined, they are used in the generated HTML files
### Typographer
-To use the typographer, ["markdown-it" option](#heading.markdown-it-options) "`markdown.extension.convertToHtml.options.typographer`" should be set to true (default).
+To use the typographer, ["markdown-it" option](#heading-markdown-it-options) "`markdown.extension.convertToHtml.options.typographer`" should be set to true (default).
Typographer substitution rules:
@@ -380,7 +378,7 @@ The value of the option "`markdown.extension.convertToHtml.options.smartQuotes`"
### Detecting Document Title
-To use the typographer, ["markdown-it" option](#heading.markdown-it-options) "`markdown.extension.convertToHtml.titleLocatorRegex`" should define the [regular expression](https://en.wikipedia.org/wiki/Regular_expression) pattern used to detect some fragment of the input Markdown text which should be interpreted as the title of the document.
+To use the typographer, ["markdown-it" option](#heading-markdown-it-options) "`markdown.extension.convertToHtml.titleLocatorRegex`" should define the [regular expression](https://en.wikipedia.org/wiki/Regular_expression) pattern used to detect some fragment of the input Markdown text which should be interpreted as the title of the document.
If the pattern match is successfully found in the Markdown document, it is written to the `title` element of the HTML `head` element. If the match is not found, the text "Converted from: /Errors: invalid anchor hrefs:
`);
+ for (let anchor of errors)
+ document.writeln(
+ ` ${anchor.hash}- Text:
+ "${anchor.textContent}"
`);
+ } //if
+
+ if (external.length > 0) {
+ document.writeln(`External anchors:
`);
+ for (let anchor of external)
+ document.writeln(
+ `-
+ ${anchor.textContent}
`);
+ document.writeln("
");
+ } //if
+
+} //window.onload
diff --git a/docs/title-base.png b/docs/title-base.png
new file mode 100644
index 0000000..ccf47d2
Binary files /dev/null and b/docs/title-base.png differ