Skip to content

Commit

Permalink
Add improved docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Jun 26, 2022
1 parent c3f827f commit b19a01f
Showing 1 changed file with 161 additions and 32 deletions.
193 changes: 161 additions & 32 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,32 @@
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**[micromark][]** extension to support GitHub flavored markdown (GFM) [literal
autolinks][].
[micromark][] extension support GFM [literal autolinks][spec].

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`gfmAutolinkLiteral`](#gfmautolinkliteral)
* [`gfmAutolinkLiteralHtml`](#gfmautolinkliteralhtml)
* [Authoring](#authoring)
* [HTML](#html)
* [CSS](#css)
* [Syntax](#syntax)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a micromark extension to add support for GFM literal autolinks.
This package contains extensions that add support for the autolink syntax
enabled by GFM to [`micromark`][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).
Expand All @@ -23,29 +43,27 @@ 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`][mdast-autolink-literal].
The second algorithm is performed by [`mdast-util-gfm-autolink-literal`][util].
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

In many cases, when working with micromark, you’d want to use
[`micromark-extension-gfm`][micromark-extension-gfm] instead, which combines
this package with other GFM features.
These tools are all low-level.
In many cases, you want to use [`remark-gfm`][plugin] with remark instead.

When working with syntax trees, you’d want to combine this package with
[`mdast-util-gfm-autolink-literal`][mdast-autolink-literal] (or
[`mdast-util-gfm`][mdast-util-gfm] when using `micromark-extension-gfm`).
Even when you want to use `micromark`, you likely want to use
[`micromark-extension-gfm`][micromark-extension-gfm] to support all GFM
features.
That extension includes this extension.

These tools are all rather low-level.
In most cases, you’d instead want to use [`remark-gfm`][remark-gfm] with
[remark][].
When working with `mdast-util-from-markdown`, you must combine this package with
[`mdast-util-gfm-autolink-literal`][util].

## Install

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

```sh
npm install micromark-extension-gfm-autolink-literal
Expand Down Expand Up @@ -90,46 +108,153 @@ Yields:

## API

This package exports the following identifiers: `gfmAutolinkLiteral`,
This package exports the identifiers `gfmAutolinkLiteral` and
`gfmAutolinkLiteralHtml`.
There is no default export.

The export map supports the endorsed
[`development` condition](https://nodejs.org/api/packages.html#packages_resolving_user_conditions).
The export map supports the endorsed [`development` condition][condition]).
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `gfmAutolinkLiteral`

An extension for micromark to parse GFM autolink literals (can be passed in
`extensions`).
Syntax extension for micromark (passed in `extensions`).

### `gfmAutolinkLiteralHtml`

An extension to compile them to HTML (can be passed in `htmlExtensions`).
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):

```markdown
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*][html] 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][css]:

```css
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:

```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][].
There are no additional exported types.
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+, and 16.0+.
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`][mdast-autolink-literal]
* [`syntax-tree/mdast-util-gfm-autolink-literal`][util]
— support GFM autolink literals in mdast
* [`syntax-tree/mdast-util-gfm`][mdast-util-gfm]
— support GFM in mdast
* [`remarkjs/remark-gfm`][remark-gfm]
* [`remarkjs/remark-gfm`][plugin]
— support GFM in remark

## Contribute
Expand Down Expand Up @@ -192,16 +317,20 @@ abide by its terms.

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark
[condition]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[remark]: https://github.com/remarkjs/remark
[util]: https://github.com/syntax-tree/mdast-util-gfm-autolink-literal

[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm
[plugin]: https://github.com/remarkjs/remark-gfm

[mdast-autolink-literal]: https://github.com/syntax-tree/mdast-util-gfm-autolink-literal
[spec]: https://github.github.com/gfm/#autolinks-extension-

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm
[html]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element

[css]: https://github.com/sindresorhus/github-markdown-css

[micromark]: https://github.com/micromark/micromark

[remark-gfm]: https://github.com/remarkjs/remark-gfm
[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm

[literal autolinks]: https://github.github.com/gfm/#autolinks-extension-
[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

0 comments on commit b19a01f

Please sign in to comment.