VS Code Markdown Language Service
❗ Note this project is actively being developed and not yet ready for production use!
The language service that powers VS Code's Markdown support, extracted so that it can be reused by other editors and tools.
Features
This library targets CommonMark. Support for other Markdown dialects and extensions is not within the scope of this project.
Currently supported language features:
-
Document links (clickable spans in the editor)
Supported links include:
- Links to headers within the current file:
[text](#header) - Absolute and relative links to files:
[text](path/to/file.md) - Reference links:
[text][link-name]
- Links to headers within the current file:
-
Document symbols
Finds all headers within a markdown file
-
Workspace symbols
Find all headers across all markdown files in the workspace.
-
Folding ranges
Folding ranges are computed for:
- Header sections
- Region sections
- Lists
- Block elements
-
Smart select (expand selection)
-
Completions
Supports completions for:
- Links to headers
- Path links
- Reference links
-
Find all references
Supports finding references to:
- Headers
- Path links
- Fragments in links
- Reference links
-
Definitions
Supports finding definitions headers and reference links.
-
Renames
Supports renaming of headers and links.
Usage
To get started using this library, first install it into your workspace:
npm install vscode-markdown-languageservice
To use the language service, first you need to create an instance of it using createLanguageService. We use dependency injection to allow the language service to be used in as many contexts as possible.
import * as md from 'vscode-markdown-languageservice';
// Implement these
const parser: md.IMdParser = ...;
const workspace: md.IWorkspace = ...;
const logger: md.ILogger = ...;
const languageService = md.createLanguageService({ workspace, parser, logger });
After creating the service, you can ask it for the language features it supports:
// We're using the vscode-language types in this demo
// If you want to use them, make sure to run:
//
// npm install vscode-languageserver vscode-languageserver-textdocument
//
// However you can also bring your own types if you want to instead.
import { CancellationTokenSource } from 'vscode-languageserver';
import { TextDocument } from 'vscode-languageserver-textdocument';
const cts = new CancellationTokenSource();
// Create a virtual document that holds our file content
const myDocument = TextDocument.create(
URI.file('/path/to/file.md').toString(), // file path
'markdown', // file language
1, // version
[ // File contents
'# Hello',
'from **Markdown**',
'',
'## World!',
].join('\n')
);
const symbols = await languageService.getDocumentSymbols(myDocument, cts.token);
See example.cjs for complete, minimal example of using the language service. You can run in using node example.cjs.
Additional Links
- VS Code's Markdown language server
- The TextMate grammar VS Code uses for Markdown syntax highlighting
Contributing
If you're interested in contributing
- Clone this repo
- Install dependencies using
npm install - Start compilation using
npm run watch
You can run the unit tests using npm test or by opening the project in VS Code and pressing F5 to debug.
![markdown link in format [`abc`] not shown as link](https://avatars.githubusercontent.com/u/3254987?v=4)
21 Aug 25, 2022
16 Nov 27, 2022
5 Nov 12, 2022
17 Sep 27, 2022
25 Sep 4, 2022
11.6k Jan 7, 2023
8 Aug 5, 2022
25 Dec 20, 2022
24 Jan 1, 2023
65 Nov 2, 2022
585 Dec 31, 2022
5 Sep 24, 2022
36 Oct 5, 2022
20 Oct 12, 2022
6 Oct 5, 2022
18 Nov 21, 2022
17 Dec 2, 2022
7 Dec 13, 2022
91 Jan 2, 2023