micromark-extension-gfm-autolink-literal

micromark extension to support GFM literal autolinks.

Contents

• What is this?
• When to use this
• Install
• Use
• API
  • gfmAutolinkLiteral
  • gfmAutolinkLiteralHtml
• Authoring
• HTML
• CSS
• Syntax
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package contains extensions that add support for the autolink syntax enabled by GFM to micromark.

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

As this is a syntax extension, it focuses on the first algorithm. The second algorithm is performed by mdast-util-gfm-autolink-literal. The html part of this micromark extension does not operate on an AST and hence can’t perform the second algorithm.

When to use this

These tools are all low-level. In many cases, you want to use remark-gfm with remark instead.

Even when you want to use micromark, you likely want to use micromark-extension-gfm to support all GFM features. That extension includes this extension.

When working with mdast-util-from-markdown, you must combine this package with mdast-util-gfm-autolink-literal.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with npm:

npm install micromark-extension-gfm-autolink-literal

In Deno with esm.sh:

import {gfmAutolinkLiteral, gfmAutolinkLiteralHtml} from 'https://esm.sh/micromark-extension-gfm-autolink-literal@1'

In browsers with esm.sh:

<script type="module">
  import {gfmAutolinkLiteral, gfmAutolinkLiteralHtml} from 'https://esm.sh/micromark-extension-gfm-autolink-literal@1?bundle'
</script>

Use

import {micromark} from 'micromark'
import {
  gfmAutolinkLiteral,
  gfmAutolinkLiteralHtml
} from 'micromark-extension-gfm-autolink-literal'

const output = micromark('Just a URL: www.example.com.', {
  extensions: [gfmAutolinkLiteral],
  htmlExtensions: [gfmAutolinkLiteralHtml]
})

console.log(output)

Yields:

<p>Just a URL: <a href="http://www.example.com">www.example.com</a>.</p>

API

This package exports the identifiers gfmAutolinkLiteral and gfmAutolinkLiteralHtml. There is no default export.

The export map supports the endorsed development condition. Run node --conditions development module.js to get instrumented dev code. Without this condition, production code is loaded.

gfmAutolinkLiteral

Syntax extension for micromark (passed in extensions).

gfmAutolinkLiteralHtml

HTML extension for micromark (can be passed in htmlExtensions).

Authoring

When authoring markdown, it’s recommended not to use this construct. It is fragile (easy to get wrong) and not pretty to readers (it’s presented as just a URL, there is no descriptive text). Instead, use link (resource) or link (label):

Instead of https://example.com (worst), use <https://example.com> (better),
or [link (resource)](https://example.com) or [link (reference)][ref] (best).

[ref]: https://example.com

When authoring markdown where the source does not matter (such as comments to some page), it can be useful to quickly paste URLs, and this will mostly work.

HTML

GFM autolink literals, similar to normal CommonMark autolinks (such as <https://example.com>), relate to the <a> element in HTML. See § 4.5.1 The a element in the HTML spec for more info. When an email autolink is used, the string mailto: is prepended before the email, when generating the href attribute of the hyperlink. When a www autolink is used, the string http:// is prepended.

CSS

As hyperlinks are the fundamental thing that makes the web, you will most definitely have CSS for a elements already. The same CSS can be used for autolink literals, too.

GitHub itself does not apply interesting CSS to autolink literals. For any link, it currently (June 2022) uses:

a {
  background-color: transparent;
  color: #58a6ff;
  text-decoration: none;
}

a:active,
a:hover {
  outline-width: 0;
}

a:hover {
  text-decoration: underline;
}

a:not([href]) {
  color: inherit;
  text-decoration: none;
}

Syntax

Autolink literals are very complex to parse. They form with, roughly, the following BNF:

; Restriction: not allowed to be in unbalanced braces.
autolink ::= www-autolink | http-autolink | email-autolink

; Restriction: the code before must be `www-autolink-before`.
www-autolink ::= 3( "w" | "W" ) "." [ domain [ path ] ]
www-autolink-before ::= eof | eol | space-or-tab | "(" | "*" | "_" | "~"

; Restriction: the code before must be `http-autolink-before`.
; Restriction: the code after the protocol must be `http-autolink-protocol-after`.
http-autolink ::= ( "h" | "H" ) 2( "t" | "T" ) ( "p" | "P" ) [ "s" | "S" ] ":" 2"/" domain [ path ]
http-autolink-before ::= code - ascii-alpha
http-autolink-protocol-after ::= code - eof - eol - ascii-control - unicode-whitespace - unicode-punctuation

; Restriction: the code before must be `email-autolink-before`.
; Restriction: `ascii-digit` may not occur in the last label part of the label.
email-autolink ::= 1*( "+" | "-" | "." | "_" | ascii-alphanumeric ) "@" 1*( 1*label-segment label-dot-cont ) 1*label-segment
email-autolink-before ::= code - ascii-alpha - "/"

; Restriction: `_` may not occur in the last two domain parts.
domain ::= 1*( url-ampt-cont | domain-punct-cont | "-" | code - eof - ascii-control - unicode-whitespace - unicode-punctuation )
; Restriction: must not be followed by `punct`.
domain-punct-cont ::= "." | "_"
; Restriction: must not be followed by `char-ref`.
url-ampt-cont ::= "&"

; Restriction: a counter `balance = 0` is increased for every `(`, and decreased for every `)`.
; Restriction: `)` must not be `paren-at-end`.
path ::= 1*( url-ampt-cont | path-punctuation-cont | "(" | ")" | code - eof - eol - space-or-tab )
; Restriction: must not be followed by `punct`.
path-punctuation-cont ::= trailing-punctuation - "<"
; Restriction: must be followed by `punct` and `balance` must be less than `0`.
paren-at-end ::= ")"

label-segment ::= label-dash-underscore-cont | ascii-alpha | ascii-digit
; Restriction: if followed by `punct`, the whole email autolink is invalid.
label-dash-underscore-cont ::= "-" | "_"
; Restriction: must not be followed by `punct`.
label-dot-cont ::= "."

punct ::= *trailing-punctuation ( code - eof - eol - space-or-tab - "<" )
char-ref ::= *ascii-alpha ";" path-end
trailing-punctuation ::= "!" | "\"" | "'" | ")" | "*" | "," | "." | ":" | ";" | "<" | '?' | '_' | '~'

Types

This package is fully typed with TypeScript. It exports no additional types.

Compatibility

This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+. It also works in Deno and modern browsers.

Security

This package is safe. Unlike other links in CommonMark, which allow arbitrary protocols, this construct always produces safe links.

Related

• syntax-tree/mdast-util-gfm-autolink-literal — support GFM autolink literals in mdast
• syntax-tree/mdast-util-gfm — support GFM in mdast
• remarkjs/remark-gfm — support GFM in remark

Contribute

See contributing.md in micromark/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer