Repository files navigation

mdast extensions to parse and serializeGFM autolink literals.

• What is this?
• When to use this
• Install
• Use
• API
  • gfmAutolinkLiteralFromMarkdown()
  • gfmAutolinkLiteralToMarkdown()
• HTML
• Syntax
• Syntax tree
• Types
• Compatibility
• Related
• Contribute
• License

This package contains two extensions that add support for GFM autolink literalssyntax in markdown tomdast.These extensions plug intomdast-util-from-markdown (to support parsingGFM autolinks in markdown into a syntax tree) andmdast-util-to-markdown (to support serializingGFM autolinks in syntax trees to markdown).

GitHub employs different algorithms to autolink: one at parse time and one attransform time (similar to how@mentions are done at transform time).This difference can be observed because character references and escapes arehandled differently.But also because issues/PRs/comments omit (perhaps by accident?) the secondalgorithm forwww.,http://, andhttps:// links (but not for email links).

As the corresponding micromark extensionmicromark-extension-gfm-autolink-literal is a syntax extension,it can only perform the first algorithm.The tree extensiongfmAutolinkLiteralFromMarkdown from this package canperform the second algorithm, and as they are combined, both are done.

You can use these extensions when you are working withmdast-util-from-markdown andmdast-util-to-markdown already.

When working withmdast-util-from-markdown, you must combine this packagewithmicromark-extension-gfm-autolink-literal.

When you don’t need a syntax tree, you can usemicromarkdirectly withmicromark-extension-gfm-autolink-literal.

When you are working with syntax trees and want all of GFM, usemdast-util-gfm instead.

All these packages are usedremark-gfm, whichfocusses on making it easier to transform content by abstracting theseinternals away.

This utility does not handle how markdown is turned to HTML.That’s done bymdast-util-to-hast.

This package isESM only.In Node.js (version 16+), install withnpm:

npm install mdast-util-gfm-autolink-literal

In Deno withesm.sh:

import{gfmAutolinkLiteralFromMarkdown,gfmAutolinkLiteralToMarkdown}from'https://esm.sh/mdast-util-gfm-autolink-literal@2'

In browsers withesm.sh:

<scripttype="module">import{gfmAutolinkLiteralFromMarkdown,gfmAutolinkLiteralToMarkdown}from'https://esm.sh/mdast-util-gfm-autolink-literal@2?bundle'</script>

Say our documentexample.md contains:

www.example.com,https://example.com, andcontact@example.com.

…and our moduleexample.js looks as follows:

importfsfrom'node:fs/promises'import{gfmAutolinkLiteral}from'micromark-extension-gfm-autolink-literal'import{fromMarkdown}from'mdast-util-from-markdown'import{gfmAutolinkLiteralFromMarkdown,gfmAutolinkLiteralToMarkdown}from'mdast-util-gfm-autolink-literal'import{toMarkdown}from'mdast-util-to-markdown'constdocument=awaitfs.readFile('example.md','utf8')consttree=fromMarkdown(document,{extensions:[gfmAutolinkLiteral()],mdastExtensions:[gfmAutolinkLiteralFromMarkdown()]})console.log(tree)constout=toMarkdown(tree,{extensions:[gfmAutolinkLiteralToMarkdown()]})console.log(out)

…now runningnode example.js yields (positional info removed for brevity):

{type:'root',children:[{type:'paragraph',children:[{type:'link',title:null,url:'http://www.example.com',children:[{type:'text',value:'www.example.com'}]},{type:'text',value:', '},{type:'link',title:null,url:'https://example.com',children:[{type:'text',value:'https://example.com'}]},{type:'text',value:', and '},{type:'link',title:null,url:'mailto:contact@example.com',children:[{type:'text',value:'contact@example.com'}]},{type:'text',value:'.'}]}]}

[www.example.com](http://www.example.com),<https://example.com>, and<contact@example.com>.

This package exports the identifiersgfmAutolinkLiteralFromMarkdown andgfmAutolinkLiteralToMarkdown.There is no default export.

Create an extension formdast-util-from-markdownto enable GFM autolink literals in markdown.

Extension formdast-util-to-markdown to enable GFM autolink literals(FromMarkdownExtension).

Create an extension formdast-util-to-markdown toenable GFM autolink literals in markdown.

Extension formdast-util-to-markdown to enable GFM autolink literals(ToMarkdownExtension).

This utility does not handle how markdown is turned to HTML.That’s done bymdast-util-to-hast.

SeeSyntax inmicromark-extension-gfm-autolink-literal.

There are no interfaces added tomdast by this utility, as it reusesthe existingLink interface.

This package is fully typed withTypeScript.It does not export additional types.

TheLink type of the mdast nodes is exposed from@types/mdast.

Projects maintained by the unified collective are compatible with maintainedversions of Node.js.

When we cut a new major release, we drop support for unmaintained versions ofNode.This means we try to keep the current release line,mdast-util-gfm-autolink-literal@^2, compatible with Node.js 16.

This utility works withmdast-util-from-markdown version 2+ andmdast-util-to-markdown version 2+.

• remarkjs/remark-gfm— remark plugin to support GFM
• syntax-tree/mdast-util-gfm— same but all of GFM (autolink literals, footnotes, strikethrough, tables,tasklists)
• micromark/micromark-extension-gfm-autolink-literal— micromark extension to parse GFM autolink literals

Seecontributing.md insyntax-tree/.github forways to get started.Seesupport.md for ways to get help.

This project has acode of conduct.By interacting with this repository, organization, or community you agree toabide by its terms.

MIT ©Titus Wormer