Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: 14 days ago
JSON representation
Customize linkification for Markdown preview in VS Code.
- Host: GitHub
- URL: https://github.com/tomtung/vscode-markdown-linkify
- Owner: tomtung
- License: apache-2.0
- Created: 2022-06-14T05:02:24.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-07-26T09:30:20.000Z (over 2 years ago)
- Last Synced: 2024-10-05T21:07:40.202Z (5 months ago)
- Topics: linkify-it, markdown, markdown-previewer, vscode, vscode-extension
- Language: TypeScript
- Homepage: https://marketplace.visualstudio.com/items?itemName=tomtung.vscode-markdown-linkify
- Size: 156 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# VS Code: Custom Linkification in Markdown Preview
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.