233 lines
8.1 KiB
TypeScript
233 lines
8.1 KiB
TypeScript
|
/**
|
|||
|
|
* Create `state` from an mdast tree.
|
|||
|
|
*
|
|||
|
|
* @param {MdastNodes} tree
|
|||
|
|
* mdast node to transform.
|
|||
|
|
* @param {Options | null | undefined} [options]
|
|||
|
|
* Configuration (optional).
|
|||
|
|
* @returns {State}
|
|||
|
|
* `state` function.
|
|||
|
|
*/
|
|||
|
|
export function createState(tree: MdastNodes, options?: Options | null | undefined): State;
|
|||
|
|
/**
|
|||
|
|
* Wrap `nodes` with line endings between each node.
|
|||
|
|
*
|
|||
|
|
* @template {HastRootContent} Type
|
|||
|
|
* Node type.
|
|||
|
|
* @param {Array<Type>} nodes
|
|||
|
|
* List of nodes to wrap.
|
|||
|
|
* @param {boolean | undefined} [loose=false]
|
|||
|
|
* Whether to add line endings at start and end (default: `false`).
|
|||
|
|
* @returns {Array<HastText | Type>}
|
|||
|
|
* Wrapped nodes.
|
|||
|
|
*/
|
|||
|
|
export function wrap<Type extends import("hast").RootContent>(nodes: Type[], loose?: boolean | undefined): (import("hast").Text | Type)[];
|
|||
|
|
export type HastElement = import('hast').Element;
|
|||
|
|
export type HastElementContent = import('hast').ElementContent;
|
|||
|
|
export type HastNodes = import('hast').Nodes;
|
|||
|
|
export type HastProperties = import('hast').Properties;
|
|||
|
|
export type HastRootContent = import('hast').RootContent;
|
|||
|
|
export type HastText = import('hast').Text;
|
|||
|
|
export type MdastDefinition = import('mdast').Definition;
|
|||
|
|
export type MdastFootnoteDefinition = import('mdast').FootnoteDefinition;
|
|||
|
|
export type MdastNodes = import('mdast').Nodes;
|
|||
|
|
export type MdastParents = import('mdast').Parents;
|
|||
|
|
export type VFile = import('vfile').VFile;
|
|||
|
|
export type FootnoteBackContentTemplate = import('./footer.js').FootnoteBackContentTemplate;
|
|||
|
|
export type FootnoteBackLabelTemplate = import('./footer.js').FootnoteBackLabelTemplate;
|
|||
|
|
/**
|
|||
|
|
* Handle a node.
|
|||
|
|
*/
|
|||
|
|
export type Handler = (state: State, node: any, parent: MdastParents | undefined) => Array<HastElementContent> | HastElementContent | undefined;
|
|||
|
|
/**
|
|||
|
|
* Handle nodes.
|
|||
|
|
*/
|
|||
|
|
export type Handlers = Partial<Record<MdastNodes['type'], Handler>>;
|
|||
|
|
/**
|
|||
|
|
* Configuration (optional).
|
|||
|
|
*/
|
|||
|
|
export type Options = {
|
|||
|
|
/**
|
|||
|
|
* Whether to persist raw HTML in markdown in the hast tree (default:
|
|||
|
|
* `false`).
|
|||
|
|
*/
|
|||
|
|
allowDangerousHtml?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Prefix to use before the `id` property on footnotes to prevent them from
|
|||
|
|
* *clobbering* (default: `'user-content-'`).
|
|||
|
|
*
|
|||
|
|
* Pass `''` for trusted markdown and when you are careful with
|
|||
|
|
* polyfilling.
|
|||
|
|
* You could pass a different prefix.
|
|||
|
|
*
|
|||
|
|
* DOM clobbering is this:
|
|||
|
|
*
|
|||
|
|
* ```html
|
|||
|
|
* <p id="x"></p>
|
|||
|
|
* <script>alert(x) // `x` now refers to the `p#x` DOM element</script>
|
|||
|
|
* ```
|
|||
|
|
*
|
|||
|
|
* The above example shows that elements are made available by browsers, by
|
|||
|
|
* their ID, on the `window` object.
|
|||
|
|
* This is a security risk because you might be expecting some other variable
|
|||
|
|
* at that place.
|
|||
|
|
* It can also break polyfills.
|
|||
|
|
* Using a prefix solves these problems.
|
|||
|
|
*/
|
|||
|
|
clobberPrefix?: string | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Corresponding virtual file representing the input document (optional).
|
|||
|
|
*/
|
|||
|
|
file?: VFile | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Content of the backreference back to references (default: `defaultFootnoteBackContent`).
|
|||
|
|
*
|
|||
|
|
* The default value is:
|
|||
|
|
*
|
|||
|
|
* ```js
|
|||
|
|
* function defaultFootnoteBackContent(_, rereferenceIndex) {
|
|||
|
|
* const result = [{type: 'text', value: '↩'}]
|
|||
|
|
*
|
|||
|
|
* if (rereferenceIndex > 1) {
|
|||
|
|
* result.push({
|
|||
|
|
* type: 'element',
|
|||
|
|
* tagName: 'sup',
|
|||
|
|
* properties: {},
|
|||
|
|
* children: [{type: 'text', value: String(rereferenceIndex)}]
|
|||
|
|
* })
|
|||
|
|
* }
|
|||
|
|
*
|
|||
|
|
* return result
|
|||
|
|
* }
|
|||
|
|
* ```
|
|||
|
|
*
|
|||
|
|
* This content is used in the `a` element of each backreference (the `↩`
|
|||
|
|
* links).
|
|||
|
|
*/
|
|||
|
|
footnoteBackContent?: FootnoteBackContentTemplate | string | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Label to describe the backreference back to references (default:
|
|||
|
|
* `defaultFootnoteBackLabel`).
|
|||
|
|
*
|
|||
|
|
* The default value is:
|
|||
|
|
*
|
|||
|
|
* ```js
|
|||
|
|
* function defaultFootnoteBackLabel(referenceIndex, rereferenceIndex) {
|
|||
|
|
* return (
|
|||
|
|
* 'Back to reference ' +
|
|||
|
|
* (referenceIndex + 1) +
|
|||
|
|
* (rereferenceIndex > 1 ? '-' + rereferenceIndex : '')
|
|||
|
|
* )
|
|||
|
|
* }
|
|||
|
|
* ```
|
|||
|
|
*
|
|||
|
|
* Change it when the markdown is not in English.
|
|||
|
|
*
|
|||
|
|
* This label is used in the `ariaLabel` property on each backreference
|
|||
|
|
* (the `↩` links).
|
|||
|
|
* It affects users of assistive technology.
|
|||
|
|
*/
|
|||
|
|
footnoteBackLabel?: FootnoteBackLabelTemplate | string | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Textual label to use for the footnotes section (default: `'Footnotes'`).
|
|||
|
|
*
|
|||
|
|
* Change it when the markdown is not in English.
|
|||
|
|
*
|
|||
|
|
* This label is typically hidden visually (assuming a `sr-only` CSS class
|
|||
|
|
* is defined that does that) and so affects screen readers only.
|
|||
|
|
* If you do have such a class, but want to show this section to everyone,
|
|||
|
|
* pass different properties with the `footnoteLabelProperties` option.
|
|||
|
|
*/
|
|||
|
|
footnoteLabel?: string | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Properties to use on the footnote label (default: `{className:
|
|||
|
|
* ['sr-only']}`).
|
|||
|
|
*
|
|||
|
|
* Change it to show the label and add other properties.
|
|||
|
|
*
|
|||
|
|
* This label is typically hidden visually (assuming an `sr-only` CSS class
|
|||
|
|
* is defined that does that) and so affects screen readers only.
|
|||
|
|
* If you do have such a class, but want to show this section to everyone,
|
|||
|
|
* pass an empty string.
|
|||
|
|
* You can also add different properties.
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: `id: 'footnote-label'` is always added, because footnote
|
|||
|
|
* > calls use it with `aria-describedby` to provide an accessible label.
|
|||
|
|
*/
|
|||
|
|
footnoteLabelProperties?: HastProperties | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* HTML tag name to use for the footnote label element (default: `'h2'`).
|
|||
|
|
*
|
|||
|
|
* Change it to match your document structure.
|
|||
|
|
*
|
|||
|
|
* This label is typically hidden visually (assuming a `sr-only` CSS class
|
|||
|
|
* is defined that does that) and so affects screen readers only.
|
|||
|
|
* If you do have such a class, but want to show this section to everyone,
|
|||
|
|
* pass different properties with the `footnoteLabelProperties` option.
|
|||
|
|
*/
|
|||
|
|
footnoteLabelTagName?: string | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Extra handlers for nodes (optional).
|
|||
|
|
*/
|
|||
|
|
handlers?: Handlers | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* List of custom mdast node types to pass through (keep) in hast (note that
|
|||
|
|
* the node itself is passed, but eventual children are transformed)
|
|||
|
|
* (optional).
|
|||
|
|
*/
|
|||
|
|
passThrough?: Array<MdastNodes['type']> | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Handler for all unknown nodes (optional).
|
|||
|
|
*/
|
|||
|
|
unknownHandler?: Handler | null | undefined;
|
|||
|
|
};
|
|||
|
|
/**
|
|||
|
|
* Info passed around.
|
|||
|
|
*/
|
|||
|
|
export type State = {
|
|||
|
|
/**
|
|||
|
|
* Transform the children of an mdast parent to hast.
|
|||
|
|
*/
|
|||
|
|
all: (node: MdastNodes) => Array<HastElementContent>;
|
|||
|
|
/**
|
|||
|
|
* Honor the `data` of `from`, and generate an element instead of `node`.
|
|||
|
|
*/
|
|||
|
|
applyData: <Type extends import("hast").Nodes>(from: MdastNodes, to: Type) => import("hast").Element | Type;
|
|||
|
|
/**
|
|||
|
|
* Definitions by their identifier.
|
|||
|
|
*/
|
|||
|
|
definitionById: Map<string, MdastDefinition>;
|
|||
|
|
/**
|
|||
|
|
* Footnote definitions by their identifier.
|
|||
|
|
*/
|
|||
|
|
footnoteById: Map<string, MdastFootnoteDefinition>;
|
|||
|
|
/**
|
|||
|
|
* Counts for how often the same footnote was called.
|
|||
|
|
*/
|
|||
|
|
footnoteCounts: Map<string, number>;
|
|||
|
|
/**
|
|||
|
|
* Identifiers of order when footnote calls first appear in tree order.
|
|||
|
|
*/
|
|||
|
|
footnoteOrder: Array<string>;
|
|||
|
|
/**
|
|||
|
|
* Applied handlers.
|
|||
|
|
*/
|
|||
|
|
handlers: Handlers;
|
|||
|
|
/**
|
|||
|
|
* Transform an mdast node to hast.
|
|||
|
|
*/
|
|||
|
|
one: (node: MdastNodes, parent: MdastParents | undefined) => Array<HastElementContent> | HastElementContent | undefined;
|
|||
|
|
/**
|
|||
|
|
* Configuration.
|
|||
|
|
*/
|
|||
|
|
options: Options;
|
|||
|
|
/**
|
|||
|
|
* Copy a node’s positional info.
|
|||
|
|
*/
|
|||
|
|
patch: (from: MdastNodes, node: HastNodes) => undefined;
|
|||
|
|
/**
|
|||
|
|
* Wrap `nodes` with line endings between each node, adds initial/final line endings when `loose`.
|
|||
|
|
*/
|
|||
|
|
wrap: <Type_1 extends import("hast").RootContent>(nodes: Type_1[], loose?: boolean | undefined) => (import("hast").Text | Type_1)[];
|
|||
|
|
};
|