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