1 | import utils = require('./common/utils');
|
2 | import helpers = require('./helpers');
|
3 | import State = require('./rules_core/state_core');
|
4 | import Renderer = require('./renderer');
|
5 | import ParserCore = require('./parser_core');
|
6 | import ParserBlock = require('./parser_block');
|
7 | import ParserInline = require('./parser_inline');
|
8 |
|
9 | import LinkifyIt = require('linkify-it');
|
10 |
|
11 | import Token = require('./token');
|
12 |
|
13 | declare namespace MarkdownIt {
|
14 | /**
|
15 | * MarkdownIt provides named presets as a convenience to quickly
|
16 | * enable/disable active syntax rules and options for common use cases.
|
17 | *
|
18 | * - ["commonmark"](https://github.com/markdown-it/markdown-it/blob/master/lib/presets/commonmark.js) -
|
19 | * configures parser to strict [CommonMark](http://commonmark.org/) mode.
|
20 | * - [default](https://github.com/markdown-it/markdown-it/blob/master/lib/presets/default.js) -
|
21 | * similar to GFM, used when no preset name given. Enables all available rules,
|
22 | * but still without html, typographer & autolinker.
|
23 | * - ["zero"](https://github.com/markdown-it/markdown-it/blob/master/lib/presets/zero.js) -
|
24 | * all rules disabled. Useful to quickly setup your config via `.enable()`.
|
25 | * For example, when you need only `bold` and `italic` markup and nothing else.
|
26 | */
|
27 | type PresetName = 'default' | 'zero' | 'commonmark';
|
28 |
|
29 | interface Options {
|
30 | /**
|
31 | * Set `true` to enable HTML tags in source. Be careful!
|
32 | * That's not safe! You may need external sanitizer to protect output from XSS.
|
33 | * It's better to extend features via plugins, instead of enabling HTML.
|
34 | * @default false
|
35 | */
|
36 | html?: boolean | undefined;
|
37 |
|
38 | /**
|
39 | * Set `true` to add '/' when closing single tags
|
40 | * (`<br />`). This is needed only for full CommonMark compatibility. In real
|
41 | * world you will need HTML output.
|
42 | * @default false
|
43 | */
|
44 | xhtmlOut?: boolean | undefined;
|
45 |
|
46 | /**
|
47 | * Set `true` to convert `\n` in paragraphs into `<br>`.
|
48 | * @default false
|
49 | */
|
50 | breaks?: boolean | undefined;
|
51 |
|
52 | /**
|
53 | * CSS language class prefix for fenced blocks.
|
54 | * Can be useful for external highlighters.
|
55 | * @default 'language-'
|
56 | */
|
57 | langPrefix?: string | undefined;
|
58 |
|
59 | /**
|
60 | * Set `true` to autoconvert URL-like text to links.
|
61 | * @default false
|
62 | */
|
63 | linkify?: boolean | undefined;
|
64 |
|
65 | /**
|
66 | * Set `true` to enable [some language-neutral replacement](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.js) +
|
67 | * quotes beautification (smartquotes).
|
68 | * @default false
|
69 | */
|
70 | typographer?: boolean | undefined;
|
71 |
|
72 | /**
|
73 | * Double + single quotes replacement
|
74 | * pairs, when typographer enabled and smartquotes on. For example, you can
|
75 | * use `'«»„“'` for Russian, `'„“‚‘'` for German, and
|
76 | * `['«\xA0', '\xA0»', '‹\xA0', '\xA0›']` for French (including nbsp).
|
77 | * @default '“”‘’'
|
78 | */
|
79 | quotes?: string | string[];
|
80 |
|
81 | /**
|
82 | * Highlighter function for fenced code blocks.
|
83 | * Highlighter `function (str, lang, attrs)` should return escaped HTML. It can
|
84 | * also return empty string if the source was not changed and should be escaped
|
85 | * externally. If result starts with <pre... internal wrapper is skipped.
|
86 | * @default null
|
87 | */
|
88 | highlight?: ((str: string, lang: string, attrs: string) => string) | null | undefined;
|
89 | }
|
90 |
|
91 | type PluginSimple = (md: MarkdownIt) => void;
|
92 | type PluginWithOptions<T = any> = (md: MarkdownIt, options?: T) => void;
|
93 | type PluginWithParams = (md: MarkdownIt, ...params: any[]) => void;
|
94 | }
|
95 |
|
96 | interface MarkdownItConstructor {
|
97 | new (): MarkdownIt;
|
98 | new (presetName: MarkdownIt.PresetName, options?: MarkdownIt.Options): MarkdownIt;
|
99 | new (options: MarkdownIt.Options): MarkdownIt;
|
100 | (): MarkdownIt;
|
101 | (presetName: MarkdownIt.PresetName, options?: MarkdownIt.Options): MarkdownIt;
|
102 | (options: MarkdownIt.Options): MarkdownIt;
|
103 | }
|
104 |
|
105 | interface MarkdownIt {
|
106 | /**
|
107 | * Instance of [[ParserInline]]. You may need it to add new rules when
|
108 | * writing plugins. For simple rules control use [[MarkdownIt.disable]] and
|
109 | * [[MarkdownIt.enable]].
|
110 | */
|
111 | readonly inline: ParserInline;
|
112 |
|
113 | /**
|
114 | * Instance of [[ParserBlock]]. You may need it to add new rules when
|
115 | * writing plugins. For simple rules control use [[MarkdownIt.disable]] and
|
116 | * [[MarkdownIt.enable]].
|
117 | */
|
118 | readonly block: ParserBlock;
|
119 |
|
120 | /**
|
121 | * Instance of [[Core]] chain executor. You may need it to add new rules when
|
122 | * writing plugins. For simple rules control use [[MarkdownIt.disable]] and
|
123 | * [[MarkdownIt.enable]].
|
124 | */
|
125 | readonly core: ParserCore;
|
126 |
|
127 | /**
|
128 | * Instance of [[Renderer]]. Use it to modify output look. Or to add rendering
|
129 | * rules for new token types, generated by plugins.
|
130 | *
|
131 | * ##### Example
|
132 | *
|
133 | * ```javascript
|
134 | * var md = require('markdown-it')();
|
135 | *
|
136 | * function myToken(tokens, idx, options, env, self) {
|
137 | * //...
|
138 | * return result;
|
139 | * };
|
140 | *
|
141 | * md.renderer.rules['my_token'] = myToken
|
142 | * ```
|
143 | *
|
144 | * See [[Renderer]] docs and [source code](https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js).
|
145 | */
|
146 | readonly renderer: Renderer;
|
147 |
|
148 | /**
|
149 | * [linkify-it](https://github.com/markdown-it/linkify-it) instance.
|
150 | * Used by [linkify](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/linkify.js)
|
151 | * rule.
|
152 | */
|
153 | readonly linkify: LinkifyIt.LinkifyIt;
|
154 |
|
155 | /**
|
156 | * Link validation function. CommonMark allows too much in links. By default
|
157 | * we disable `javascript:`, `vbscript:`, `file:` schemas, and almost all `data:...` schemas
|
158 | * except some embedded image types.
|
159 | *
|
160 | * You can change this behaviour:
|
161 | *
|
162 | * ```javascript
|
163 | * var md = require('markdown-it')();
|
164 | * // enable everything
|
165 | * md.validateLink = function () { return true; }
|
166 | * ```
|
167 | */
|
168 | validateLink(url: string): boolean;
|
169 |
|
170 | /**
|
171 | * Function used to encode link url to a machine-readable format,
|
172 | * which includes url-encoding, punycode, etc.
|
173 | */
|
174 | normalizeLink(url: string): string;
|
175 |
|
176 | /**
|
177 | * Function used to decode link url to a human-readable format`
|
178 | */
|
179 | normalizeLinkText(url: string): string;
|
180 |
|
181 | readonly utils: typeof utils;
|
182 |
|
183 | readonly helpers: typeof helpers;
|
184 |
|
185 | readonly options: MarkdownIt.Options;
|
186 |
|
187 | /**
|
188 | * *chainable*
|
189 | *
|
190 | * Set parser options (in the same format as in constructor). Probably, you
|
191 | * will never need it, but you can change options after constructor call.
|
192 | *
|
193 | * ##### Example
|
194 | *
|
195 | * ```javascript
|
196 | * var md = require('markdown-it')()
|
197 | * .set({ html: true, breaks: true })
|
198 | * .set({ typographer: true });
|
199 | * ```
|
200 | *
|
201 | * __Note:__ To achieve the best possible performance, don't modify a
|
202 | * `markdown-it` instance options on the fly. If you need multiple configurations
|
203 | * it's best to create multiple instances and initialize each with separate
|
204 | * config.
|
205 | */
|
206 | set(options: MarkdownIt.Options): this;
|
207 |
|
208 | /**
|
209 | * *chainable*, *internal*
|
210 | *
|
211 | * Batch load of all options and compenent settings. This is internal method,
|
212 | * and you probably will not need it. But if you with - see available presets
|
213 | * and data structure [here](https://github.com/markdown-it/markdown-it/tree/master/lib/presets)
|
214 | *
|
215 | * We strongly recommend to use presets instead of direct config loads. That
|
216 | * will give better compatibility with next versions.
|
217 | */
|
218 | configure(presets: MarkdownIt.PresetName): this;
|
219 |
|
220 | /**
|
221 | * *chainable*
|
222 | *
|
223 | * Enable list or rules. It will automatically find appropriate components,
|
224 | * containing rules with given names. If rule not found, and `ignoreInvalid`
|
225 | * not set - throws exception.
|
226 | *
|
227 | * ##### Example
|
228 | *
|
229 | * ```javascript
|
230 | * var md = require('markdown-it')()
|
231 | * .enable(['sub', 'sup'])
|
232 | * .disable('smartquotes');
|
233 | * ```
|
234 | *
|
235 | * @param list rule name or list of rule names to enable
|
236 | * @param ignoreInvalid set `true` to ignore errors when rule not found.
|
237 | */
|
238 | enable(list: string | string[], ignoreInvalid?: boolean): this;
|
239 |
|
240 | /**
|
241 | * *chainable*
|
242 | *
|
243 | * The same as [[MarkdownIt.enable]], but turn specified rules off.
|
244 | *
|
245 | * @param list rule name or list of rule names to disable.
|
246 | * @param ignoreInvalid set `true` to ignore errors when rule not found.
|
247 | */
|
248 | disable(list: string | string[], ignoreInvalid?: boolean): this;
|
249 |
|
250 | /**
|
251 | * *chainable*
|
252 | *
|
253 | * Load specified plugin with given params into current parser instance.
|
254 | * It's just a sugar to call `plugin(md, params)` with curring.
|
255 | *
|
256 | * ##### Example
|
257 | *
|
258 | * ```javascript
|
259 | * var iterator = require('markdown-it-for-inline');
|
260 | * var md = require('markdown-it')()
|
261 | * .use(iterator, 'foo_replace', 'text', function (tokens, idx) {
|
262 | * tokens[idx].content = tokens[idx].content.replace(/foo/g, 'bar');
|
263 | * });
|
264 | * ```
|
265 | */
|
266 | use(plugin: MarkdownIt.PluginSimple): this;
|
267 | use<T = any>(plugin: MarkdownIt.PluginWithOptions<T>, options?: T): this;
|
268 | use(plugin: MarkdownIt.PluginWithParams, ...params: any[]): this;
|
269 |
|
270 | /**
|
271 | * *internal*
|
272 | *
|
273 | * Parse input string and returns list of block tokens (special token type
|
274 | * "inline" will contain list of inline tokens). You should not call this
|
275 | * method directly, until you write custom renderer (for example, to produce
|
276 | * AST).
|
277 | *
|
278 | * `env` is used to pass data between "distributed" rules and return additional
|
279 | * metadata like reference info, needed for the renderer. It also can be used to
|
280 | * inject data in specific cases. Usually, you will be ok to pass `{}`,
|
281 | * and then pass updated object to renderer.
|
282 | *
|
283 | * @param src source string
|
284 | * @param env environment sandbox
|
285 | */
|
286 | parse(src: string, env: any): Token[];
|
287 |
|
288 | /**
|
289 | * Render markdown string into html. It does all magic for you :).
|
290 | *
|
291 | * `env` can be used to inject additional metadata (`{}` by default).
|
292 | * But you will not need it with high probability. See also comment
|
293 | * in [[MarkdownIt.parse]].
|
294 | *
|
295 | * @param src source string
|
296 | * @param env environment sandbox
|
297 | */
|
298 | render(src: string, env?: any): string;
|
299 |
|
300 | /**
|
301 | * *internal*
|
302 | *
|
303 | * The same as [[MarkdownIt.parse]] but skip all block rules. It returns the
|
304 | * block tokens list with the single `inline` element, containing parsed inline
|
305 | * tokens in `children` property. Also updates `env` object.
|
306 | *
|
307 | * @param src source string
|
308 | * @param env environment sandbox
|
309 | */
|
310 | parseInline(src: string, env: any): Token[];
|
311 |
|
312 | /**
|
313 | * Similar to [[MarkdownIt.render]] but for single paragraph content. Result
|
314 | * will NOT be wrapped into `<p>` tags.
|
315 | *
|
316 | * @param src source string
|
317 | * @param env environment sandbox
|
318 | */
|
319 | renderInline(src: string, env?: any): string;
|
320 | }
|
321 |
|
322 | /**
|
323 | * Main parser/renderer class.
|
324 | *
|
325 | * ##### Usage
|
326 | *
|
327 | * ```javascript
|
328 | * // node.js, "classic" way:
|
329 | * var MarkdownIt = require('markdown-it'),
|
330 | * md = new MarkdownIt();
|
331 | * var result = md.render('# markdown-it rulezz!');
|
332 | *
|
333 | * // node.js, the same, but with sugar:
|
334 | * var md = require('markdown-it')();
|
335 | * var result = md.render('# markdown-it rulezz!');
|
336 | *
|
337 | * // browser without AMD, added to "window" on script load
|
338 | * // Note, there are no dash.
|
339 | * var md = window.markdownit();
|
340 | * var result = md.render('# markdown-it rulezz!');
|
341 | * ```
|
342 | *
|
343 | * Single line rendering, without paragraph wrap:
|
344 | *
|
345 | * ```javascript
|
346 | * var md = require('markdown-it')();
|
347 | * var result = md.renderInline('__markdown-it__ rulezz!');
|
348 | * ```
|
349 | *
|
350 | * ##### Example
|
351 | *
|
352 | * ```javascript
|
353 | * // commonmark mode
|
354 | * var md = require('markdown-it')('commonmark');
|
355 | *
|
356 | * // default mode
|
357 | * var md = require('markdown-it')();
|
358 | *
|
359 | * // enable everything
|
360 | * var md = require('markdown-it')({
|
361 | * html: true,
|
362 | * linkify: true,
|
363 | * typographer: true
|
364 | * });
|
365 | * ```
|
366 | *
|
367 | * ##### Syntax highlighting
|
368 | *
|
369 | * ```js
|
370 | * var hljs = require('highlight.js') // https://highlightjs.org/
|
371 | *
|
372 | * var md = require('markdown-it')({
|
373 | * highlight: function (str, lang) {
|
374 | * if (lang && hljs.getLanguage(lang)) {
|
375 | * try {
|
376 | * return hljs.highlight(lang, str, true).value;
|
377 | * } catch (__) {}
|
378 | * }
|
379 | *
|
380 | * return ''; // use external default escaping
|
381 | * }
|
382 | * });
|
383 | * ```
|
384 | *
|
385 | * Or with full wrapper override (if you need assign class to `<pre>`):
|
386 | *
|
387 | * ```javascript
|
388 | * var hljs = require('highlight.js') // https://highlightjs.org/
|
389 | *
|
390 | * // Actual default values
|
391 | * var md = require('markdown-it')({
|
392 | * highlight: function (str, lang) {
|
393 | * if (lang && hljs.getLanguage(lang)) {
|
394 | * try {
|
395 | * return '<pre class="hljs"><code>' +
|
396 | * hljs.highlight(lang, str, true).value +
|
397 | * '</code></pre>';
|
398 | * } catch (__) {}
|
399 | * }
|
400 | *
|
401 | * return '<pre class="hljs"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
|
402 | * }
|
403 | * });
|
404 | * ```
|
405 | */
|
406 | declare const MarkdownIt: MarkdownItConstructor;
|
407 |
|
408 | export = MarkdownIt;
|