Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tomtung/vscode-markdown-linkify

Customize linkification for Markdown preview in VS Code.
https://github.com/tomtung/vscode-markdown-linkify

linkify-it markdown markdown-previewer vscode vscode-extension

Last synced: 13 days ago
JSON representation

Customize linkification for Markdown preview in VS Code.

Awesome Lists containing this project

README

        

# VS Code: Custom Linkification in Markdown Preview

![](docs/demo.png)

This extension customizes automatic linkification of texts rendered in Markdown Preview.

## Extension Settings

By adding rules to the `"markdown-linkify.rules"` settings, the user can specify how links with custom formats are matched, linked, and rendered.

The value of `"markdown-linkify.rules"` is a list of custom linkification rules, each represented by a JSON object with 4 members:
```typescript
interface Rule {
prefix: string
tail?: string
url?: string
text?: string
}
```
- `prefix`: the prefix of link strings to be matched, most typically a protocol name that ends with `:` (like `skype:`). The match is automatically ensured to not be preceded by an alphanumeric character.
- `tail`: an optional regex for matching the **remainder** of the link string immediately following the prefix. The match is automatically ensured to be immediately followed by either space or punctuation. *If not provided, defaults to matching URI-path-like strings.*
- `url`: an optional string template for the rendered link's URL. *If not provided, defaults to the matched link string, possibly prepended by `http://`.*
- `text`: an optional string template for the rendered link text. *If not provided, defaults to the matched link string.*

Both template strings can contain placeholders of matched (sub)strings (`%MATCH%`, `%PREFIX%`, and `%TAIL%`) and backreferences (`$1`, `$2`, ...) to capturing groups from the `tail` regex. The placeholder `%MATCH%` is replaced with the entirety of the matched link string, while `%PREFIX%` only the prefix part, `%TAIL%` only the tail part.

## Examples

The custom linkification demonstrated in the screenshot above is enabled by the following setting:

```json
{
"markdown-linkify.rules": [
{ "prefix": "skype:" },
{ "prefix": "goto/" },
{
"prefix": "@",
"tail": "([a-zA-Z0-9_]){1,15}(?!_)",
"url": "https://twitter.com/%TAIL%"
},
{
"prefix": "gh-issue:",
"tail": "([a-zA-Z\\d](?:[a-zA-Z\\d]|-(?=[a-zA-Z\\d]))+)\/([a-zA-Z.\\-_]+)(?:#(\\d+))",
"url": "https://github.com/$1/$2/issues/$3",
"text": "%TAIL%"
}
]
}
```

Let's break it down in the following sections.

### Custom URI Scheme

With the first simple rule:

```json
{ "prefix": "skype:" }
```

the text

```
Do you still use Skype? Call me at: skype:echo123?call.
```

is rendered to

>

Do you still use Skype? Call me at: skype:echo123?call.

### Non-URI Link Prefix

Similarly, with the rule:

```json
{ "prefix": "goto/" }
```

the text

```
Here's an internal short link: goto/link.
It may get quite complex (goto/abc/1;2,3?x=4&y=5)!
```

is rendered to

>

Here's an internal short link: goto/link. It may get quite complex (goto/abc/1;2,3?x=4&y=5)!

Here since `goto/` doesn't look like a valid URI prefix, `http://` is automatically prepended to the link URL by default.

### Matching with Regex, Linking with Template
The next rule matches Twitter handles using regex, and constructs link URLs using a template string.
```json
{
"prefix": "@",
"tail": "([a-zA-Z0-9_]){1,15}(?!_)",
"url": "https://twitter.com/%TAIL%"
}
```

With this rule, the text

```
This is a Twitter handle @jack.
Not to be confused with an Email address [email protected].
```

is rendered to
>

This is a Twitter handle @jack. Not to be confused with an Email address [email protected].

### Overriding Link Text

The final rule demonstrates a more advanced use case: in addition to matching the tail with a regex and constructing the link URL with backreferences to capturing groups in the regex, it also drops the prefix string when rendering the link text.

```json
{
"prefix": "gh-issue:",
"tail": "([a-zA-Z\\d](?:[a-zA-Z\\d]|-(?=[a-zA-Z\\d]))+)\/([a-zA-Z.\\-_]+)(?:#(\\d+))",
"url": "https://github.com/$1/$2/issues/$3",
"text": "%TAIL%"
}
```

With this rule, the following text:

```
I invented this custom link format for GitHub issues:
gh-issue:tomtung/vscode-markdown-linkify#123.
```

is rendered to

>

I invented this custom link format for GitHub issues: tomtung/vscode-markdown-linkify#123.

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.

## License

Apache 2.0; see [`LICENSE.txt`](LICENSE.txt) for details.

## Disclaimer

This project is not an official Google project. It is not supported by Google and Google specifically disclaims all warranties as to its quality, merchantability, or fitness for a particular purpose.