From 9b06534813667d83d461984ac92543075793042b Mon Sep 17 00:00:00 2001
From: Luke Hagar <lukeslakemail@gmail.com>
Date: Tue, 11 Nov 2025 02:10:42 +0000
Subject: [PATCH 1/2] Templating out the start of a docs update

---
 astro.config.ts                               |  34 ++-
 .../{core-concepts => about}/why-volar.mdx    |   0
 .../core-concepts/language-definition.mdx     | 282 ++++++++++++++++++
 .../docs/core-concepts/service-definition.mdx |  71 +++++
 src/content/docs/guides/build-and-bundle.mdx  | 262 ++++++++++++++++
 src/content/docs/index.mdx                    |   2 +-
 src/content/docs/packages/cdn.mdx             |  31 ++
 src/content/docs/packages/coc-nvim.mdx        |  53 ++++
 src/content/docs/packages/code-gen.mdx        |  45 +++
 src/content/docs/packages/eslint.mdx          |  46 +++
 src/content/docs/packages/jsdelivr.mdx        |  27 ++
 src/content/docs/packages/kit.mdx             |  42 +++
 src/content/docs/packages/language-core.mdx   |  65 ++++
 src/content/docs/packages/language-hub.mdx    |  45 +++
 src/content/docs/packages/language-server.mdx |  64 ++++
 .../docs/packages/language-service.mdx        |  57 ++++
 src/content/docs/packages/monaco.mdx          |  45 +++
 src/content/docs/packages/preview.mdx         |  38 +++
 src/content/docs/packages/shared.mdx          |  35 +++
 .../docs/packages/snapshot-document.mdx       |  40 +++
 src/content/docs/packages/source-map.mdx      |  44 +++
 src/content/docs/packages/test-utils.mdx      |  38 +++
 src/content/docs/packages/transforms.mdx      |  35 +++
 src/content/docs/packages/tsl-config.mdx      |  35 +++
 .../docs/packages/typescript-faster.mdx       |  34 +++
 .../packages/typescript-language-service.mdx  |  40 +++
 src/content/docs/packages/typescript.mdx      |  43 +++
 src/content/docs/packages/vscode.mdx          |  45 +++
 src/content/docs/reference/languages.mdx      | 126 --------
 src/content/docs/reference/services.mdx       | 279 -----------------
 src/content/docs/service-methods/index.mdx    |  39 +++
 .../provide-call-hierarchy-incoming-calls.mdx |  19 ++
 .../provide-call-hierarchy-items.mdx          |  20 ++
 .../provide-call-hierarchy-outgoing-calls.mdx |  19 ++
 .../service-methods/provide-code-actions.mdx  |  41 +++
 .../service-methods/provide-code-lens.mdx     |  26 ++
 .../provide-color-presentations.mdx           |  22 ++
 .../provide-completion-items.mdx              |  44 +++
 .../service-methods/provide-definition.mdx    |  28 ++
 .../provide-document-colors.mdx               |  23 ++
 .../provide-document-formatting-edits.mdx     |  28 ++
 .../provide-document-highlights.mdx           |  26 ++
 .../provide-document-links.mdx                |  26 ++
 ...rovide-document-range-formatting-edits.mdx |  25 ++
 ...provide-document-semantic-tokens-edits.mdx |  16 +
 .../provide-document-semantic-tokens.mdx      |  25 ++
 .../provide-document-symbols.mdx              |  26 ++
 .../provide-folding-ranges.mdx                |  19 ++
 .../docs/service-methods/provide-hover.mdx    |  34 +++
 .../service-methods/provide-inlay-hints.mdx   |  26 ++
 .../provide-linked-editing-ranges.mdx         |  20 ++
 .../provide-on-type-formatting-edits.mdx      |  24 ++
 .../service-methods/provide-references.mdx    |  28 ++
 .../service-methods/provide-rename-edits.mdx  |  30 ++
 .../provide-selection-ranges.mdx              |  19 ++
 .../provide-signature-help.mdx                |  32 ++
 .../service-methods/resolve-code-action.mdx   |  34 +++
 .../service-methods/resolve-code-lens.mdx     |  25 ++
 .../resolve-completion-item.mdx               |  35 +++
 .../service-methods/resolve-document-link.mdx |  22 ++
 .../service-methods/resolve-inlay-hint.mdx    |  22 ++
 src/content/docs/services/css.mdx             |  49 +++
 src/content/docs/services/emmet.mdx           |  41 +++
 src/content/docs/services/eslint.mdx          |  41 +++
 src/content/docs/services/html.mdx            |  42 +++
 src/content/docs/services/json.mdx            |  41 +++
 src/content/docs/services/markdown.mdx        |  41 +++
 src/content/docs/services/prettier.mdx        |  56 ++++
 src/content/docs/services/prettyhtml.mdx      |  40 +++
 src/content/docs/services/pug-beautify.mdx    |  40 +++
 src/content/docs/services/pug.mdx             |  40 +++
 src/content/docs/services/sass-formatter.mdx  |  40 +++
 src/content/docs/services/tslint.mdx          |  41 +++
 .../services/typescript-twoslash-queries.mdx  |  41 +++
 src/content/docs/services/typescript.mdx      |  41 +++
 src/content/docs/services/vetur.mdx           |  40 +++
 src/content/docs/services/yaml.mdx            |  41 +++
 .../{core-concepts => tools}/volar-labs-1.png | Bin
 .../{core-concepts => tools}/volar-labs.mdx   |   0
 79 files changed, 3081 insertions(+), 420 deletions(-)
 rename src/content/docs/{core-concepts => about}/why-volar.mdx (100%)
 create mode 100644 src/content/docs/core-concepts/language-definition.mdx
 create mode 100644 src/content/docs/core-concepts/service-definition.mdx
 create mode 100644 src/content/docs/guides/build-and-bundle.mdx
 create mode 100644 src/content/docs/packages/cdn.mdx
 create mode 100644 src/content/docs/packages/coc-nvim.mdx
 create mode 100644 src/content/docs/packages/code-gen.mdx
 create mode 100644 src/content/docs/packages/eslint.mdx
 create mode 100644 src/content/docs/packages/jsdelivr.mdx
 create mode 100644 src/content/docs/packages/kit.mdx
 create mode 100644 src/content/docs/packages/language-core.mdx
 create mode 100644 src/content/docs/packages/language-hub.mdx
 create mode 100644 src/content/docs/packages/language-server.mdx
 create mode 100644 src/content/docs/packages/language-service.mdx
 create mode 100644 src/content/docs/packages/monaco.mdx
 create mode 100644 src/content/docs/packages/preview.mdx
 create mode 100644 src/content/docs/packages/shared.mdx
 create mode 100644 src/content/docs/packages/snapshot-document.mdx
 create mode 100644 src/content/docs/packages/source-map.mdx
 create mode 100644 src/content/docs/packages/test-utils.mdx
 create mode 100644 src/content/docs/packages/transforms.mdx
 create mode 100644 src/content/docs/packages/tsl-config.mdx
 create mode 100644 src/content/docs/packages/typescript-faster.mdx
 create mode 100644 src/content/docs/packages/typescript-language-service.mdx
 create mode 100644 src/content/docs/packages/typescript.mdx
 create mode 100644 src/content/docs/packages/vscode.mdx
 delete mode 100644 src/content/docs/reference/languages.mdx
 delete mode 100644 src/content/docs/reference/services.mdx
 create mode 100644 src/content/docs/service-methods/index.mdx
 create mode 100644 src/content/docs/service-methods/provide-call-hierarchy-incoming-calls.mdx
 create mode 100644 src/content/docs/service-methods/provide-call-hierarchy-items.mdx
 create mode 100644 src/content/docs/service-methods/provide-call-hierarchy-outgoing-calls.mdx
 create mode 100644 src/content/docs/service-methods/provide-code-actions.mdx
 create mode 100644 src/content/docs/service-methods/provide-code-lens.mdx
 create mode 100644 src/content/docs/service-methods/provide-color-presentations.mdx
 create mode 100644 src/content/docs/service-methods/provide-completion-items.mdx
 create mode 100644 src/content/docs/service-methods/provide-definition.mdx
 create mode 100644 src/content/docs/service-methods/provide-document-colors.mdx
 create mode 100644 src/content/docs/service-methods/provide-document-formatting-edits.mdx
 create mode 100644 src/content/docs/service-methods/provide-document-highlights.mdx
 create mode 100644 src/content/docs/service-methods/provide-document-links.mdx
 create mode 100644 src/content/docs/service-methods/provide-document-range-formatting-edits.mdx
 create mode 100644 src/content/docs/service-methods/provide-document-semantic-tokens-edits.mdx
 create mode 100644 src/content/docs/service-methods/provide-document-semantic-tokens.mdx
 create mode 100644 src/content/docs/service-methods/provide-document-symbols.mdx
 create mode 100644 src/content/docs/service-methods/provide-folding-ranges.mdx
 create mode 100644 src/content/docs/service-methods/provide-hover.mdx
 create mode 100644 src/content/docs/service-methods/provide-inlay-hints.mdx
 create mode 100644 src/content/docs/service-methods/provide-linked-editing-ranges.mdx
 create mode 100644 src/content/docs/service-methods/provide-on-type-formatting-edits.mdx
 create mode 100644 src/content/docs/service-methods/provide-references.mdx
 create mode 100644 src/content/docs/service-methods/provide-rename-edits.mdx
 create mode 100644 src/content/docs/service-methods/provide-selection-ranges.mdx
 create mode 100644 src/content/docs/service-methods/provide-signature-help.mdx
 create mode 100644 src/content/docs/service-methods/resolve-code-action.mdx
 create mode 100644 src/content/docs/service-methods/resolve-code-lens.mdx
 create mode 100644 src/content/docs/service-methods/resolve-completion-item.mdx
 create mode 100644 src/content/docs/service-methods/resolve-document-link.mdx
 create mode 100644 src/content/docs/service-methods/resolve-inlay-hint.mdx
 create mode 100644 src/content/docs/services/css.mdx
 create mode 100644 src/content/docs/services/emmet.mdx
 create mode 100644 src/content/docs/services/eslint.mdx
 create mode 100644 src/content/docs/services/html.mdx
 create mode 100644 src/content/docs/services/json.mdx
 create mode 100644 src/content/docs/services/markdown.mdx
 create mode 100644 src/content/docs/services/prettier.mdx
 create mode 100644 src/content/docs/services/prettyhtml.mdx
 create mode 100644 src/content/docs/services/pug-beautify.mdx
 create mode 100644 src/content/docs/services/pug.mdx
 create mode 100644 src/content/docs/services/sass-formatter.mdx
 create mode 100644 src/content/docs/services/tslint.mdx
 create mode 100644 src/content/docs/services/typescript-twoslash-queries.mdx
 create mode 100644 src/content/docs/services/typescript.mdx
 create mode 100644 src/content/docs/services/vetur.mdx
 create mode 100644 src/content/docs/services/yaml.mdx
 rename src/content/docs/{core-concepts => tools}/volar-labs-1.png (100%)
 rename src/content/docs/{core-concepts => tools}/volar-labs.mdx (100%)

diff --git a/astro.config.ts b/astro.config.ts
index 8834a22..112bb11 100644
--- a/astro.config.ts
+++ b/astro.config.ts
@@ -32,26 +32,32 @@ export default defineConfig({
         PageTitle: "./src/components/starlight/PageTitle.astro",
       },
       sidebar: [
+        {
+          label: "About",
+          autogenerate: { directory: "about" },
+        },
         {
           label: "Core Concepts",
-          items: [
-            // Each item here is one entry in the navigation menu.
-            { label: "Why Volar?", link: "/core-concepts/why-volar" },
-            { label: "Embedded Languages", link: "/core-concepts/embedded-languages" },
-            { label: "Volar Labs", link: "/core-concepts/volar-labs" },
-          ],
-          // TODO: Use `autogenerate` once it allows you to order the sidebar
+          autogenerate: { directory: "core-concepts" },
+        },
+        {
+          label: "Service Methods",
+          autogenerate: { directory: "service-methods" },
+          collapsed: true,
+        },
+        {
+          label: "Packages",
+          autogenerate: { directory: "packages" },
+          collapsed: true,
         },
         {
-          label: "Guides",
-          items: [
-            { label: "Your First Volar Language Server", link: "/guides/first-server" },
-            { label: "File Structure", link: "/guides/file-structure" },
-          ],
+          label: "Services",
+          autogenerate: { directory: "services" },
+          collapsed: true,
         },
         {
-          label: "Reference",
-          autogenerate: { directory: "reference" },
+          label: "Tools",
+          autogenerate: { directory: "tools" },
         },
       ],
     }),
diff --git a/src/content/docs/core-concepts/why-volar.mdx b/src/content/docs/about/why-volar.mdx
similarity index 100%
rename from src/content/docs/core-concepts/why-volar.mdx
rename to src/content/docs/about/why-volar.mdx
diff --git a/src/content/docs/core-concepts/language-definition.mdx b/src/content/docs/core-concepts/language-definition.mdx
new file mode 100644
index 0000000..1f1d045
--- /dev/null
+++ b/src/content/docs/core-concepts/language-definition.mdx
@@ -0,0 +1,282 @@
+---
+title: Language Definition
+description: Define and implement Volar language plugins and VirtualCode, including all hooks, mappings, and best practices.
+---
+
+> This page is a work in progress. Interested in contributing some documentation to it, or want to improve it? [Edit this page on GitHub](https://github.com/volarjs/docs/blob/main/src/content/docs/core-concepts/language-definition.mdx)
+
+As can be expected from a framework for language servers, Volar allows you to define the languages you want to support in your project.
+
+## Shape of a language definition
+
+A language definition is a JavaScript object that contains a `createVirtualCode` and a `updateVirtualCode` function.
+
+```ts title="src/my-language.ts"
+export const language = {
+	createVirtualCode(fileId, languageId, snapshot) {
+		// Create a virtual code object
+	},
+	updateVirtualCode(_fileId, languageCode, snapshot) {
+		// Update the virtual code object
+	},
+};
+```
+
+As the names suggests, those methods create and update a `VirtualCode`. A `VirtualCode` object is created for each file that your language server will handle. These can then be accessed in the hooks of the [services](/core-concepts/service-definition) that provides the features of your language server, as such they're also a place you can store additional information about the file that could be useful to know for the features of your services.
+
+Albeit not required, a common pattern is to define a JavaScript class that implements the `VirtualCode` interface, as this makes it easier to later add more properties and methods to the virtual code object and unlock the ability to use `instanceof` to check if a virtual code object is of a certain type.
+
+```ts title="src/my-language.ts"
+import type { LanguagePlugin, VirtualCode } from '@volar/language-core';
+
+export const language = {
+	createVirtualCode(fileId, languageId, snapshot) {
+		if (languageId !== 'my-language')
+			return;
+
+		return new MyLanguageVirtualCode(snapshot);
+	},
+	updateVirtualCode(_fileId, languageCode, snapshot) {
+		languageCode.update(snapshot);
+		return languageCode;
+	},
+} satisfies LanguagePlugin<MyLanguageVirtualCode>;
+
+export class MyLanguageVirtualCode implements VirtualCode {
+	id = 'root';
+	languageId = 'my-language';
+	mappings = []
+
+	constructor(
+		public snapshot: ts.IScriptSnapshot
+	) {
+		this.onSnapshotUpdated();
+	}
+
+	public update(newSnapshot: ts.IScriptSnapshot) {
+		this.snapshot = newSnapshot;
+		this.onSnapshotUpdated();
+	}
+
+	onSnapshotUpdated() {
+		// Update the virtual code object
+	}
+}
+```
+
+This is a simple example of a language definition, where `MyVirtualLanguageCode` only does the strict minimum possible. In a real language definition, you would most likely have a lot more properties and methods available on the `MyLanguageVirtualCode` class.
+
+### Embedded languages
+
+If your language supports [embedded languages](/core-concepts/embedded-languages/), your instance `VirtualCode` should include a `embeddedCodes` property that contains an array of `VirtualCode` instances for the embedded languages.
+
+```ts title="src/my-language.ts" ins={20, 34-52} collapse={1-14, 22-31}
+import type { LanguagePlugin, VirtualCode } from '@volar/language-core';
+
+export const language = {
+	createVirtualCode(fileId, languageId, snapshot) {
+		if (languageId !== 'my-language')
+			return;
+
+		return new MyLanguageVirtualCode(snapshot);
+	},
+	updateVirtualCode(_fileId, languageCode, snapshot) {
+		languageCode.update(snapshot);
+		return languageCode;
+	},
+} satisfies LanguagePlugin<MyLanguageVirtualCode>;
+
+export class MyLanguageVirtualCode implements VirtualCode {
+	id = 'root';
+	languageId = 'my-language';
+	mappings = []
+	embeddedCodes: VirtualCode[] = []
+
+	constructor(
+		public snapshot: ts.IScriptSnapshot
+	) {
+		this.onSnapshotUpdated();
+	}
+
+	public update(newSnapshot: ts.IScriptSnapshot) {
+		this.snapshot = newSnapshot;
+		this.onSnapshotUpdated();
+	}
+
+	onSnapshotUpdated() {
+		const snapshotContent = this.snapshot.getText(0, this.snapshot.getLength());
+
+		// Find embedded languages
+		const embeddedLanguages = findEmbeddedLanguages(snapshotContent);
+
+		// Create virtual code objects for embedded languages
+		this.embeddedCodes = embeddedLanguages.map(embeddedLanguage => {
+			return {
+				id: embeddedLanguage.id,
+				languageId: embeddedLanguage.languageId,
+				mappings: [],
+				snapshot: {
+						getText: (start, end) => embeddedLanguage.content.substring(start, end),
+						getLength: () => embeddedLanguage.content.length,
+						getChangeRange: () => undefined,
+					}
+			}
+		});
+	}
+}
+```
+
+## Full LanguagePlugin hooks
+
+While only two methods are required, Volar's language plugin commonly implements three hooks:
+
+- `getLanguageId(fileUri)?: string | undefined`
+  - Return a language id (e.g. `"vue"`, `"svelte"`, `"html1"`) for `fileUri`, or `undefined` to skip.
+  - Use this to opt files in/out by extension, shebang, or contents.
+- `createVirtualCode(fileUri, languageId, snapshot): VirtualCode | undefined`
+  - Create the root `VirtualCode` for a file. Build initial mappings and any embedded `VirtualCode`s.
+- `updateVirtualCode(fileUri, languageCode, snapshot): VirtualCode`
+  - Incrementally update the existing `VirtualCode` to reflect a new snapshot, then return it.
+
+Notes:
+- `snapshot` is immutable for a given version. Build all parsing and indexing on the snapshot text.
+- Keep updates incremental; avoid full re-parses if you can track deltas.
+
+## The VirtualCode contract
+
+Your `VirtualCode` should implement the following essential properties:
+
+- `id: string`
+  - Unique within the file. The root is commonly `"root"`.
+- `languageId: string`
+  - The language id of the root or embedded segment (`"my-language"`, `"html"`, `"css"`, etc.).
+- `snapshot: ts.IScriptSnapshot`
+  - Provides stable reads via `getText(start, end)` and `getLength()`.
+- `embeddedCodes?: VirtualCode[]`
+  - Child segments for embedded languages (e.g., HTML template + CSS block).
+- `mappings?: Array<{ sourceRange: [number, number]; mappedRange: [number, number]; data?: unknown }>`
+  - Optional raw mappings that your plugin feeds into higher-level source-mapping utilities.
+
+Tip: You can store additional parsed state on the instance (AST, symbol tables, indexes) keyed by the current snapshot to speed up service methods.
+
+## Mappings and source maps
+
+Mappings connect source text offsets to generated text offsets for embedded/virtual files and vice versa. Accurate mappings are the foundation for “jump to definition,” “rename,” “highlight,” etc.
+
+- Use `@volar/source-map` to build and query mappings reliably.
+- Prefer coarse-enough segments to avoid mapping explosions.
+- Attach capability flags in mapping `data` to signal which features should traverse a mapping.
+
+See: [@volar/source-map](/packages/source-map), [@volar/code-gen](/packages/code-gen), [@volar/transforms](/packages/transforms).
+
+## Implementing getLanguageId
+
+Use `getLanguageId` to rout files to your plugin:
+
+```ts
+getLanguageId(uri) {
+  if (uri.path.endsWith('.html1')) return 'html1';
+}
+```
+
+Avoid expensive I/O; for content sniffing, consider a cheap prefix/marker check from a lightweight cache.
+
+## Implementing createVirtualCode
+
+Parse the snapshot, build initial state and mappings, and create any embedded `VirtualCode`s:
+
+```ts
+createVirtualCode(uri, languageId, snapshot) {
+  if (languageId !== 'my-language') return;
+  const code = new MyLanguageVirtualCode(snapshot);
+  // Build mappings for template / style regions, if any
+  code.embeddedCodes = [
+    /* e.g., HTML virtual code, CSS virtual code */
+  ];
+  return code;
+}
+```
+
+## Implementing updateVirtualCode
+
+Keep it incremental when possible:
+
+```ts
+updateVirtualCode(uri, languageCode, snapshot) {
+  if (languageCode.snapshot === snapshot) return languageCode; // no-op
+  languageCode.update(snapshot); // recompute mappings/embeds that changed
+  return languageCode;
+}
+```
+
+## Best practices
+
+- Performance
+  - Cache parse results and indexes per snapshot version.
+  - Recompute only affected regions on update.
+  - Keep mapping segments focused; avoid 1:1 character mappings unless necessary.
+- Correctness
+  - Always operate on the provided snapshot; never read from the file system directly.
+  - Keep `embeddedCodes` synchronized with source regions on each update.
+  - Normalize URIs (use consistent schemes like `file://`).
+- Debuggability
+  - Add a `name` to your service (in the service layer) and log mapping spans during development.
+  - Provide toggles to dump virtual files for inspection.
+
+## Example: language with HTML and CSS embeds
+
+```ts
+export class HtmlLikeCode implements VirtualCode {
+  id = 'root';
+  languageId = 'htmllike';
+  embeddedCodes = [];
+  constructor(public snapshot: ts.IScriptSnapshot) {
+    this.onSnapshotUpdated();
+  }
+  update(s: ts.IScriptSnapshot) {
+    this.snapshot = s;
+    this.onSnapshotUpdated();
+  }
+  private onSnapshotUpdated() {
+    const text = this.snapshot.getText(0, this.snapshot.getLength());
+    const { templateRange, styleRange } = parseRegions(text);
+    this.embeddedCodes = [];
+    if (templateRange) {
+      this.embeddedCodes.push(new HtmlEmbeddedCode(this.snapshot, templateRange));
+    }
+    if (styleRange) {
+      this.embeddedCodes.push(new CssEmbeddedCode(this.snapshot, styleRange));
+    }
+  }
+}
+```
+
+Pair this with first-party services:
+- HTML: `volar-service-html`
+- CSS: `volar-service-css`
+
+## Interplay with Services
+
+Language plugins define structure (files, embeds, mappings). Services implement features (completion, hover, formatting, etc.). Services rely on your plugin’s mappings to translate positions correctly.
+
+- Learn service method semantics in [Service Methods](/service-methods/).
+- Use purpose-built services (HTML/CSS/TS/JSON/YAML) where possible, and write custom services for language-specific logic.
+
+## Troubleshooting
+
+- Features act on the wrong text
+  - Check mapping direction and off-by-one offsets; ensure ranges are half-open `[start, end)`.
+- Embedded regions not updating
+  - Ensure `updateVirtualCode` recomputes `embeddedCodes` when the snapshot changes.
+- Poor performance with large files
+  - Cache parse results per snapshot; avoid full re-parse on every change.
+  - Reduce mapping granularity; prefer region-level segments.
+
+## Related reading
+
+- VS Code API (extension environment, client-side expectations): https://code.visualstudio.com/api
+- LSP server/client libraries for VS Code: https://github.com/microsoft/vscode-languageserver-node
+- Source mapping and transforms:
+  - [@volar/source-map](/packages/source-map)
+  - [@volar/code-gen](/packages/code-gen)
+  - [@volar/transforms](/packages/transforms)
diff --git a/src/content/docs/core-concepts/service-definition.mdx b/src/content/docs/core-concepts/service-definition.mdx
new file mode 100644
index 0000000..6290525
--- /dev/null
+++ b/src/content/docs/core-concepts/service-definition.mdx
@@ -0,0 +1,71 @@
+---
+title: Service Definition
+description: A list of available services in VolarJS and how to use them.
+---
+
+Services are the building blocks of Volar language servers. They are responsible for providing all the features you'd expect in a language server, completions, diagnostics, hover information, you name it.
+
+While services are technically not tied to individual languages, they are often designed to work with a specific language or file type, including [embedded languages](/core-concepts/embedded-languages).
+
+For example, if you were to implement a Volar language server for HTML, you would likely end up with three different services, one for general HTML support, one for CSS support and one for JavaScript support, the latter two being used for `<style>` and `<script>` tags respectively.
+
+## Shape of a service
+
+A service is a JavaScript object, whose only required property is a `create` method. The `create` method is called when the service is initialized, and it should return an object with methods that implement the various features of the service.
+
+These methods are called by the Volar language server when it needs to perform a specific task, such as providing completions or diagnostics. Those methods map almost exactly to the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) requests, for instance `textDocument/completion` becomes `provideCompletionItems`, `textDocument/hover` becomes `provideHover`, etc.
+
+```ts title="service.ts"
+export const service = {
+	name: 'my-service', // The name of the service, this is used to identify the service in the logs and in Volar Labs
+	create(context): ServicePluginInstance {
+		return {
+			provideHover(document, position, token) {
+				// Implement hover support here
+			},
+			// More methods...
+		};
+	},
+} satisfies ServicePlugin;
+```
+
+## Using a service
+
+When initializing the language server, the list of services to use is passed as an option to the `initialize` method.
+
+```ts title="server.ts"
+import {
+  createConnection,
+  createServer,
+  createSimpleProjectProviderFactory,
+} from "@volar/language-server/node";
+import { service } from "./service";
+
+const connection = createConnection();
+const server = createServer(connection);
+
+connection.listen();
+
+connection.onInitialize((params) => {
+  return server.initialize(params, createSimpleProjectProviderFactory(), {
+    // ...
+    getServicePlugins() {
+      return [service];
+    },
+  });
+});
+
+connection.onInitialized(() => {
+  server.initialized();
+});
+```
+
+## First-party services
+
+The Volar team maintains a number of first-party services that are ready for use in your Volar language servers. These services should cover the vast majority of common use cases, such as providing completions, diagnostics, hover information, etc for HTML, CSS, JSON, JavaScript and more, or integrating with well-known tools like Emmett, Prettier, etc.
+
+To see a list of all first-party services, see the [volarjs/services](https://github.com/volarjs/services) repository.
+
+## Methods
+
+For detailed per-method docs, see the dedicated section: [Service Methods](/service-methods/).
diff --git a/src/content/docs/guides/build-and-bundle.mdx b/src/content/docs/guides/build-and-bundle.mdx
new file mode 100644
index 0000000..23c1cd2
--- /dev/null
+++ b/src/content/docs/guides/build-and-bundle.mdx
@@ -0,0 +1,262 @@
+---
+title: "Build and Bundle for Volar LSP (Server, Client, Web)"
+description: A practical, fast, and robust build system for Volar-based LSPs across Node (server), VS Code extension (client), and web/Monaco targets.
+---
+
+> This guide captures a recommended toolchain and settings for building a Volar-powered LSP that is fast, modern, and reliable across environments. It aligns with the VS Code extension runtime and the LSP stack.
+>
+> References:
+> - VS Code API docs: https://code.visualstudio.com/api
+> - vscode-languageserver-node: https://github.com/microsoft/vscode-languageserver-node
+
+## Goals
+
+- Very fast builds and rebuilds (esbuild-based)
+- Works with complex monorepos and bleeding-edge TS/JS
+- Emits exactly what VS Code expects for extensions
+- Produces optional web/Monaco bundles for demos/playgrounds
+
+## Recommended stack
+
+- Package manager: pnpm workspaces
+- Orchestrator: Turborepo (or Nx) for caching/parallelism
+- Builder: tsup (esbuild) for server and VS Code extension
+- Type checking: `tsc --build` with Project References (separate from bundling)
+- Packaging: `@vscode/vsce`
+- VS Code tests: `@vscode/test-electron`
+- Optional web builds: esbuild/tsup or Vite (for `@volar/monaco` playgrounds)
+
+## Monorepo layout
+
+```
+packages/
+  language-core/            # shared libs (optional)
+  language-service/         # optional service composition (optional)
+  language-server/          # LSP server (Node)
+  vscode-extension/         # VS Code client (extension)
+  web-playground/           # optional Monaco web demos
+```
+
+`pnpm-workspace.yaml`
+```yaml
+packages:
+  - "packages/*"
+```
+
+## TypeScript setup
+
+- TS 5.x, strict mode on
+- `moduleResolution: "node16"` (or `"bundler"` if preferred)
+- Project References to speed up type-checking across packages
+
+Root `tsconfig.base.json`:
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "moduleResolution": "node16",
+    "resolveJsonModule": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+## Server (Node LSP) build
+
+- Output format: CommonJS
+- Platform: node
+- Target: match VS Code’s Node runtime for your `engines.vscode` (e.g. `node20`)
+- Externalize: `vscode`, `typescript` (and other peers you don’t want bundled)
+
+`packages/language-server/tsup.config.ts`
+```ts
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/node.ts'],        // your LSP server entry
+  format: ['cjs'],
+  platform: 'node',
+  target: 'node20',              // align to VS Code engine’s Node
+  sourcemap: true,
+  dts: true,
+  splitting: false,
+  minify: false,
+  clean: true,
+  external: ['vscode', 'typescript'],
+});
+```
+
+`packages/language-server/package.json`
+```jsonc
+{
+  "name": "@your-scope/language-server",
+  "main": "./dist/node.cjs",
+  "bin": {
+    "your-language-server": "./bin/cli.js"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -b"
+  },
+  "dependencies": {
+    "@volar/language-server": "latest",
+    "@volar/language-core": "latest",
+    "@volar/language-service": "latest"
+  }
+}
+```
+
+CLI shim `bin/cli.js`
+```js
+#!/usr/bin/env node
+require('../dist/node.cjs');
+```
+
+### Server gotchas
+- Always emit CJS for Node entry consumed by the extension
+- Keep `vscode` external (provided by VS Code on the client side)
+- Ensure `node` target matches the VS Code engine you support
+- Avoid dynamic `require` paths that bundlers can’t analyze
+
+## VS Code extension (client) build
+
+- Output format: CommonJS
+- Platform: node
+- Externalize: `vscode`
+- Package with `@vscode/vsce`
+- Test with `@vscode/test-electron`
+
+`packages/vscode-extension/tsup.config.ts`
+```ts
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/extension.ts'],
+  format: ['cjs'],
+  platform: 'node',
+  target: 'node20',
+  sourcemap: true,
+  dts: false,
+  clean: true,
+  external: ['vscode'],
+});
+```
+
+`packages/vscode-extension/package.json`
+```jsonc
+{
+  "name": "your-language-extension",
+  "displayName": "Your Language Extension",
+  "version": "0.0.1",
+  "engines": { "vscode": "^1.90.0" },
+  "activationEvents": ["onLanguage:yourlang"],
+  "main": "./dist/extension.cjs",
+  "scripts": {
+    "build": "tsup",
+    "package": "vsce package",
+    "test": "vscode-test"
+  },
+  "devDependencies": {
+    "@vscode/vsce": "^3",
+    "@vscode/test-electron": "^2"
+  },
+  "dependencies": {
+    "vscode-languageclient": "^9",
+    "@volar/vscode": "latest"
+  }
+}
+```
+
+`.vscodeignore` (keep bundles lean)
+```
+**/node_modules/**
+!node_modules/vscode-languageclient/**
+!dist/**
+src/**
+tsconfig*.json
+tsup.config.ts
+```
+
+### Client gotchas
+- `vscode` must be external; don’t bundle it
+- Use CommonJS output for the extension entry
+- Align Node target with the VS Code engine
+- Use absolute file URIs and consistent URI schemes when talking to your server
+
+## Optional: Web/Monaco build
+
+- Output: ESM for browsers
+- Platform: browser, `target: es2020` (or newer as needed)
+- Externalize/peer: `monaco-editor`; load via CDN or top-level bundler
+
+Minimal tsup config:
+```ts
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/web.ts'],
+  format: ['esm'],
+  platform: 'browser',
+  target: 'es2020',
+  splitting: true,
+  sourcemap: true,
+  dts: false,
+  external: ['monaco-editor'],
+  clean: true,
+});
+```
+
+### Web gotchas
+- Don’t ship Node builtins/polyfills unless strictly required
+- Use `inmemory://` (or similar) URIs consistently across Monaco and Volar
+- Keep bundles code-split for faster demo loads
+
+## Monorepo workflows
+
+- Use Turborepo for incremental caching and parallelism:
+  - `build`: runs `tsup` in each package
+  - `typecheck`: runs `tsc -b` with references
+  - `test`: runs unit/integration tests
+- Use Changesets for versioning/publishing
+
+`turbo.json`
+```json
+{
+  "pipeline": {
+    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
+    "typecheck": { "dependsOn": ["^typecheck"] },
+    "test": { "dependsOn": ["build"] }
+  }
+}
+```
+
+## Troubleshooting
+
+- Extension fails to activate:
+  - Check `main` path and `activationEvents` in extension `package.json`
+  - Verify `vscode` is external and not bundled
+  - Confirm Node target matches the VS Code engine
+- Language server doesn’t start or exits:
+  - Inspect output channel “Your Language Server”
+  - Verify the extension resolves the server module path correctly
+  - Run server directly with `node` to catch runtime errors
+- Missing typings or path aliases break the build:
+  - Ensure path aliases have a tsup/esbuild “tsconfig paths” plugin or use relative imports
+  - Use Project References to avoid circular deps
+- Debugging:
+  - Use `--inspect` on the server process and “Attach to Node” in VS Code
+  - Enable source maps in bundler and test that breakpoints bind
+
+## Why this toolchain
+
+- `tsup`/esbuild gives the fastest practical builds with excellent TS/JS support
+- Clear separation of concerns: bundling vs type-checking (`tsc -b`)
+- Targets exactly what VS Code expects for extensions (CJS, Node platform)
+- Scales to large monorepos with Turborepo caching and Project References
+
+> Further reading:
+> - VS Code API: https://code.visualstudio.com/api
+> - `vscode-languageserver-node`: https://github.com/microsoft/vscode-languageserver-node
+
+
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index 98c891f..5ad7586 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -8,7 +8,7 @@ hero:
     file: ../../assets/logo.svg
   actions:
     - text: Why Volar?
-      link: /core-concepts/why-volar
+      link: /about/why-volar
       icon: right-arrow
       variant: primary
     - text: Starter project
diff --git a/src/content/docs/packages/cdn.mdx b/src/content/docs/packages/cdn.mdx
new file mode 100644
index 0000000..d675f4c
--- /dev/null
+++ b/src/content/docs/packages/cdn.mdx
@@ -0,0 +1,31 @@
+---
+title: "@volar/cdn"
+description: CDN-friendly builds and helpers for using Volar in the browser without bundling.
+---
+
+### Overview
+`@volar/cdn` helps load Volar pieces from a CDN (ESM) for quick demos and zero-build setups.
+
+### Install
+
+```bash
+npm i @volar/cdn
+```
+
+Or load directly from a CDN (e.g. jsDelivr):
+
+```html
+<script type="module">
+  import { createMonacoLanguageService } from 'https://cdn.jsdelivr.net/npm/@volar/monaco/+esm';
+  // ...
+</script>
+```
+
+### Usage
+- Combine with `@volar/monaco` and service plugins
+- Good for playgrounds, embedding editors in docs sites
+
+### Related
+- [@volar/jsdelivr](/packages/jsdelivr), [@volar/monaco](/packages/monaco), [@volar/preview](/packages/preview)
+
+
diff --git a/src/content/docs/packages/coc-nvim.mdx b/src/content/docs/packages/coc-nvim.mdx
new file mode 100644
index 0000000..9257305
--- /dev/null
+++ b/src/content/docs/packages/coc-nvim.mdx
@@ -0,0 +1,53 @@
+---
+title: "@volar/coc.nvim"
+description: coc.nvim client integration for Volar language servers in (Neo)Vim.
+---
+
+### Overview
+`@volar/coc.nvim` provides a ready-to-use coc.nvim client configuration for Volar-based language servers. It wires the Volar LSP server to coc.nvim so you get completions, hovers, diagnostics, refactors, rename, inlay hints, semantic tokens, and more in Vim/Neovim.
+
+### Install
+
+```bash
+npm i -D @volar/coc.nvim
+```
+
+Also ensure coc.nvim is installed in your editor.
+
+### Usage
+Add a language server entry to your `:CocConfig` (usually `~/.config/nvim/coc-settings.json`):
+
+```json
+{
+  "languageserver": {
+    "volar": {
+      "module": "@volar/coc.nvim",
+      "args": [],
+      "filetypes": ["html", "vue", "markdown", "json", "yaml", "javascript", "javascriptreact", "typescript", "typescriptreact"],
+      "initializationOptions": {
+        "getServicePlugins": true
+      }
+    }
+  }
+}
+```
+
+- Set `filetypes` to the languages your server supports.
+- Pass any project-specific initialization options as needed.
+
+### How it works
+- Exposes a coc.nvim-compatible client module that spawns a Volar LSP server
+- Bridges LSP requests/responses between coc.nvim and the server
+- Respects coc.nvim workspace and configuration facilities
+
+### API summary
+This package is consumed by coc.nvim through its “languageserver.module” entry. You typically don’t import it directly in application code.
+
+### Tips
+- For large repos, prefer workspaceFolders-aware setups and enable incremental features in your server configuration
+- Use `:CocCommand` to inspect logs when diagnosing issues
+
+### Related
+- [@volar/language-server](/packages/language-server), [@volar/kit](/packages/kit), [@volar/vscode](/packages/vscode)
+
+
diff --git a/src/content/docs/packages/code-gen.mdx b/src/content/docs/packages/code-gen.mdx
new file mode 100644
index 0000000..2466ceb
--- /dev/null
+++ b/src/content/docs/packages/code-gen.mdx
@@ -0,0 +1,45 @@
+---
+title: "@volar/code-gen"
+description: Utilities for generating virtual code with stable source maps and range tracking.
+---
+
+### Overview
+`@volar/code-gen` helps you produce generated code strings (virtual files) while recording precise mappings back to the source. This is essential for accurate hovers, go-to-definition, and diagnostics in embedded-language scenarios.
+
+### Install
+
+```bash
+npm i @volar/code-gen
+```
+
+### Usage
+
+```ts
+import { CodeGen } from '@volar/code-gen';
+
+const cg = new CodeGen();
+cg.addText('function render(){ return ');
+cg.addMapping({
+  sourceRange: [12, 17], // source indices for `Hello`
+  generatedRange: [cg.getText().length, cg.getText().length + 7],
+  data: { capabilities: { references: true, definitions: true, rename: true } },
+});
+cg.addText('"Hello"');
+cg.addText('; }');
+
+const { text, mappings } = cg.generate();
+```
+
+### API summary
+- `new CodeGen()`
+- `addText(text)`, `addMapping({ sourceRange, generatedRange, data })`
+- `generate() => { text, mappings }`
+
+### Best practices
+- Keep mappings granular but not overly fragmented
+- Tag mapping `data` with capability flags to optimize downstream routing
+
+### Related
+- [@volar/source-map](/packages/source-map), [@volar/transforms](/packages/transforms)
+
+
diff --git a/src/content/docs/packages/eslint.mdx b/src/content/docs/packages/eslint.mdx
new file mode 100644
index 0000000..3899b31
--- /dev/null
+++ b/src/content/docs/packages/eslint.mdx
@@ -0,0 +1,46 @@
+---
+title: "@volar/eslint"
+description: Utilities to integrate ESLint diagnostics and fixes with Volar-based tooling.
+---
+
+### Overview
+`@volar/eslint` offers helpers to run ESLint in tandem with Volar’s document model and surface results via LSP-like diagnostics and code actions. It’s useful when your language server should report ESLint findings alongside other language features.
+
+### Install
+
+```bash
+npm i @volar/eslint eslint
+```
+
+### Usage
+Use from a Volar service/plugin to execute ESLint against current snapshots and map results to diagnostics:
+
+```ts
+import { createEslintRunner } from '@volar/eslint';
+
+const run = await createEslintRunner({
+  cwd: process.cwd(),
+  eslintOptions: {}, // your ESLint CLIEngine/ESLint options
+});
+
+const results = await run.lintText(text, filePath);
+// Convert to LSP diagnostics and return from your service
+```
+
+### How it works
+- Adapts ESLint to Volar’s snapshot model
+- Helps convert ESLint messages to LSP diagnostics and code actions
+- Supports partial/lazy execution to keep keystroke latency low
+
+### API summary
+- `createEslintRunner({ cwd?, eslintOptions? })`
+- Utilities to map ESLint results to diagnostics/actions
+
+### Best practices
+- Cache ESLint instances; avoid reloading configs on every keystroke
+- Limit lint-on-type to small files or throttle for responsiveness
+
+### Related
+- [volar-service-eslint](/services/eslint) (ready-made service), [@volar/language-service](/packages/language-service)
+
+
diff --git a/src/content/docs/packages/jsdelivr.mdx b/src/content/docs/packages/jsdelivr.mdx
new file mode 100644
index 0000000..f4227eb
--- /dev/null
+++ b/src/content/docs/packages/jsdelivr.mdx
@@ -0,0 +1,27 @@
+---
+title: "@volar/jsdelivr"
+description: Convenience for consuming Volar packages via jsDelivr ESM endpoints.
+---
+
+### Overview
+`@volar/jsdelivr` documents patterns and helpers for loading Volar libraries directly from jsDelivr.
+
+### Example
+
+```html
+<script type="module">
+  import { createMonacoLanguageService } from 'https://cdn.jsdelivr.net/npm/@volar/monaco/+esm';
+  import { create as createHtml } from 'https://cdn.jsdelivr.net/npm/volar-service-html/+esm';
+  // bootstrap monaco + volar...
+  // const ls = await createMonacoLanguageService({ getServicePlugins: () => [createHtml()] })
+</script>
+```
+
+### Notes
+- Use explicit versions for stability in production
+- Consider caching headers and integrity attributes where possible
+
+### Related
+- [@volar/cdn](/packages/cdn), [@volar/monaco](/packages/monaco), [@volar/preview](/packages/preview)
+
+
diff --git a/src/content/docs/packages/kit.mdx b/src/content/docs/packages/kit.mdx
new file mode 100644
index 0000000..6f546c1
--- /dev/null
+++ b/src/content/docs/packages/kit.mdx
@@ -0,0 +1,42 @@
+---
+title: "@volar/kit"
+description: Convenience utilities to bootstrap Volar language services and servers quickly.
+---
+
+### Overview
+`@volar/kit` streamlines common setup for language servers and services: file watching, project discovery, and creating a ready-to-use Volar stack. It’s ideal when you want to stand up a server rapidly and iterate.
+
+### Install
+
+```bash
+npm i @volar/kit
+```
+
+### Usage
+
+```ts
+import { createNodeServer } from '@volar/kit';
+import { create as createHtml } from 'volar-service-html';
+
+const server = await createNodeServer({
+  getServicePlugins() {
+    return [createHtml()];
+  },
+});
+
+await server.listen(); // starts LSP over stdio
+```
+
+### Features
+- Turnkey Node-based LSP bootstrap
+- Reasonable defaults for workspace and projects
+- Hooks to inject custom services and configuration
+
+### When to use
+- Prototyping a new language server
+- Internal tools where you don’t need bespoke project graph handling
+
+### Related
+- If you need maximum control, use [@volar/language-server](/packages/language-server) directly.
+
+
diff --git a/src/content/docs/packages/language-core.mdx b/src/content/docs/packages/language-core.mdx
new file mode 100644
index 0000000..e624f41
--- /dev/null
+++ b/src/content/docs/packages/language-core.mdx
@@ -0,0 +1,65 @@
+---
+title: "@volar/language-core"
+description: Core primitives for building embedded-language tooling. Documents, snapshots, source maps, and plugin composition.
+---
+
+### Overview
+`@volar/language-core` provides the fundamental data structures and algorithms that power Volar. It models source files, virtual/embedded files, and mappings between them so higher-level services (TypeScript, CSS, HTML, etc.) can reason about complex, multi-language documents.
+
+Use this when you are:
+- Building a language plugin for an embedded language
+- Creating virtual files that represent transformed/compiled output
+- Mapping positions/ranges across source and generated code
+
+### How it works
+The core exposes:
+- Snapshot documents to read stable versions of text
+- Source maps and ranges to translate positions across files
+- File registries and plugin composition helpers
+- Normalized capabilities (completion, hover, diagnostics, etc.) to route requests through plugins
+
+This layer does not speak LSP or editor protocols; it focuses on correctness and performance for embedded-language modeling.
+
+### Install
+
+```bash
+npm i @volar/language-core
+```
+
+### Usage
+Create files and source maps, then pass them to higher layers:
+
+```ts
+import { createLanguage } from '@volar/language-core';
+import { createSnapshotDocument } from '@volar/snapshot-document';
+import { createSourceMap } from '@volar/source-map';
+
+const language = createLanguage();
+const doc = createSnapshotDocument('file:///app.vue', '<template>Hello</template>');
+
+const htmlVirtualCode = '<div>Hello</div>';
+const htmlMap = createSourceMap({
+  sourceDocument: doc,
+  generatedDocumentText: htmlVirtualCode,
+  // add segments that map source ranges to generated ranges...
+});
+
+language.files.registerVirtual('file:///app.vue.html', htmlVirtualCode, htmlMap);
+```
+
+### API summary
+- File and project abstractions
+- Document snapshots and change tracking
+- Source maps and range translation
+- Plugin composition types and helpers
+
+### Best practices
+- Normalize URIs early; keep a consistent scheme (`file://`, `inmemory://`, etc.)
+- Avoid recomputing source maps on every keystroke; cache per snapshot/version
+- Model transformations as isolated “virtual” files with explicit maps
+
+### Related
+- [@volar/source-map](/packages/source-map), [@volar/snapshot-document](/packages/snapshot-document), [@volar/transforms](/packages/transforms)
+- Higher layers: [@volar/language-service](/packages/language-service), [@volar/language-server](/packages/language-server)
+
+
diff --git a/src/content/docs/packages/language-hub.mdx b/src/content/docs/packages/language-hub.mdx
new file mode 100644
index 0000000..ec328e7
--- /dev/null
+++ b/src/content/docs/packages/language-hub.mdx
@@ -0,0 +1,45 @@
+---
+title: "@volar/language-hub"
+description: Compose and coordinate multiple Volar language services across files, projects, and workspaces.
+---
+
+### Overview
+`@volar/language-hub` is a high-level coordinator that helps you compose multiple language services and route requests across complex project structures. It’s useful for monorepos, multi-root workspaces, and tools that stitch together several embedded-language stacks.
+
+### Install
+
+```bash
+npm i @volar/language-hub
+```
+
+### Usage
+
+```ts
+import { createLanguageHub } from '@volar/language-hub';
+import { createLanguageService } from '@volar/language-service';
+
+const htmlLs = createLanguageService({...});
+const tsLs = createLanguageService({...});
+
+const hub = createLanguageHub([htmlLs, tsLs]);
+
+const hover = await hub.provideHover(uri, position);
+```
+
+### How it works
+- Maintains a registry of child language services
+- Routes feature requests based on file types, virtual file ownership, or custom rules
+- Merges and deduplicates results where appropriate
+
+### API summary
+- `createLanguageHub(services: LanguageService[])`
+- Forwards: `provide*` feature methods with result merging
+
+### Notes
+- Keep service ownership rules simple; prefer single-owner per virtual file to reduce duplication
+- Use for orchestration; keep heavy lifting inside individual services
+
+### Related
+- [@volar/language-service](/packages/language-service), [@volar/language-server](/packages/language-server)
+
+
diff --git a/src/content/docs/packages/language-server.mdx b/src/content/docs/packages/language-server.mdx
new file mode 100644
index 0000000..fba8c69
--- /dev/null
+++ b/src/content/docs/packages/language-server.mdx
@@ -0,0 +1,64 @@
+---
+title: "@volar/language-server"
+description: Language Server Protocol (LSP) server built on top of Volar’s core and service layers.
+---
+
+### Overview
+`@volar/language-server` adapts the Volar language-service to the Language Server Protocol. It handles client connections, initialization, workspace folders, and routes LSP requests to your configured services.
+
+Use this to:
+- Ship a complete LSP server for your language/tooling
+- Integrate with VS Code, Neovim, Eclipse Theia, etc.
+
+### How it works
+- Provides `createServer` and server wiring (connection, initialize, lifecycle)
+- Accepts a project provider factory and `getServicePlugins` callback
+- Translates LSP requests/responses to Volar service calls
+
+### Install
+
+```bash
+npm i @volar/language-server
+```
+
+### Usage
+
+```ts
+import {
+  createConnection,
+  createServer,
+  createSimpleProjectProviderFactory,
+} from '@volar/language-server/node';
+import { create as createHtml } from 'volar-service-html';
+
+const connection = createConnection();
+const server = createServer(connection);
+
+connection.listen();
+
+connection.onInitialize((params) => {
+  return server.initialize(params, createSimpleProjectProviderFactory(), {
+    getServicePlugins() {
+      return [createHtml()];
+    },
+  });
+});
+
+connection.onInitialized(() => {
+  server.initialized();
+});
+```
+
+### API summary
+- `createServer(connection)`
+- `initialize(params, createProjectProviderFactory, { getServicePlugins })`
+- Project provider factories (simple/advanced)
+
+### Best practices
+- Keep `getServicePlugins` deterministic; avoid side effects on every call
+- Prefer the “simple” factory first; switch to advanced when you need custom project graph/tsconfig handling
+
+### Related
+- [@volar/kit](/packages/kit), [@volar/vscode](/packages/vscode)
+
+
diff --git a/src/content/docs/packages/language-service.mdx b/src/content/docs/packages/language-service.mdx
new file mode 100644
index 0000000..aebcdc8
--- /dev/null
+++ b/src/content/docs/packages/language-service.mdx
@@ -0,0 +1,57 @@
+---
+title: "@volar/language-service"
+description: The service runtime that executes plugins (services) over core documents and routes feature requests.
+---
+
+### Overview
+`@volar/language-service` is the execution layer for Volar plugins (aka “services”). It takes documents and virtual files from `@volar/language-core` and runs feature providers (completion, hover, diagnostics, etc.) supplied by your services.
+
+Use this to:
+- Compose multiple services (HTML, CSS, TS, YAML, custom) into a single language-service
+- Orchestrate request routing, deduplication, and result merging
+
+### How it works
+- Accepts a project/document provider and a list of service plugins
+- Each plugin implements some subset of language features
+- The language service calls plugins, merges results, and returns LSP-like data structures
+
+### Install
+
+```bash
+npm i @volar/language-service
+```
+
+### Usage
+
+```ts
+import { createLanguageService } from '@volar/language-service';
+import { createLanguage } from '@volar/language-core';
+import { create as createHtml } from 'volar-service-html';
+import { create as createCss } from 'volar-service-css';
+import { create as createTs } from 'volar-service-typescript';
+
+const core = createLanguage();
+const ls = createLanguageService({
+  language: core,
+  getServicePlugins() {
+    return [createHtml(), createCss(), createTs()];
+  },
+});
+
+// Example: completions
+const completions = await ls.provideCompletionItems(uri, position);
+```
+
+### API summary
+- `createLanguageService({ language, getServicePlugins })`
+- Methods: `provideCompletionItems`, `provideHover`, `provideDiagnostics`, etc.
+- Result-merging utilities and cancellation handling
+
+### Notes
+- Keep plugin execution fast; prefer incremental caches keyed by document versions
+- Return partial results where supported
+
+### Related
+- [@volar/language-core](/packages/language-core), [@volar/language-server](/packages/language-server), [@volar/kit](/packages/kit)
+
+
diff --git a/src/content/docs/packages/monaco.mdx b/src/content/docs/packages/monaco.mdx
new file mode 100644
index 0000000..7fc4c6d
--- /dev/null
+++ b/src/content/docs/packages/monaco.mdx
@@ -0,0 +1,45 @@
+---
+title: "@volar/monaco"
+description: Monaco Editor integration for running Volar in the browser.
+---
+
+### Overview
+`@volar/monaco` adapts the Volar language-service to Monaco Editor. Use this to run embedded-language tooling fully in the browser (docs sites, sandboxes, playgrounds).
+
+### Install
+
+```bash
+npm i @volar/monaco
+```
+
+### Usage
+
+```ts
+import * as monaco from 'monaco-editor';
+import { createMonacoLanguageService } from '@volar/monaco';
+import { create as createHtml } from 'volar-service-html';
+
+const model = monaco.editor.createModel('<div/>', 'html', monaco.Uri.parse('inmemory:///index.html'));
+
+const volar = await createMonacoLanguageService({
+  models: [model],
+  getServicePlugins: () => [createHtml()],
+});
+
+// wire to Monaco’s completion provider
+monaco.languages.registerCompletionItemProvider('html', {
+  provideCompletionItems: async (model, position) => {
+    const items = await volar.provideCompletionItems(model.uri.toString(), position);
+    return { suggestions: items?.items ?? [] };
+  },
+});
+```
+
+### Notes
+- Use in combination with `@volar/cdn` or bundler-friendly builds for browser environments.
+- URI schemes like `inmemory://` or `file://` must be consistent across Volar and Monaco.
+
+### Related
+- [@volar/preview](/packages/preview), [@volar/cdn](/packages/cdn), [@volar/jsdelivr](/packages/jsdelivr)
+
+
diff --git a/src/content/docs/packages/preview.mdx b/src/content/docs/packages/preview.mdx
new file mode 100644
index 0000000..466acdf
--- /dev/null
+++ b/src/content/docs/packages/preview.mdx
@@ -0,0 +1,38 @@
+---
+title: "@volar/preview"
+description: Lightweight playground preview harness for running Volar-powered editors in the browser.
+---
+
+### Overview
+`@volar/preview` provides utilities to bootstrap interactive previews/playgrounds that use Volar language services under the hood. It’s useful for documentation sites and demos.
+
+### Install
+
+```bash
+npm i @volar/preview
+```
+
+### Usage
+
+```ts
+import { createPreviewApp } from '@volar/preview';
+import { create as createHtml } from 'volar-service-html';
+
+const app = await createPreviewApp({
+  files: {
+    '/index.html': '<div>Hello</div>',
+  },
+  getServicePlugins: () => [createHtml()],
+});
+
+app.mount('#app');
+```
+
+### Notes
+- Often paired with `@volar/monaco` to provide the editor part
+- Provides simple file system abstractions and wiring for demos
+
+### Related
+- [@volar/monaco](/packages/monaco), [@volar/cdn](/packages/cdn), [@volar/jsdelivr](/packages/jsdelivr)
+
+
diff --git a/src/content/docs/packages/shared.mdx b/src/content/docs/packages/shared.mdx
new file mode 100644
index 0000000..97e7061
--- /dev/null
+++ b/src/content/docs/packages/shared.mdx
@@ -0,0 +1,35 @@
+---
+title: "@volar/shared"
+description: Common types, utilities, and constants used across Volar packages.
+---
+
+### Overview
+`@volar/shared` contains reusable primitives (types, guards, small helpers) shared by multiple packages. It avoids duplicating small utilities across repos.
+
+### Install
+
+```bash
+npm i @volar/shared
+```
+
+### Contents
+- Type guards and small data structures
+- URI/path helpers, normalization routines
+- Constants used across services and servers
+
+### Usage
+
+```ts
+import { isNotNull, toUri } from '@volar/shared';
+
+const uri = toUri('/workspace/file.ts');
+items.filter(isNotNull);
+```
+
+### Notes
+- Keep `shared` focused on small, stable utilities to prevent dependency bloat
+
+### Related
+- [@volar/language-core](/packages/language-core), [@volar/transforms](/packages/transforms)
+
+
diff --git a/src/content/docs/packages/snapshot-document.mdx b/src/content/docs/packages/snapshot-document.mdx
new file mode 100644
index 0000000..32a0aba
--- /dev/null
+++ b/src/content/docs/packages/snapshot-document.mdx
@@ -0,0 +1,40 @@
+---
+title: "@volar/snapshot-document"
+description: Immutable document snapshots for consistent reads during analysis.
+---
+
+### Overview
+`@volar/snapshot-document` provides read-only snapshots of a text document at a specific version. Snapshots ensure stable reads while the user edits, enabling safe parsing, mapping, and feature computation.
+
+### Install
+
+```bash
+npm i @volar/snapshot-document
+```
+
+### Usage
+
+```ts
+import { createSnapshotDocument } from '@volar/snapshot-document';
+
+const snap = createSnapshotDocument('file:///index.html', '<div>Hello</div>');
+snap.getText(); // stable content
+```
+
+### How it works
+- Captures the text and version at a point in time
+- Exposes read methods that do not change while analysis runs
+- New edits produce new snapshots; consumers can compare versions
+
+### API summary
+- `createSnapshotDocument(uri, text, version?) => SnapshotDocument`
+- Methods: `getText()`, `offsetAt(position)`, `positionAt(offset)`, `version`, `uri`
+
+### Best practices
+- Use snapshots to drive all feature providers
+- Cache snapshot-derived structures keyed by `version`
+
+### Related
+- [@volar/source-map](/packages/source-map), [@volar/language-core](/packages/language-core)
+
+
diff --git a/src/content/docs/packages/source-map.mdx b/src/content/docs/packages/source-map.mdx
new file mode 100644
index 0000000..374f586
--- /dev/null
+++ b/src/content/docs/packages/source-map.mdx
@@ -0,0 +1,44 @@
+---
+title: "@volar/source-map"
+description: Precise mappings between source and generated virtual code for embedded languages.
+---
+
+### Overview
+`@volar/source-map` represents range/position relationships between original source files and generated virtual files. Accurate source maps are critical for definition/rename, hovers, diagnostics, and more across embedded languages.
+
+### Install
+
+```bash
+npm i @volar/source-map
+```
+
+### Usage
+
+```ts
+import { createSourceMap } from '@volar/source-map';
+
+const map = createSourceMap({
+  sourceDocument: snapshot,
+  generatedDocumentText: code,
+});
+
+map.add({
+  sourceRange: [start, end],
+  generatedRange: [gStart, gEnd],
+  data: { capabilities: { definitions: true, references: true } },
+});
+```
+
+### API summary
+- `createSourceMap({ sourceDocument, generatedDocumentText })`
+- `add({ sourceRange, generatedRange, data? })`
+- Query helpers: find generated ranges from source and vice versa
+
+### Best practices
+- Keep mapping segments minimal but comprehensive
+- Attach capability flags in `data` to optimize downstream routing
+
+### Related
+- [@volar/code-gen](/packages/code-gen), [@volar/snapshot-document](/packages/snapshot-document), [@volar/transforms](/packages/transforms)
+
+
diff --git a/src/content/docs/packages/test-utils.mdx b/src/content/docs/packages/test-utils.mdx
new file mode 100644
index 0000000..f50cf8c
--- /dev/null
+++ b/src/content/docs/packages/test-utils.mdx
@@ -0,0 +1,38 @@
+---
+title: "@volar/test-utils"
+description: Helpers for unit/integration testing of Volar plugins, transforms, and services.
+---
+
+### Overview
+`@volar/test-utils` provides utilities to construct mock documents, virtual files, and minimal language services so you can test plugins and transforms without spinning up a full LSP server.
+
+### Install
+
+```bash
+npm i -D @volar/test-utils
+```
+
+### Usage
+
+```ts
+import { createTestLanguageService, createTestDocument } from '@volar/test-utils';
+
+const doc = createTestDocument('file:///index.html', '<div/>)');
+const ls = createTestLanguageService({ getServicePlugins: () => [createHtml()] });
+
+const diags = await ls.provideDiagnostics(doc.uri);
+expect(diags.length).toBeGreaterThan(0);
+```
+
+### API summary
+- Builders for documents, projects, and language services
+- Assertions and helpers for common feature scenarios
+
+### Tips
+- Prefer small, focused fixtures per test
+- Snapshot test results that are stable (e.g. range/position sets)
+
+### Related
+- [@volar/language-service](/packages/language-service), [@volar/transforms](/packages/transforms)
+
+
diff --git a/src/content/docs/packages/transforms.mdx b/src/content/docs/packages/transforms.mdx
new file mode 100644
index 0000000..0cac187
--- /dev/null
+++ b/src/content/docs/packages/transforms.mdx
@@ -0,0 +1,35 @@
+---
+title: "@volar/transforms"
+description: Convert and combine results (ranges, edits, diagnostics) across source and virtual files.
+---
+
+### Overview
+`@volar/transforms` provides utilities to transform LSP-like results (completions, hovers, edits, diagnostics) between different coordinate spaces, typically source-to-generated or generated-to-source using source maps.
+
+### Install
+
+```bash
+npm i @volar/transforms
+```
+
+### Usage
+
+```ts
+import { transformLocations } from '@volar/transforms';
+
+const sourceLocations = transformLocations(generatedLocations, sourceMap, 'toSource');
+```
+
+### API summary
+- Location, Range, TextEdit transformers
+- Collections: arrays of locations/edits/diagnostics
+- Merge and dedupe helpers
+
+### Best practices
+- Always pair with accurate `@volar/source-map` mappings
+- Avoid double-transforming the same payload
+
+### Related
+- [@volar/source-map](/packages/source-map), [@volar/language-core](/packages/language-core)
+
+
diff --git a/src/content/docs/packages/tsl-config.mdx b/src/content/docs/packages/tsl-config.mdx
new file mode 100644
index 0000000..4d05aca
--- /dev/null
+++ b/src/content/docs/packages/tsl-config.mdx
@@ -0,0 +1,35 @@
+---
+title: "@volar/tsl-config"
+description: Shared TypeScript language configuration presets and helpers for Volar toolchains.
+---
+
+### Overview
+`@volar/tsl-config` centralizes TypeScript-related configuration commonly used by Volar. It helps align TS language service setup across packages and servers.
+
+### Install
+
+```bash
+npm i @volar/tsl-config
+```
+
+### Usage
+
+```ts
+import { createDefaultTsConfig } from '@volar/tsl-config';
+
+const tsConfig = createDefaultTsConfig({
+  // extend/override as needed
+});
+```
+
+### API summary
+- Presets for compiler options
+- Helpers to load/merge tsconfig.json
+
+### Notes
+- Intended for server authors; end users rarely need this directly
+
+### Related
+- [@volar/typescript](/packages/typescript), [@volar/typescript-language-service](/packages/typescript-language-service)
+
+
diff --git a/src/content/docs/packages/typescript-faster.mdx b/src/content/docs/packages/typescript-faster.mdx
new file mode 100644
index 0000000..7f68e32
--- /dev/null
+++ b/src/content/docs/packages/typescript-faster.mdx
@@ -0,0 +1,34 @@
+---
+title: "@volar/typescript-faster"
+description: Experimental performance-focused TypeScript integration helpers for Volar.
+---
+
+### Overview
+`@volar/typescript-faster` explores configurations and adapters to reduce latency of TS-powered features in large workspaces. Trade-offs may include reduced completeness under certain conditions.
+
+### Install
+
+```bash
+npm i @volar/typescript-faster typescript
+```
+
+### Usage
+
+```ts
+import { createFastTsProject } from '@volar/typescript-faster';
+const project = createFastTsProject({ tsconfigPath: './tsconfig.json' });
+```
+
+### Techniques
+- Aggressive caching of parsed source files
+- Skipping seldom-used TS services on keystroke
+- Debounced/batched updates
+
+### Notes
+- Consider for very large repos or constrained environments
+- Validate feature coverage for your use cases
+
+### Related
+- [@volar/typescript](/packages/typescript), [@volar/typescript-language-service](/packages/typescript-language-service)
+
+
diff --git a/src/content/docs/packages/typescript-language-service.mdx b/src/content/docs/packages/typescript-language-service.mdx
new file mode 100644
index 0000000..3cdd61f
--- /dev/null
+++ b/src/content/docs/packages/typescript-language-service.mdx
@@ -0,0 +1,40 @@
+---
+title: "@volar/typescript-language-service"
+description: Helpers to expose the TypeScript Language Service through Volar’s service API.
+---
+
+### Overview
+`@volar/typescript-language-service` focuses on adapting the raw TypeScript Language Service to Volar’s service/plugin interface. It provides scaffolding to translate TS LS requests/responses into LSP-like features used by editors.
+
+### Install
+
+```bash
+npm i @volar/typescript-language-service typescript
+```
+
+### Usage
+
+```ts
+import { createTsLanguageServiceAdapter } from '@volar/typescript-language-service';
+import * as ts from 'typescript';
+
+const adapter = createTsLanguageServiceAdapter({ ts, tsconfigPath: './tsconfig.json' });
+// Use it within a Volar service plugin to provide TS-based features
+```
+
+### How it works
+- Creates a TS LS instance and maps its outputs (edits, locations, etc.) to Volar feature methods
+- Bridges virtual files and source maps so TS results align with original sources
+
+### API summary
+- Builders/adapters for TS LS
+- Converters for TS result types to LSP-like structures
+
+### Best practices
+- Align your document lifecycle with TS project updates to avoid stale symbols
+- Cache symbol and semantic data per snapshot version
+
+### Related
+- [@volar/typescript](/packages/typescript), [volar-service-typescript](/services/typescript)
+
+
diff --git a/src/content/docs/packages/typescript.mdx b/src/content/docs/packages/typescript.mdx
new file mode 100644
index 0000000..005dfd7
--- /dev/null
+++ b/src/content/docs/packages/typescript.mdx
@@ -0,0 +1,43 @@
+---
+title: "@volar/typescript"
+description: Building blocks to integrate the TypeScript Language Service with Volar core.
+---
+
+### Overview
+`@volar/typescript` contains adapters and helpers that connect Volar’s virtual files and source maps to the TypeScript Language Service (TS LS). Use it when authoring TS-powered services or servers.
+
+### Install
+
+```bash
+npm i @volar/typescript typescript
+```
+
+### Usage
+
+```ts
+import * as ts from 'typescript';
+import { createTypeScriptProject } from '@volar/typescript';
+
+const project = createTypeScriptProject({
+  ts,
+  tsconfigPath: './tsconfig.json',
+  // supply host hooks that read from Volar’s virtual file system, if needed
+});
+```
+
+### How it works
+- Creates and manages a TS Program/Language Service backed by your documents
+- Knows how to expose TS features through Volar’s service abstractions
+
+### API summary
+- Project builders and host factories
+- Helpers to query TS LS for completions/diagnostics/edits and map results back
+
+### Performance
+- Reuse TS Programs; update incrementally
+- Use Volar snapshots for stable reads; avoid re-parsing the same text
+
+### Related
+- [volar-service-typescript](/services/typescript), [@volar/typescript-language-service](/packages/typescript-language-service)
+
+
diff --git a/src/content/docs/packages/vscode.mdx b/src/content/docs/packages/vscode.mdx
new file mode 100644
index 0000000..6333851
--- /dev/null
+++ b/src/content/docs/packages/vscode.mdx
@@ -0,0 +1,45 @@
+---
+title: "@volar/vscode"
+description: VS Code extension integration for Volar language servers.
+---
+
+### Overview
+`@volar/vscode` contains the VS Code-side glue for running Volar-based language servers and exposing features in the editor. It wires activation, client configuration, commands, and capability registration.
+
+### Install
+
+```bash
+npm i -D @volar/vscode
+```
+
+Typically consumed inside a VS Code extension, not by end-user projects.
+
+### Usage
+
+```ts
+// extension.ts
+import { activateVolarExtension } from '@volar/vscode';
+
+export async function activate(context: import('vscode').ExtensionContext) {
+  await activateVolarExtension(context, {
+    serverModule: require.resolve('@volar/language-server/node'),
+    serverOptions: { /* transport, debug opts */ },
+    clientOptions: { documentSelector: [{ language: 'vue' }, { language: 'html' }] },
+    getServicePlugins() { return []; },
+  });
+}
+```
+
+### How it works
+- Starts a Language Client connected to your server
+- Registers standard LSP features and custom commands
+- Manages workspace folders and configuration watch
+
+### Best practices
+- Keep activation lightweight; lazy-load heavy pieces
+- Use `documentSelector` precisely to avoid unnecessary activation
+
+### Related
+- [@volar/language-server](/packages/language-server), [@volar/kit](/packages/kit)
+
+
diff --git a/src/content/docs/reference/languages.mdx b/src/content/docs/reference/languages.mdx
deleted file mode 100644
index faea8e0..0000000
--- a/src/content/docs/reference/languages.mdx
+++ /dev/null
@@ -1,126 +0,0 @@
----
-title: Languages
----
-
-> This page is a work in progress. Interested in contributing some documentation to it, or want to improve it? [Edit this page on GitHub](https://github.com/volarjs/docs/blob/main/src/content/docs/reference/languages.mdx)
-
-As can be expected from a framework for language servers, Volar allows you to define the languages you want to support in your project.
-
-## Shape of a language definition
-
-A language definition is a JavaScript object that contains a `createVirtualCode` and a `updateVirtualCode` function.
-
-```ts title="src/my-language.ts"
-export const language = {
-	createVirtualCode(fileId, languageId, snapshot) {
-		// Create a virtual code object
-	},
-	updateVirtualCode(_fileId, languageCode, snapshot) {
-		// Update the virtual code object
-	},
-};
-```
-
-As the names suggests, those methods create and update a `VirtualCode`. A `VirtualCode` object is created for each file that your language server will handle. These can then be accessed in the hooks of the [services](/reference/services) that provides the features of your language server, as such they're also a place you can store additional information about the file that could be useful to know for the features of your services.
-
-Albeit not required, a common pattern is to define a JavaScript class that implements the `VirtualCode` interface, as this makes it easier to later add more properties and methods to the virtual code object and unlock the ability to use `instanceof` to check if a virtual code object is of a certain type.
-
-```ts title="src/my-language.ts"
-import type { LanguagePlugin, VirtualCode } from '@volar/language-core';
-
-export const language = {
-	createVirtualCode(fileId, languageId, snapshot) {
-		if (languageId !== 'my-language')
-			return;
-
-		return new MyLanguageVirtualCode(snapshot);
-	},
-	updateVirtualCode(_fileId, languageCode, snapshot) {
-		languageCode.update(snapshot);
-		return languageCode;
-	},
-} satisfies LanguagePlugin<MyLanguageVirtualCode>;
-
-export class MyLanguageVirtualCode implements VirtualCode {
-	id = 'root';
-	languageId = 'my-language';
-	mappings = []
-
-	constructor(
-		public snapshot: ts.IScriptSnapshot
-	) {
-		this.onSnapshotUpdated();
-	}
-
-	public update(newSnapshot: ts.IScriptSnapshot) {
-		this.snapshot = newSnapshot;
-		this.onSnapshotUpdated();
-	}
-
-	onSnapshotUpdated() {
-		// Update the virtual code object
-	}
-}
-```
-
-This is a simple example of a language definition, where `MyVirtualLanguageCode` only does the strict minimum possible. In a real language definition, you would most likely have a lot more properties and methods available on the `MyLanguageVirtualCode` class.
-
-### Embedded languages
-
-If your language supports [embedded languages](/core-concepts/embedded-languages/), your instance `VirtualCode` should include a `embeddedCodes` property that contains an array of `VirtualCode` instances for the embedded languages.
-
-```ts title="src/my-language.ts" ins={20, 34-52} collapse={1-14, 22-31}
-import type { LanguagePlugin, VirtualCode } from '@volar/language-core';
-
-export const language = {
-	createVirtualCode(fileId, languageId, snapshot) {
-		if (languageId !== 'my-language')
-			return;
-
-		return new MyLanguageVirtualCode(snapshot);
-	},
-	updateVirtualCode(_fileId, languageCode, snapshot) {
-		languageCode.update(snapshot);
-		return languageCode;
-	},
-} satisfies LanguagePlugin<MyLanguageVirtualCode>;
-
-export class MyLanguageVirtualCode implements VirtualCode {
-	id = 'root';
-	languageId = 'my-language';
-	mappings = []
-	embeddedCodes: VirtualCode[] = []
-
-	constructor(
-		public snapshot: ts.IScriptSnapshot
-	) {
-		this.onSnapshotUpdated();
-	}
-
-	public update(newSnapshot: ts.IScriptSnapshot) {
-		this.snapshot = newSnapshot;
-		this.onSnapshotUpdated();
-	}
-
-	onSnapshotUpdated() {
-		const snapshotContent = this.snapshot.getText(0, this.snapshot.getLength());
-
-		// Find embedded languages
-		const embeddedLanguages = findEmbeddedLanguages(snapshotContent);
-
-		// Create virtual code objects for embedded languages
-		this.embeddedCodes = embeddedLanguages.map(embeddedLanguage => {
-			return {
-				id: embeddedLanguage.id,
-				languageId: embeddedLanguage.languageId,
-				mappings: [],
-				snapshot: {
-						getText: (start, end) => embeddedLanguage.content.substring(start, end),
-						getLength: () => embeddedLanguage.content.length,
-						getChangeRange: () => undefined,
-					}
-			}
-		});
-	}
-}
-```
diff --git a/src/content/docs/reference/services.mdx b/src/content/docs/reference/services.mdx
deleted file mode 100644
index 9316422..0000000
--- a/src/content/docs/reference/services.mdx
+++ /dev/null
@@ -1,279 +0,0 @@
----
-title: Services
-description: A list of available services in VolarJS and how to use them.
----
-
-Services are the building blocks of Volar language servers. They are responsible for providing all the features you'd expect in a language server, completions, diagnostics, hover information, you name it.
-
-While services are technically not tied to individual languages, they are often designed to work with a specific language or file type, including [embedded languages](/core-concepts/embedded-languages).
-
-For example, if you were to implement a Volar language server for HTML, you would likely end up with three different services, one for general HTML support, one for CSS support and one for JavaScript support, the latter two being used for `<style>` and `<script>` tags respectively.
-
-## Shape of a service
-
-A service is a JavaScript object, whose only required property is a `create` method. The `create` method is called when the service is initialized, and it should return an object with methods that implement the various features of the service.
-
-These methods are called by the Volar language server when it needs to perform a specific task, such as providing completions or diagnostics. Those methods map almost exactly to the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) requests, for instance `textDocument/completion` becomes `provideCompletionItems`, `textDocument/hover` becomes `provideHover`, etc.
-
-```ts title="service.ts"
-export const service = {
-	name: 'my-service', // The name of the service, this is used to identify the service in the logs and in Volar Labs
-	create(context): ServicePluginInstance {
-		return {
-			provideHover(document, position, token) {
-				// Implement hover support here
-			},
-			// More methods...
-		};
-	},
-} satisfies ServicePlugin;
-```
-
-## Using a service
-
-When initializing the language server, the list of services to use is passed as an option to the `initialize` method.
-
-```ts title="server.ts"
-import {
-  createConnection,
-  createServer,
-  createSimpleProjectProviderFactory,
-} from "@volar/language-server/node";
-import { service } from "./service";
-
-const connection = createConnection();
-const server = createServer(connection);
-
-connection.listen();
-
-connection.onInitialize((params) => {
-  return server.initialize(params, createSimpleProjectProviderFactory(), {
-    // ...
-    getServicePlugins() {
-      return [service];
-    },
-  });
-});
-
-connection.onInitialized(() => {
-  server.initialized();
-});
-```
-
-## First-party services
-
-The Volar team maintains a number of first-party services that are ready for use in your Volar language servers. These services should cover the vast majority of common use cases, such as providing completions, diagnostics, hover information, etc for HTML, CSS, JSON, JavaScript and more, or integrating with well-known tools like Emmett, Prettier, etc.
-
-To see a list of all first-party services, see the [volarjs/services](https://github.com/volarjs/services) repository.
-
-## Methods
-
-### `provideCompletionItems`
-
-**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => CompletionItem[] | Promise<CompletionItem[]>`
-
-This method is called when the user requests completions at a specific position in the document.
-
-```ts title="service.ts"
-import { CompletionItemKind } from '@volar/language-server';
-
-export const service = {
-	name: 'my-service',
-	create(context): ServicePluginInstance {
-		return {
-			provideCompletionItems(document, position, token) {
-				return {
-					isIncomplete: true,
-					items: [
-						{
-							label: 'Hello',
-							kind: CompletionItemKind.Text,
-							isIncomplete: false
-						},
-						{
-							label: 'World',
-							kind: CompletionItemKind.Text,
-							isIncomplete: false
-						},
-					]
-				}
-			},
-		};
-	},
-} satisfies ServicePlugin;
-```
-
-### `resolveCompletionItem`
-
-**Signature:** `(item: CompletionItem, token: CancellationToken) => CompletionItem | Promise<CompletionItem>`
-
-This method is called when the user selects a completion item from the list of completions. It allows you to provide additional information for the selected completion item. This is often used when calculating the full information for completions is expensive and you want to defer it until the user actually selects a specific completion.
-
-### `provideCodeActions`
-
-**Signature:** `(document: TextDocument, range: Range, context: CodeActionContext, token: CancellationToken) => CodeAction[] | Promise<CodeAction[]>`
-
-This method is called when the user requests code actions for a specific range in the document. Code actions are typically used to fix issues or improve the code (e.g. "Extract Method", "Add missing import").
-
-### `resolveCodeAction`
-
-**Signature:** `(action: CodeAction, token: CancellationToken) => CodeAction | Promise<CodeAction>`
-
-This method is called when the user selects a code action from the list of code actions. It allows you to provide additional information for the selected code action.
-
-### `provideHover`
-
-**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => Hover | Promise<Hover>`
-
-This method is called when the user requests hover information at a specific position in the document.
-
-### `provideSignatureHelp`
-
-**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => SignatureHelp | Promise<SignatureHelp>`
-
-This method is called when the user requests signature help at a specific position in the document.
-
-### `provideDefinition`
-
-**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => Location | Location[] | Promise<Location | Location[]>`
-
-This method is called when the user requests the definition of a symbol at a specific position in the document. This method powers features like "Go to Definition".
-
-### `provideReferences`
-
-**Signature:** `(document: TextDocument, position: Position, context: ReferenceContext, token: CancellationToken) => Location[] | Promise<Location[]>`
-
-This method is called when the user requests references to a symbol at a specific position in the document. This method powers features like "Find All References".
-
-### `provideDocumentHighlights`
-
-**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => DocumentHighlight[] | Promise<DocumentHighlight[]>`
-
-This method is called when the user requests highlights for a symbol at a specific position in the document.
-
-### `provideDocumentSymbols`
-
-**Signature:** `(document: TextDocument, token: CancellationToken) => SymbolInformation[] | Promise<SymbolInformation[]>`
-
-This method is called when the user requests symbols in the document.
-
-
-### `provideCodeLens`
-
-**Signature:** `(document: TextDocument, token: CancellationToken) => CodeLens[] | Promise<CodeLens[]>`
-
-This method is called when the user requests code lenses in the document.
-
-### `resolveCodeLens`
-
-**Signature:** `(codeLens: CodeLens, token: CancellationToken) => CodeLens | Promise<CodeLens>`
-
-This method is called when the user selects a code lens from the list of code lenses. It allows you to provide additional information for the selected code lens.
-
-### `provideDocumentFormattingEdits`
-
-**Signature:** `(document: TextDocument, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`
-
-This method is called when the user requests formatting for the entire document.
-
-### `provideDocumentRangeFormattingEdits`
-
-**Signature:** `(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`
-
-This method is called when the user requests formatting for a specific range in the document.
-
-### `provideOnTypeFormattingEdits`
-
-**Signature:** `(document: TextDocument, position: Position, ch: string, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`
-
-This method is called when the user types a specific character in the document.
-
-### `provideRenameEdits`
-
-**Signature:** `(document: TextDocument, position: Position, newName: string, token: CancellationToken) => WorkspaceEdit | Promise<WorkspaceEdit>`
-
-This method is called when the user requests to rename a symbol at a specific position in the document.
-
-### `provideDocumentLinks`
-
-**Signature:** `(document: TextDocument, token: CancellationToken) => DocumentLink[] | Promise<DocumentLink[]>`
-
-This method is called when the user requests links in the document.
-
-### `resolveDocumentLink`
-
-**Signature:** `(link: DocumentLink, token: CancellationToken) => DocumentLink | Promise<DocumentLink>`
-
-This method is called when the user selects a link from the list of links. It allows you to provide additional information for the selected link.
-
-### `provideDocumentColors`
-
-**Signature:** `(document: TextDocument, token: CancellationToken) => ColorInformation[] | Promise<ColorInformation[]>`
-
-This method is called when the user requests colors in the document.
-
-### `provideColorPresentations`
-
-**Signature:** `(color: Color, document: TextDocument, range: Range, token: CancellationToken) => ColorPresentation[] | Promise<ColorPresentation[]>`
-
-This method is called when the user selects a color from the list of colors. It allows you to provide additional information for the selected color.
-
-### `provideFoldingRanges`
-
-**Signature:** `(document: TextDocument, context: FoldingContext, token: CancellationToken) => FoldingRange[] | Promise<FoldingRange[]>`
-
-This method is called when the user requests folding ranges in the document.
-
-### `provideSelectionRanges`
-
-**Signature:** `(document: TextDocument, positions: Position[], token: CancellationToken) => SelectionRange[] | Promise<SelectionRange[]>`
-
-This method is called when the user requests selection ranges at specific positions in the document.
-
-### `provideDocumentSemanticTokens`
-
-**Signature:** `(document: TextDocument, token: CancellationToken) => SemanticTokens | Promise<SemanticTokens>`
-
-This method is called when the user requests semantic tokens in the document.
-
-### `provideDocumentSemanticTokensEdits`
-
-**Signature:** `(document: TextDocument, previousResultId: string, token: CancellationToken) => SemanticTokens | SemanticTokensEdits | Promise<SemanticTokens | SemanticTokensEdits>`
-
-This method is called when the user requests semantic tokens edits in the document.
-
-### `provideLinkedEditingRanges`
-
-**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => LinkedEditingRanges | Promise<LinkedEditingRanges>`
-
-This method is called when the user requests linked editing ranges at a specific position in the document.
-
-### `provideCallHierarchyItems`
-
-**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyItem[] | Promise<CallHierarchyItem[]>`
-
-This method is called when the user requests call hierarchy items for a symbol at a specific position in the document.
-
-### `provideCallHierarchyIncomingCalls`
-
-**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyIncomingCall[] | Promise<CallHierarchyIncomingCall[]>`
-
-This method is called when the user requests incoming calls for a symbol at a specific position in the document.
-
-### `provideCallHierarchyOutgoingCalls`
-
-**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyOutgoingCall[] | Promise<CallHierarchyOutgoingCall[]>`
-
-This method is called when the user requests outgoing calls for a symbol at a specific position in the document.
-
-### `provideInlayHints`
-
-**Signature:** `(document: TextDocument, token: CancellationToken) => InlayHint[] | Promise<InlayHint[]>`
-
-This method is called when the user requests inlay hints in the document.
-
-### `resolveInlayHint`
-
-**Signature:** `(hint: InlayHint, token: CancellationToken) => InlayHint | Promise<InlayHint>`
-
-This method is called when the user selects an inlay hint from the list of inlay hints. It allows you to provide additional information for the selected inlay hint.
diff --git a/src/content/docs/service-methods/index.mdx b/src/content/docs/service-methods/index.mdx
new file mode 100644
index 0000000..aa6bb8a
--- /dev/null
+++ b/src/content/docs/service-methods/index.mdx
@@ -0,0 +1,39 @@
+---
+title: Index
+description: Detailed reference for each service method returned by a Volar service plugin instance.
+---
+
+This section documents each method your service plugin instance can implement, with signatures, best practices, examples, and troubleshooting.
+
+- [provideCompletionItems](/service-methods/provide-completion-items)
+- [resolveCompletionItem](/service-methods/resolve-completion-item)
+- [provideCodeActions](/service-methods/provide-code-actions)
+- [resolveCodeAction](/service-methods/resolve-code-action)
+- [provideHover](/service-methods/provide-hover)
+- [provideSignatureHelp](/service-methods/provide-signature-help)
+- [provideDefinition](/service-methods/provide-definition)
+- [provideReferences](/service-methods/provide-references)
+- [provideDocumentHighlights](/service-methods/provide-document-highlights)
+- [provideDocumentSymbols](/service-methods/provide-document-symbols)
+- [provideCodeLens](/service-methods/provide-code-lens)
+- [resolveCodeLens](/service-methods/resolve-code-lens)
+- [provideDocumentFormattingEdits](/service-methods/provide-document-formatting-edits)
+- [provideDocumentRangeFormattingEdits](/service-methods/provide-document-range-formatting-edits)
+- [provideOnTypeFormattingEdits](/service-methods/provide-on-type-formatting-edits)
+- [provideRenameEdits](/service-methods/provide-rename-edits)
+- [provideDocumentLinks](/service-methods/provide-document-links)
+- [resolveDocumentLink](/service-methods/resolve-document-link)
+- [provideDocumentColors](/service-methods/provide-document-colors)
+- [provideColorPresentations](/service-methods/provide-color-presentations)
+- [provideFoldingRanges](/service-methods/provide-folding-ranges)
+- [provideSelectionRanges](/service-methods/provide-selection-ranges)
+- [provideDocumentSemanticTokens](/service-methods/provide-document-semantic-tokens)
+- [provideDocumentSemanticTokensEdits](/service-methods/provide-document-semantic-tokens-edits)
+- [provideLinkedEditingRanges](/service-methods/provide-linked-editing-ranges)
+- [provideCallHierarchyItems](/service-methods/provide-call-hierarchy-items)
+- [provideCallHierarchyIncomingCalls](/service-methods/provide-call-hierarchy-incoming-calls)
+- [provideCallHierarchyOutgoingCalls](/service-methods/provide-call-hierarchy-outgoing-calls)
+- [provideInlayHints](/service-methods/provide-inlay-hints)
+- [resolveInlayHint](/service-methods/resolve-inlay-hint)
+
+
diff --git a/src/content/docs/service-methods/provide-call-hierarchy-incoming-calls.mdx b/src/content/docs/service-methods/provide-call-hierarchy-incoming-calls.mdx
new file mode 100644
index 0000000..5384c59
--- /dev/null
+++ b/src/content/docs/service-methods/provide-call-hierarchy-incoming-calls.mdx
@@ -0,0 +1,19 @@
+---
+title: provideCallHierarchyIncomingCalls
+description: Provide incoming calls to a call hierarchy item.
+---
+
+## Overview
+Return `CallHierarchyIncomingCall[]` showing where a symbol is referenced as a callee.
+
+## Signature
+`(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyIncomingCall[] | Promise<CallHierarchyIncomingCall[]>`
+
+## Example
+```ts
+provideCallHierarchyIncomingCalls(doc, pos) {
+  return findIncomingCalls(doc, pos);
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-call-hierarchy-items.mdx b/src/content/docs/service-methods/provide-call-hierarchy-items.mdx
new file mode 100644
index 0000000..4c4b7ba
--- /dev/null
+++ b/src/content/docs/service-methods/provide-call-hierarchy-items.mdx
@@ -0,0 +1,20 @@
+---
+title: provideCallHierarchyItems
+description: Provide call hierarchy roots (symbols) at a position.
+---
+
+## Overview
+Return one or more `CallHierarchyItem` entries to explore incoming/outgoing calls.
+
+## Signature
+`(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyItem[] | Promise<CallHierarchyItem[]>`
+
+## Example
+```ts
+provideCallHierarchyItems(doc, pos) {
+  const symbol = findCallable(doc, pos);
+  return symbol ? [toCallHierarchyItem(symbol)] : [];
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-call-hierarchy-outgoing-calls.mdx b/src/content/docs/service-methods/provide-call-hierarchy-outgoing-calls.mdx
new file mode 100644
index 0000000..b8d6b92
--- /dev/null
+++ b/src/content/docs/service-methods/provide-call-hierarchy-outgoing-calls.mdx
@@ -0,0 +1,19 @@
+---
+title: provideCallHierarchyOutgoingCalls
+description: Provide outgoing calls from a call hierarchy item.
+---
+
+## Overview
+Return `CallHierarchyOutgoingCall[]` showing what a symbol calls as a caller.
+
+## Signature
+`(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyOutgoingCall[] | Promise<CallHierarchyOutgoingCall[]>`
+
+## Example
+```ts
+provideCallHierarchyOutgoingCalls(doc, pos) {
+  return findOutgoingCalls(doc, pos);
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-code-actions.mdx b/src/content/docs/service-methods/provide-code-actions.mdx
new file mode 100644
index 0000000..0c23779
--- /dev/null
+++ b/src/content/docs/service-methods/provide-code-actions.mdx
@@ -0,0 +1,41 @@
+---
+title: provideCodeActions
+description: Provide quick fixes and refactors for a document range.
+---
+
+## Overview
+Called for `textDocument/codeAction`. Return quick fixes or refactors relevant to the given range and diagnostic context.
+
+## Signature
+`(document: TextDocument, range: Range, context: CodeActionContext, token: CancellationToken) => CodeAction[] | Promise<CodeAction[]>`
+
+## Best practices
+- Use diagnostics in `context` to suggest targeted fixes.
+- Group related edits; avoid overlapping/conflicting edits.
+- Prefer lazily computed `edit` in `resolveCodeAction` if expensive.
+
+## Example
+```ts
+provideCodeActions(document, range, context, token) {
+  const fixes: CodeAction[] = [];
+  for (const d of context.diagnostics) {
+    if (d.code === 'missing-attr') {
+      fixes.push({
+        title: 'Add missing attribute',
+        kind: 'quickfix',
+        diagnostics: [d],
+        data: { fix: 'add-attr', range: d.range },
+      });
+    }
+  }
+  return fixes;
+}
+```
+
+## Troubleshooting
+- No actions: ensure range intersects diagnostics or symbols of interest.
+- Conflicts: coalesce edits and ensure document versions match.
+
+## Related
+- [resolveCodeAction](/service-methods/resolve-code-action)
+
diff --git a/src/content/docs/service-methods/provide-code-lens.mdx b/src/content/docs/service-methods/provide-code-lens.mdx
new file mode 100644
index 0000000..08ab137
--- /dev/null
+++ b/src/content/docs/service-methods/provide-code-lens.mdx
@@ -0,0 +1,26 @@
+---
+title: provideCodeLens
+description: Provide code lenses for a document (inline actionable commands).
+---
+
+## Overview
+Called for `textDocument/codeLens`. Return lenses with `range` and optional `command`. Use `resolveCodeLens` for expensive commands.
+
+## Signature
+`(document: TextDocument, token: CancellationToken) => CodeLens[] | Promise<CodeLens[]>`
+
+## Best practices
+- Minimize work; move command resolution to `resolveCodeLens`.
+- Use `data` for identifiers to resolve later.
+
+## Example
+```ts
+provideCodeLens(doc) {
+  const tests = findTests(doc);
+  return tests.map(t => ({ range: t.nameRange, data: { testId: t.id } }));
+}
+```
+
+## Related
+- [resolveCodeLens](/service-methods/resolve-code-lens)
+
diff --git a/src/content/docs/service-methods/provide-color-presentations.mdx b/src/content/docs/service-methods/provide-color-presentations.mdx
new file mode 100644
index 0000000..859f7fd
--- /dev/null
+++ b/src/content/docs/service-methods/provide-color-presentations.mdx
@@ -0,0 +1,22 @@
+---
+title: provideColorPresentations
+description: Provide color formatting options for a color at a range.
+---
+
+## Overview
+Given a color and the range where it appears, return alternative presentations (e.g., hex, rgb, named).
+
+## Signature
+`(color: Color, document: TextDocument, range: Range, token: CancellationToken) => ColorPresentation[] | Promise<ColorPresentation[]>`
+
+## Example
+```ts
+provideColorPresentations(color, doc, range) {
+  return [
+    { label: toHex(color) },
+    { label: toRgb(color) },
+  ];
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-completion-items.mdx b/src/content/docs/service-methods/provide-completion-items.mdx
new file mode 100644
index 0000000..f0ada9b
--- /dev/null
+++ b/src/content/docs/service-methods/provide-completion-items.mdx
@@ -0,0 +1,44 @@
+---
+title: provideCompletionItems
+description: Provide completion items at a given position in a document.
+---
+
+## Overview
+Called for `textDocument/completion`. Return completion items for the given document and position. Prefer fast, incremental results with optional follow-up resolution.
+
+## Signature
+`(document: TextDocument, position: Position, token: CancellationToken) => CompletionList | Promise<CompletionList>`
+
+- Supports returning either an array of `CompletionItem` or a `CompletionList` with `isIncomplete`.
+- Use `token` to bail early when the user continues typing.
+
+## Inputs and outputs
+- Position should be mapped to your language’s virtual document if you use embedded languages.
+- Mark `isIncomplete: true` to hint the client to re-request as the user types.
+
+## Best practices
+- Cache context (e.g., symbol index) per document snapshot/version.
+- Avoid heavy computation; push expensive data to `resolveCompletionItem`.
+- Respect `CancellationToken`.
+
+## Example
+```ts
+provideCompletionItems(document, position, token) {
+  if (token.isCancellationRequested) return;
+  return {
+    isIncomplete: true,
+    items: [
+      { label: 'Hello', kind: 14 /* Text */ },
+      { label: 'World', kind: 14 /* Text */ },
+    ],
+  };
+}
+```
+
+## Troubleshooting
+- Empty list: verify position mapping from source to virtual docs.
+- Slow typing: add `isIncomplete`, reduce computation per keystroke.
+
+## Related
+- [resolveCompletionItem](/service-methods/resolve-completion-item)
+
diff --git a/src/content/docs/service-methods/provide-definition.mdx b/src/content/docs/service-methods/provide-definition.mdx
new file mode 100644
index 0000000..e46f8a9
--- /dev/null
+++ b/src/content/docs/service-methods/provide-definition.mdx
@@ -0,0 +1,28 @@
+---
+title: provideDefinition
+description: Provide go-to-definition for a symbol at a position.
+---
+
+## Overview
+Called for `textDocument/definition`. Return a location or multiple candidate locations for the symbol under the cursor.
+
+## Signature
+`(document: TextDocument, position: Position, token: CancellationToken) => Location | Location[] | Promise<Location | Location[]>`
+
+## Best practices
+- Map through source maps if definitions live in generated/embedded files.
+- Deduplicate overlapping locations.
+- Prefer precise ranges on identifiers.
+
+## Example
+```ts
+provideDefinition(document, position) {
+  const def = findDefinition(document, position);
+  return def ? { uri: def.uri, range: def.range } : undefined;
+}
+```
+
+## Troubleshooting
+- Jumps to wrong file: verify mapping direction and URIs.
+- Returns too many locations: filter by symbol kind or scope.
+
diff --git a/src/content/docs/service-methods/provide-document-colors.mdx b/src/content/docs/service-methods/provide-document-colors.mdx
new file mode 100644
index 0000000..d706781
--- /dev/null
+++ b/src/content/docs/service-methods/provide-document-colors.mdx
@@ -0,0 +1,23 @@
+---
+title: provideDocumentColors
+description: Provide color occurrences in the document.
+---
+
+## Overview
+Return `ColorInformation[]` for color literals/usages to power color decorators.
+
+## Signature
+`(document: TextDocument, token: CancellationToken) => ColorInformation[] | Promise<ColorInformation[]>`
+
+## Best practices
+- Map colors in embedded styles/templates as needed.
+- Deduplicate overlapping color ranges.
+
+## Example
+```ts
+provideDocumentColors(doc) {
+  return findColorInfos(doc);
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-document-formatting-edits.mdx b/src/content/docs/service-methods/provide-document-formatting-edits.mdx
new file mode 100644
index 0000000..d16a0a3
--- /dev/null
+++ b/src/content/docs/service-methods/provide-document-formatting-edits.mdx
@@ -0,0 +1,28 @@
+---
+title: provideDocumentFormattingEdits
+description: Provide edits to format the entire document.
+---
+
+## Overview
+Called for full-document formatting. Return `TextEdit[]` that transform the document to a formatted version.
+
+## Signature
+`(document: TextDocument, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`
+
+## Best practices
+- Keep edits minimal; prefer fewer larger edits over many tiny ones.
+- Respect user options (tabSize, insertSpaces).
+- Use stable formatter (Prettier/sass-formatter/prettyhtml) when possible.
+
+## Example
+```ts
+provideDocumentFormattingEdits(doc, options) {
+  const formatted = format(doc.getText(), options);
+  return [{ range: fullRange(doc), newText: formatted }];
+}
+```
+
+## Troubleshooting
+- Cursor jumps: produce deterministic edits; avoid overlapping ranges.
+
+
diff --git a/src/content/docs/service-methods/provide-document-highlights.mdx b/src/content/docs/service-methods/provide-document-highlights.mdx
new file mode 100644
index 0000000..c96688f
--- /dev/null
+++ b/src/content/docs/service-methods/provide-document-highlights.mdx
@@ -0,0 +1,26 @@
+---
+title: provideDocumentHighlights
+description: Highlight occurrences of a symbol in the current document.
+---
+
+## Overview
+Called for `textDocument/documentHighlight`. Return ranges that should be highlighted for the symbol at position.
+
+## Signature
+`(document: TextDocument, position: Position, token: CancellationToken) => DocumentHighlight[] | Promise<DocumentHighlight[]>`
+
+## Best practices
+- Distinguish read vs write highlights if known.
+- Keep results scoped to current file; cross-file is not expected.
+
+## Example
+```ts
+provideDocumentHighlights(doc, pos) {
+  const occurrences = findOccurrences(doc, pos);
+  return occurrences.map(r => ({ range: r, kind: 1 /* Read */ }));
+}
+```
+
+## Troubleshooting
+- Flicker: ensure stable ordering and ranges across keystrokes.
+
diff --git a/src/content/docs/service-methods/provide-document-links.mdx b/src/content/docs/service-methods/provide-document-links.mdx
new file mode 100644
index 0000000..6032b5a
--- /dev/null
+++ b/src/content/docs/service-methods/provide-document-links.mdx
@@ -0,0 +1,26 @@
+---
+title: provideDocumentLinks
+description: Provide links present in the document (e.g., imports, URLs).
+---
+
+## Overview
+Return `DocumentLink[]` for navigable resources and optionally a resolver to compute targets lazily.
+
+## Signature
+`(document: TextDocument, token: CancellationToken) => DocumentLink[] | Promise<DocumentLink[]>`
+
+## Best practices
+- Keep link ranges precise; avoid including quotes.
+- Use `data` to postpone expensive resolution.
+
+## Example
+```ts
+provideDocumentLinks(doc) {
+  return findLinks(doc).map(l => ({ range: l.range, data: { href: l.href } }));
+}
+```
+
+## Related
+- [resolveDocumentLink](/service-methods/resolve-document-link)
+
+
diff --git a/src/content/docs/service-methods/provide-document-range-formatting-edits.mdx b/src/content/docs/service-methods/provide-document-range-formatting-edits.mdx
new file mode 100644
index 0000000..dc9ad63
--- /dev/null
+++ b/src/content/docs/service-methods/provide-document-range-formatting-edits.mdx
@@ -0,0 +1,25 @@
+---
+title: provideDocumentRangeFormattingEdits
+description: Provide edits to format a selected document range.
+---
+
+## Overview
+Called for range formatting. Similar to full-document formatting but constrained to a specific range.
+
+## Signature
+`(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`
+
+## Best practices
+- Expand to syntactic boundaries to avoid partial AST breakage.
+- Respect user options and preserve surrounding whitespace.
+
+## Example
+```ts
+provideDocumentRangeFormattingEdits(doc, range, options) {
+  const text = doc.getText(range);
+  const formatted = format(text, options);
+  return [{ range, newText: formatted }];
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-document-semantic-tokens-edits.mdx b/src/content/docs/service-methods/provide-document-semantic-tokens-edits.mdx
new file mode 100644
index 0000000..75f9474
--- /dev/null
+++ b/src/content/docs/service-methods/provide-document-semantic-tokens-edits.mdx
@@ -0,0 +1,16 @@
+---
+title: provideDocumentSemanticTokensEdits
+description: Provide incremental semantic token edits based on a previous result.
+---
+
+## Overview
+Return either a full token set or an edits structure to update the client efficiently.
+
+## Signature
+`(document: TextDocument, previousResultId: string, token: CancellationToken) => SemanticTokens | SemanticTokensEdits | Promise<SemanticTokens | SemanticTokensEdits>`
+
+## Best practices
+- Track `resultId` to compute diffs across snapshots.
+- Fall back to full result if diff is too large or state is invalid.
+
+
diff --git a/src/content/docs/service-methods/provide-document-semantic-tokens.mdx b/src/content/docs/service-methods/provide-document-semantic-tokens.mdx
new file mode 100644
index 0000000..68a19da
--- /dev/null
+++ b/src/content/docs/service-methods/provide-document-semantic-tokens.mdx
@@ -0,0 +1,25 @@
+---
+title: provideDocumentSemanticTokens
+description: Provide semantic tokens for syntax coloring.
+---
+
+## Overview
+Return semantic tokens for the entire document to enable semantic highlighting.
+
+## Signature
+`(document: TextDocument, token: CancellationToken) => SemanticTokens | Promise<SemanticTokens>`
+
+## Best practices
+- Use legend consistent with the client.
+- Incremental updates should be supported via the edits variant.
+
+## Example
+```ts
+provideDocumentSemanticTokens(doc) {
+  const builder = createTokenBuilder();
+  collectTokens(doc, builder);
+  return builder.build();
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-document-symbols.mdx b/src/content/docs/service-methods/provide-document-symbols.mdx
new file mode 100644
index 0000000..2487a05
--- /dev/null
+++ b/src/content/docs/service-methods/provide-document-symbols.mdx
@@ -0,0 +1,26 @@
+---
+title: provideDocumentSymbols
+description: Provide outline symbols for the current document.
+---
+
+## Overview
+Called for `textDocument/documentSymbol`. Return either `SymbolInformation[]` or hierarchical `DocumentSymbol[]`.
+
+## Signature
+`(document: TextDocument, token: CancellationToken) => SymbolInformation[] | Promise<SymbolInformation[]>`
+
+## Best practices
+- Provide hierarchical symbols when possible (better outline UX).
+- Use consistent symbol kinds and ranges.
+
+## Example
+```ts
+provideDocumentSymbols(doc) {
+  const symbols = parseSymbols(doc);
+  return symbols;
+}
+```
+
+## Troubleshooting
+- Empty outline: ensure parser runs on latest snapshot text.
+
diff --git a/src/content/docs/service-methods/provide-folding-ranges.mdx b/src/content/docs/service-methods/provide-folding-ranges.mdx
new file mode 100644
index 0000000..d652613
--- /dev/null
+++ b/src/content/docs/service-methods/provide-folding-ranges.mdx
@@ -0,0 +1,19 @@
+---
+title: provideFoldingRanges
+description: Provide folding ranges for the document.
+---
+
+## Overview
+Return logical folding regions (blocks, headers, sections) to improve code navigation.
+
+## Signature
+`(document: TextDocument, context: FoldingContext, token: CancellationToken) => FoldingRange[] | Promise<FoldingRange[]>`
+
+## Example
+```ts
+provideFoldingRanges(doc) {
+  return computeFolds(doc);
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-hover.mdx b/src/content/docs/service-methods/provide-hover.mdx
new file mode 100644
index 0000000..c14e5fb
--- /dev/null
+++ b/src/content/docs/service-methods/provide-hover.mdx
@@ -0,0 +1,34 @@
+---
+title: provideHover
+description: Provide hover information at a given position.
+---
+
+## Overview
+Called for `textDocument/hover`. Return concise, high-signal information (types, docs, examples) for the symbol at the position.
+
+## Signature
+`(document: TextDocument, position: Position, token: CancellationToken) => Hover | Promise<Hover>`
+
+## Best practices
+- Keep hover brief; prefer markdown with code fences.
+- Map source→virtual positions where embedded.
+- Respect cancellation for responsiveness.
+
+## Example
+```ts
+provideHover(document, position) {
+  const symbol = findSymbol(document, position);
+  if (!symbol) return;
+  return {
+    contents: {
+      kind: 'markdown',
+      value: `**${symbol.name}**\\n\\n\`\`\`ts\\n${symbol.type}\\n\`\`\``
+    }
+  };
+}
+```
+
+## Troubleshooting
+- Wrong location: verify mappings and offset calculations.
+- Overly verbose: trim or link out to detailed docs.
+
diff --git a/src/content/docs/service-methods/provide-inlay-hints.mdx b/src/content/docs/service-methods/provide-inlay-hints.mdx
new file mode 100644
index 0000000..33ec628
--- /dev/null
+++ b/src/content/docs/service-methods/provide-inlay-hints.mdx
@@ -0,0 +1,26 @@
+---
+title: provideInlayHints
+description: Provide inlay hints (inline annotations) for a document.
+---
+
+## Overview
+Return `InlayHint[]` to show parameter names, inferred types, or other inline hints.
+
+## Signature
+`(document: TextDocument, token: CancellationToken) => InlayHint[] | Promise<InlayHint[]>`
+
+## Best practices
+- Keep hints subtle and relevant; avoid clutter.
+- Provide `tooltip` for extra context.
+
+## Example
+```ts
+provideInlayHints(doc) {
+  return computeHints(doc);
+}
+```
+
+## Related
+- [resolveInlayHint](/service-methods/resolve-inlay-hint)
+
+
diff --git a/src/content/docs/service-methods/provide-linked-editing-ranges.mdx b/src/content/docs/service-methods/provide-linked-editing-ranges.mdx
new file mode 100644
index 0000000..f1d8cea
--- /dev/null
+++ b/src/content/docs/service-methods/provide-linked-editing-ranges.mdx
@@ -0,0 +1,20 @@
+---
+title: provideLinkedEditingRanges
+description: Provide linked ranges for simultaneous editing (e.g., paired tags).
+---
+
+## Overview
+Return ranges that should be edited together while the user types.
+
+## Signature
+`(document: TextDocument, position: Position, token: CancellationToken) => LinkedEditingRanges | Promise<LinkedEditingRanges>`
+
+## Example
+```ts
+provideLinkedEditingRanges(doc, pos) {
+  const pair = findPairedTagRanges(doc, pos);
+  return pair ? { ranges: [pair.open, pair.close] } : undefined;
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-on-type-formatting-edits.mdx b/src/content/docs/service-methods/provide-on-type-formatting-edits.mdx
new file mode 100644
index 0000000..7db55e5
--- /dev/null
+++ b/src/content/docs/service-methods/provide-on-type-formatting-edits.mdx
@@ -0,0 +1,24 @@
+---
+title: provideOnTypeFormattingEdits
+description: Provide edits when a specific character is typed.
+---
+
+## Overview
+Trigger small formatting edits (e.g., closing braces, semicolons) when the user types a character.
+
+## Signature
+`(document: TextDocument, position: Position, ch: string, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`
+
+## Best practices
+- Keep edits minimal and predictable.
+- Avoid racing with other features; respect cancellation.
+
+## Example
+```ts
+provideOnTypeFormattingEdits(doc, pos, ch, options) {
+  if (ch !== '}') return [];
+  return maybeIndent(doc, pos, options);
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-references.mdx b/src/content/docs/service-methods/provide-references.mdx
new file mode 100644
index 0000000..4f78a94
--- /dev/null
+++ b/src/content/docs/service-methods/provide-references.mdx
@@ -0,0 +1,28 @@
+---
+title: provideReferences
+description: Provide references to the symbol at a position.
+---
+
+## Overview
+Called for `textDocument/references`. Return all read/write locations of a symbol.
+
+## Signature
+`(document: TextDocument, position: Position, context: ReferenceContext, token: CancellationToken) => Location[] | Promise<Location[]>`
+
+## Best practices
+- Honor `context.includeDeclaration`.
+- Map through source maps; dedupe results across virtual/source files.
+- Batch I/O; avoid per-file scans where possible.
+
+## Example
+```ts
+provideReferences(document, position, ctx) {
+  const refs = findRefs(document, position, { includeDecl: ctx.includeDeclaration });
+  return dedupeLocations(refs);
+}
+```
+
+## Troubleshooting
+- Missing references: ensure index includes embedded regions.
+- Too many: scope to project/workspace boundaries intentionally.
+
diff --git a/src/content/docs/service-methods/provide-rename-edits.mdx b/src/content/docs/service-methods/provide-rename-edits.mdx
new file mode 100644
index 0000000..dc9fb0b
--- /dev/null
+++ b/src/content/docs/service-methods/provide-rename-edits.mdx
@@ -0,0 +1,30 @@
+---
+title: provideRenameEdits
+description: Provide a workspace edit to rename a symbol.
+---
+
+## Overview
+Called for `textDocument/rename`. Compute all edits needed to rename the symbol at position to `newName`.
+
+## Signature
+`(document: TextDocument, position: Position, newName: string, token: CancellationToken) => WorkspaceEdit | Promise<WorkspaceEdit>`
+
+## Best practices
+- Validate `newName` (identifiers only) and provide errors early.
+- Use symbol references; include declaration if appropriate.
+- Map edits across source/virtual files; dedupe.
+
+## Example
+```ts
+provideRenameEdits(doc, pos, newName) {
+  const refs = findRefs(doc, pos, { includeDecl: true });
+  const changes = groupByUri(refs, r => ({ range: r.range, newText: newName }));
+  return { changes };
+}
+```
+
+## Troubleshooting
+- Partial rename: ensure refs include embedded regions.
+- Collisions: validate the target scope before applying edits.
+
+
diff --git a/src/content/docs/service-methods/provide-selection-ranges.mdx b/src/content/docs/service-methods/provide-selection-ranges.mdx
new file mode 100644
index 0000000..c367df8
--- /dev/null
+++ b/src/content/docs/service-methods/provide-selection-ranges.mdx
@@ -0,0 +1,19 @@
+---
+title: provideSelectionRanges
+description: Provide selection ranges that expand semantically from positions.
+---
+
+## Overview
+Return a hierarchy of ranges that the editor can use to expand/shrink selection (e.g., identifier → call → block).
+
+## Signature
+`(document: TextDocument, positions: Position[], token: CancellationToken) => SelectionRange[] | Promise<SelectionRange[]>`
+
+## Example
+```ts
+provideSelectionRanges(doc, positions) {
+  return positions.map(p => computeSelectionPyramid(doc, p));
+}
+```
+
+
diff --git a/src/content/docs/service-methods/provide-signature-help.mdx b/src/content/docs/service-methods/provide-signature-help.mdx
new file mode 100644
index 0000000..ab08d48
--- /dev/null
+++ b/src/content/docs/service-methods/provide-signature-help.mdx
@@ -0,0 +1,32 @@
+---
+title: provideSignatureHelp
+description: Provide parameter hints and active signature at a position.
+---
+
+## Overview
+Called for `textDocument/signatureHelp`. Show function overloads and active parameter while typing arguments.
+
+## Signature
+`(document: TextDocument, position: Position, token: CancellationToken) => SignatureHelp | Promise<SignatureHelp>`
+
+## Best practices
+- Compute activeSignature/activeParameter accurately.
+- Handle partial/invalid syntax gracefully.
+- Debounce heavy symbol lookups, cache per snapshot.
+
+## Example
+```ts
+provideSignatureHelp(doc, pos) {
+  const call = findCallExpression(doc, pos);
+  if (!call) return;
+  return {
+    signatures: call.overloads.map(o => ({ label: o.label, parameters: o.params.map(p => ({ label: p })) })),
+    activeSignature: call.activeIndex,
+    activeParameter: call.argIndex,
+  };
+}
+```
+
+## Troubleshooting
+- Wrong active parameter: double-check comma/paren scanning rules.
+
diff --git a/src/content/docs/service-methods/resolve-code-action.mdx b/src/content/docs/service-methods/resolve-code-action.mdx
new file mode 100644
index 0000000..8786a66
--- /dev/null
+++ b/src/content/docs/service-methods/resolve-code-action.mdx
@@ -0,0 +1,34 @@
+---
+title: resolveCodeAction
+description: Compute or finalize edits/commands for a selected code action.
+---
+
+## Overview
+Called for `codeAction/resolve`. Fill in edits and commands for a chosen action. Great for expensive or context-heavy edits.
+
+## Signature
+`(action: CodeAction, token: CancellationToken) => CodeAction | Promise<CodeAction>`
+
+## Best practices
+- Use `action.data` to carry identifiers from `provideCodeActions`.
+- Validate ranges against the latest snapshot; re-map if needed.
+- Respect cancellations to avoid UI jank.
+
+## Example
+```ts
+resolveCodeAction(action, token) {
+  if (action.data?.fix === 'add-attr') {
+    const edit = /* compute TextEdit[] */;
+    action.edit = { changes: { [action.data.uri]: edit } };
+  }
+  return action;
+}
+```
+
+## Troubleshooting
+- Edits not applied: ensure URIs and versions match client expectations.
+- Multi-file: use `WorkspaceEdit.changes` across files or `documentChanges`.
+
+## Related
+- [provideCodeActions](/service-methods/provide-code-actions)
+
diff --git a/src/content/docs/service-methods/resolve-code-lens.mdx b/src/content/docs/service-methods/resolve-code-lens.mdx
new file mode 100644
index 0000000..59ddb8f
--- /dev/null
+++ b/src/content/docs/service-methods/resolve-code-lens.mdx
@@ -0,0 +1,25 @@
+---
+title: resolveCodeLens
+description: Compute the command for a specific code lens.
+---
+
+## Overview
+Called for `codeLens/resolve`. Fill `command` for a selected lens. Useful for lazy test runs, navigation, etc.
+
+## Signature
+`(codeLens: CodeLens, token: CancellationToken) => CodeLens | Promise<CodeLens>`
+
+## Example
+```ts
+resolveCodeLens(lens) {
+  if (lens.data?.testId) {
+    lens.command = { title: 'Run Test', command: 'extension.runTest', arguments: [lens.data.testId] };
+  }
+  return lens;
+}
+```
+
+## Troubleshooting
+- Missing commands: verify command is contributed in the client extension.
+
+
diff --git a/src/content/docs/service-methods/resolve-completion-item.mdx b/src/content/docs/service-methods/resolve-completion-item.mdx
new file mode 100644
index 0000000..1dfcea8
--- /dev/null
+++ b/src/content/docs/service-methods/resolve-completion-item.mdx
@@ -0,0 +1,35 @@
+---
+title: resolveCompletionItem
+description: Enrich a selected completion item with additional data.
+---
+
+## Overview
+Called when a user selects a completion item. Perform expensive lookups (documentation, edits, imports) on demand.
+
+## Signature
+`(item: CompletionItem, token: CancellationToken) => CompletionItem | Promise<CompletionItem>`
+
+## Best practices
+- Keep `provideCompletionItems` lightweight; move cost here.
+- Use `data` field on items to identify what to resolve.
+- Respect cancellation; return early if `token.isCancellationRequested`.
+
+## Example
+```ts
+resolveCompletionItem(item, token) {
+  if (token.isCancellationRequested) return item;
+  if (item.data?.symbolId) {
+    item.detail = lookupDetail(item.data.symbolId);
+    item.documentation = getDocs(item.data.symbolId);
+  }
+  return item;
+}
+```
+
+## Troubleshooting
+- Missing docs: ensure `data` is carried from `provideCompletionItems`.
+- Jitter: avoid network requests on hot paths; cache by snapshot version.
+
+## Related
+- [provideCompletionItems](/service-methods/provide-completion-items)
+
diff --git a/src/content/docs/service-methods/resolve-document-link.mdx b/src/content/docs/service-methods/resolve-document-link.mdx
new file mode 100644
index 0000000..0ecb6a3
--- /dev/null
+++ b/src/content/docs/service-methods/resolve-document-link.mdx
@@ -0,0 +1,22 @@
+---
+title: resolveDocumentLink
+description: Resolve the target for a specific document link.
+---
+
+## Overview
+Called to compute `DocumentLink.target` lazily. Useful when link resolution requires I/O or project graph lookups.
+
+## Signature
+`(link: DocumentLink, token: CancellationToken) => DocumentLink | Promise<DocumentLink>`
+
+## Example
+```ts
+resolveDocumentLink(link) {
+  if (link.data?.href) {
+    link.target = toUri(link.data.href);
+  }
+  return link;
+}
+```
+
+
diff --git a/src/content/docs/service-methods/resolve-inlay-hint.mdx b/src/content/docs/service-methods/resolve-inlay-hint.mdx
new file mode 100644
index 0000000..11bb40d
--- /dev/null
+++ b/src/content/docs/service-methods/resolve-inlay-hint.mdx
@@ -0,0 +1,22 @@
+---
+title: resolveInlayHint
+description: Enrich an inlay hint with additional details lazily.
+---
+
+## Overview
+Called to resolve properties on a specific inlay hint, e.g., `tooltip` or `textEdits`.
+
+## Signature
+`(hint: InlayHint, token: CancellationToken) => InlayHint | Promise<InlayHint>`
+
+## Example
+```ts
+resolveInlayHint(hint) {
+  if (hint.data?.typeId) {
+    hint.tooltip = getTypeDocs(hint.data.typeId);
+  }
+  return hint;
+}
+```
+
+
diff --git a/src/content/docs/services/css.mdx b/src/content/docs/services/css.mdx
new file mode 100644
index 0000000..b507b87
--- /dev/null
+++ b/src/content/docs/services/css.mdx
@@ -0,0 +1,49 @@
+---
+title: volar-service-css
+description: Integrate vscode-css-languageservice into Volar.
+---
+
+### What it does
+Provides CSS language features (diagnostics, completions, hovers, document colors, color presentations, formatting, symbols, folding/selection ranges) for `style` blocks and standalone CSS files in embedded projects.
+
+### How it works
+Wraps `vscode-css-languageservice` behind Volar’s Service Plugin interface. The service analyzes CSS documents (including virtual embedded CSS) and responds to LSP-style hooks.
+
+### Why use it
+- Add first-class CSS editing features to any language server built on Volar.
+- Works for embedded CSS (e.g. within SFCs or HTML) and plain `.css` files.
+
+### Install
+
+```bash
+npm i volar-service-css
+```
+
+### Usage
+
+```ts
+import { create as createCss } from 'volar-service-css';
+
+getServicePlugins() {
+  return [
+    createCss(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements (via underlying CSS LS):
+  - provideCompletionItems, resolveCompletionItem
+  - provideHover
+  - provideDocumentSymbols
+  - provideDocumentColors, provideColorPresentations
+  - provideDocumentFormattingEdits, provideDocumentRangeFormattingEdits, provideOnTypeFormattingEdits
+  - provideFoldingRanges, provideSelectionRanges
+  - provideDocumentLinks
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/css`
+- Upstream LS: `https://github.com/microsoft/vscode-css-languageservice`
+
+
diff --git a/src/content/docs/services/emmet.mdx b/src/content/docs/services/emmet.mdx
new file mode 100644
index 0000000..8b2256b
--- /dev/null
+++ b/src/content/docs/services/emmet.mdx
@@ -0,0 +1,41 @@
+---
+title: volar-service-emmet
+description: Integrate @vscode/emmet-helper into Volar for abbreviation expansion.
+---
+
+### What it does
+Provides Emmet abbreviation expansion and related completions in HTML/CSS-like contexts.
+
+### How it works
+Wraps `@vscode/emmet-helper` and exposes completion hooks through Volar’s service API.
+
+### Why use it
+- Speed up authoring of markup and styles with Emmet.
+
+### Install
+
+```bash
+npm i volar-service-emmet
+```
+
+### Usage
+
+```ts
+import { create as createEmmet } from 'volar-service-emmet';
+
+getServicePlugins() {
+  return [
+    createEmmet(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements: provideCompletionItems (Emmet expansions), resolveCompletionItem.
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/emmet`
+- Upstream helper: `https://github.com/microsoft/vscode/tree/main/extensions/emmet`
+
+
diff --git a/src/content/docs/services/eslint.mdx b/src/content/docs/services/eslint.mdx
new file mode 100644
index 0000000..8eb7618
--- /dev/null
+++ b/src/content/docs/services/eslint.mdx
@@ -0,0 +1,41 @@
+---
+title: volar-service-eslint
+description: Integrate ESLint diagnostics into Volar.
+---
+
+### What it does
+Runs ESLint over relevant documents and surfaces diagnostics and quick fixes via Volar.
+
+### How it works
+Executes ESLint through the service and maps results to LSP diagnostics and code actions where possible.
+
+### Why use it
+- Keep code quality feedback in the same pipeline as language features.
+
+### Install
+
+```bash
+npm i volar-service-eslint
+```
+
+### Usage
+
+```ts
+import { create as createEslint } from 'volar-service-eslint';
+
+getServicePlugins() {
+  return [
+    createEslint(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements: diagnostics, provideCodeActions/resolveCodeAction (for applicable fixes).
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/eslint`
+- ESLint: `https://eslint.org/`
+
+
diff --git a/src/content/docs/services/html.mdx b/src/content/docs/services/html.mdx
new file mode 100644
index 0000000..8833fc7
--- /dev/null
+++ b/src/content/docs/services/html.mdx
@@ -0,0 +1,42 @@
+---
+title: volar-service-html
+description: Integrate vscode-html-languageservice into Volar.
+---
+
+### What it does
+Provides HTML language features (completions, hovers, validation, linked editing, formatting, symbols, folding/selection ranges) for templates and `.html` files.
+
+### How it works
+Wraps `vscode-html-languageservice` behind Volar’s Service Plugin interface to power LSP-like hooks for HTML and embedded HTML.
+
+### Why use it
+- HTML editor features for any Volar-based server.
+- Works across embedded templates and standalone HTML files.
+
+### Install
+
+```bash
+npm i volar-service-html
+```
+
+### Usage
+
+```ts
+import { create as createHtml } from 'volar-service-html';
+
+getServicePlugins() {
+  return [
+    createHtml(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements (via HTML LS): provideCompletionItems/resolveCompletionItem, provideHover, provideDocumentSymbols, provideDocumentLinks, provideLinkedEditingRanges, provideDocumentFormattingEdits/Range/OnType, provideFoldingRanges, provideSelectionRanges.
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/html`
+- Upstream LS: `https://github.com/microsoft/vscode-html-languageservice`
+
+
diff --git a/src/content/docs/services/json.mdx b/src/content/docs/services/json.mdx
new file mode 100644
index 0000000..7791e7b
--- /dev/null
+++ b/src/content/docs/services/json.mdx
@@ -0,0 +1,41 @@
+---
+title: volar-service-json
+description: Integrate vscode-json-languageservice into Volar.
+---
+
+### What it does
+Provides JSON features with schema-aware validation, completions, hovers, formatting, and symbols for `.json` and embedded JSON.
+
+### How it works
+Wraps `vscode-json-languageservice` to respond to Volar service hooks, optionally leveraging JSON Schemas discovered by the upstream LS.
+
+### Why use it
+- First-class JSON authoring and schema support in embedded contexts and plain `.json`.
+
+### Install
+
+```bash
+npm i volar-service-json
+```
+
+### Usage
+
+```ts
+import { create as createJson } from 'volar-service-json';
+
+getServicePlugins() {
+  return [
+    createJson(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements (via JSON LS): provideCompletionItems/resolveCompletionItem, provideHover, provideDocumentSymbols, provideDocumentLinks, provideDocumentFormattingEdits/Range, provideFoldingRanges, provideSelectionRanges, diagnostics (schema-based).
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/json`
+- Upstream LS: `https://github.com/microsoft/vscode-json-languageservice`
+
+
diff --git a/src/content/docs/services/markdown.mdx b/src/content/docs/services/markdown.mdx
new file mode 100644
index 0000000..6977a48
--- /dev/null
+++ b/src/content/docs/services/markdown.mdx
@@ -0,0 +1,41 @@
+---
+title: volar-service-markdown
+description: Integrate vscode-markdown-languageservice into Volar.
+---
+
+### What it does
+Provides Markdown features like hovers, links, symbols, folding/selection ranges, and formatting for `.md`/`.mdx` (where supported).
+
+### How it works
+Wraps `vscode-markdown-languageservice` to deliver LSP-style features for Markdown documents in Volar-based servers.
+
+### Why use it
+- Rich Markdown authoring inside multi-language workspaces or embedded contexts.
+
+### Install
+
+```bash
+npm i volar-service-markdown
+```
+
+### Usage
+
+```ts
+import { create as createMarkdown } from 'volar-service-markdown';
+
+getServicePlugins() {
+  return [
+    createMarkdown(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements (via Markdown LS): provideHover, provideDocumentSymbols, provideDocumentLinks, provideFoldingRanges, provideSelectionRanges, provideDocumentFormattingEdits/Range (where supported).
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/markdown`
+- Upstream LS: `https://github.com/microsoft/vscode`
+
+
diff --git a/src/content/docs/services/prettier.mdx b/src/content/docs/services/prettier.mdx
new file mode 100644
index 0000000..732e6d5
--- /dev/null
+++ b/src/content/docs/services/prettier.mdx
@@ -0,0 +1,56 @@
+---
+title: volar-service-prettier
+description: Integrate Prettier as a formatter within Volar.
+---
+
+### What it does
+Adds Prettier-based formatting for supported languages.
+
+### How it works
+Bridges Prettier through Volar’s formatting hooks, with optional language-specific controls and a resolver for Prettier options.
+
+### Why use it
+- Enforce consistent code style using your existing Prettier config.
+
+### Install
+
+```bash
+npm i volar-service-prettier
+```
+
+### Usage
+
+```ts
+import { create as createPrettier } from 'volar-service-prettier';
+
+getServicePlugins() {
+  return [
+    createPrettier(
+      {
+        languages: ['html', 'css', 'scss', 'typescript', 'javascript'],
+        html: { breakContentsFromTags: true },
+        ignoreIdeOptions: true,
+      },
+      // Provide Prettier options programmatically (optional).
+      () => ({
+        // ...your Prettier config here...
+      })
+    ),
+  ];
+}
+```
+
+### API
+- Export: `create(options?, resolvePrettierOptions?) => ServicePlugin`
+- Implements: provideDocumentFormattingEdits, provideDocumentRangeFormattingEdits, provideOnTypeFormattingEdits.
+- Options highlights:
+  - `languages?: string[]`
+  - `html?: { breakContentsFromTags?: boolean }`
+  - `ignoreIdeOptions?: boolean`
+  - `resolvePrettierOptions?: () => PrettierOptions`
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/prettier`
+- Prettier: `https://prettier.io/`
+
+
diff --git a/src/content/docs/services/prettyhtml.mdx b/src/content/docs/services/prettyhtml.mdx
new file mode 100644
index 0000000..5b2936d
--- /dev/null
+++ b/src/content/docs/services/prettyhtml.mdx
@@ -0,0 +1,40 @@
+---
+title: volar-service-prettyhtml
+description: Integrate prettyhtml as a formatter for HTML-like content.
+---
+
+### What it does
+Provides HTML formatting via `prettyhtml`.
+
+### How it works
+Calls `prettyhtml` under Volar’s formatting hooks for HTML/templating contexts.
+
+### Why use it
+- Opinionated HTML formatting alternative to Prettier where desired.
+
+### Install
+
+```bash
+npm i volar-service-prettyhtml
+```
+
+### Usage
+
+```ts
+import { create as createPrettyhtml } from 'volar-service-prettyhtml';
+
+getServicePlugins() {
+  return [
+    createPrettyhtml(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements: provideDocumentFormattingEdits, provideDocumentRangeFormattingEdits.
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/prettyhtml`
+
+
diff --git a/src/content/docs/services/pug-beautify.mdx b/src/content/docs/services/pug-beautify.mdx
new file mode 100644
index 0000000..3bc280a
--- /dev/null
+++ b/src/content/docs/services/pug-beautify.mdx
@@ -0,0 +1,40 @@
+---
+title: volar-service-pug-beautify
+description: Integrate pug-beautify into Volar for formatting.
+---
+
+### What it does
+Adds Pug code formatting via `pug-beautify`.
+
+### How it works
+Wires `pug-beautify` as a Volar formatting provider through the service interface.
+
+### Why use it
+- Consistent and configurable Pug formatting inside your Volar-based server.
+
+### Install
+
+```bash
+npm i volar-service-pug-beautify
+```
+
+### Usage
+
+```ts
+import { create as createPugBeautify } from 'volar-service-pug-beautify';
+
+getServicePlugins() {
+  return [
+    createPugBeautify(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements: provideDocumentFormattingEdits, provideDocumentRangeFormattingEdits.
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/pug-beautify`
+
+
diff --git a/src/content/docs/services/pug.mdx b/src/content/docs/services/pug.mdx
new file mode 100644
index 0000000..0306c11
--- /dev/null
+++ b/src/content/docs/services/pug.mdx
@@ -0,0 +1,40 @@
+---
+title: volar-service-pug
+description: Integrate Pug into Volar for template authoring.
+---
+
+### What it does
+Adds Pug template language features (diagnostics, completions, hovers, formatting, symbols) for Pug blocks and files.
+
+### How it works
+Provides a Pug-aware service that parses and maps Pug templates to HTML/AST behind Volar’s service interface, enabling common LSP hooks.
+
+### Why use it
+- First-class Pug authoring in frameworks that embed Pug templates.
+
+### Install
+
+```bash
+npm i volar-service-pug
+```
+
+### Usage
+
+```ts
+import { create as createPug } from 'volar-service-pug';
+
+getServicePlugins() {
+  return [
+    createPug(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements: provideCompletionItems/resolveCompletionItem, provideHover, provideDocumentSymbols, provideDocumentFormattingEdits/Range, provideFoldingRanges, provideSelectionRanges, diagnostics.
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/pug`
+
+
diff --git a/src/content/docs/services/sass-formatter.mdx b/src/content/docs/services/sass-formatter.mdx
new file mode 100644
index 0000000..4718833
--- /dev/null
+++ b/src/content/docs/services/sass-formatter.mdx
@@ -0,0 +1,40 @@
+---
+title: volar-service-sass-formatter
+description: Integrate sass-formatter for SCSS/Sass formatting.
+---
+
+### What it does
+Adds formatting for SCSS/Sass sources via `sass-formatter`.
+
+### How it works
+Wires `sass-formatter` through Volar’s formatting hooks.
+
+### Why use it
+- Consistent Sass/SCSS formatting aligned with your style guidelines.
+
+### Install
+
+```bash
+npm i volar-service-sass-formatter
+```
+
+### Usage
+
+```ts
+import { create as createSassFormatter } from 'volar-service-sass-formatter';
+
+getServicePlugins() {
+  return [
+    createSassFormatter(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements: provideDocumentFormattingEdits, provideDocumentRangeFormattingEdits.
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/sass-formatter`
+
+
diff --git a/src/content/docs/services/tslint.mdx b/src/content/docs/services/tslint.mdx
new file mode 100644
index 0000000..fa973e6
--- /dev/null
+++ b/src/content/docs/services/tslint.mdx
@@ -0,0 +1,41 @@
+---
+title: volar-service-tslint
+description: Integrate TSLint diagnostics into Volar (legacy).
+---
+
+### What it does
+Surfaces TSLint diagnostics and quick fixes where applicable.
+
+### How it works
+Invokes TSLint via the service and maps results to LSP diagnostics/actions.
+
+### Why use it
+- Only for legacy codebases still using TSLint (TSLint is deprecated).
+
+### Install
+
+```bash
+npm i volar-service-tslint
+```
+
+### Usage
+
+```ts
+import { create as createTslint } from 'volar-service-tslint';
+
+getServicePlugins() {
+  return [
+    createTslint(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements: diagnostics, provideCodeActions/resolveCodeAction (where applicable).
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/tslint`
+- TSLint: `https://github.com/palantir/tslint` (deprecated)
+
+
diff --git a/src/content/docs/services/typescript-twoslash-queries.mdx b/src/content/docs/services/typescript-twoslash-queries.mdx
new file mode 100644
index 0000000..81a45e3
--- /dev/null
+++ b/src/content/docs/services/typescript-twoslash-queries.mdx
@@ -0,0 +1,41 @@
+---
+title: volar-service-typescript-twoslash-queries
+description: Integrate TypeScript Twoslash queries into Volar for inline type exploration.
+---
+
+### What it does
+Enables TypeScript Twoslash queries (e.g. `// ^?`) to inspect inferred types and symbols inline.
+
+### How it works
+Parses special Twoslash comment queries in TS/JS and returns results via service hooks for display in editors.
+
+### Why use it
+- Great for docs, learning, and debugging types inside the editor.
+
+### Install
+
+```bash
+npm i volar-service-typescript-twoslash-queries
+```
+
+### Usage
+
+```ts
+import { create as createTsTwoslash } from 'volar-service-typescript-twoslash-queries';
+
+getServicePlugins() {
+  return [
+    createTsTwoslash(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements: hooks to evaluate Twoslash queries and surface results (editor integrations may present them as hovers or decorations).
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/typescript-twoslash-queries`
+- Twoslash: `https://www.typescriptlang.org/dev/twoslash/`
+
+
diff --git a/src/content/docs/services/typescript.mdx b/src/content/docs/services/typescript.mdx
new file mode 100644
index 0000000..b2637dd
--- /dev/null
+++ b/src/content/docs/services/typescript.mdx
@@ -0,0 +1,41 @@
+---
+title: volar-service-typescript
+description: Integrate TypeScript features into Volar.
+---
+
+### What it does
+Provides TypeScript language features (completions, diagnostics, hovers, definitions, references, code actions/refactors, inlay hints, semantic tokens, formatting) for `script` blocks and TS/JS files in embedded projects.
+
+### How it works
+Bridges the TypeScript Language Service into Volar’s service runtime and handles embedded TS/JS via virtual documents and source maps.
+
+### Why use it
+- First-class TS/JS authoring in frameworks with embedded scripts.
+
+### Install
+
+```bash
+npm i volar-service-typescript
+```
+
+### Usage
+
+```ts
+import { create as createTs } from 'volar-service-typescript';
+
+getServicePlugins() {
+  return [
+    createTs(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements (via TS LS): provideCompletionItems/resolveCompletionItem, provideHover, provideSignatureHelp, provideDefinition, provideReferences, provideCallHierarchyItems/IncomingCalls/OutgoingCalls, provideCodeActions/resolveCodeAction, provideRenameEdits, provideDocumentSemanticTokens/Edits, provideInlayHints/resolveInlayHint, provideDocumentSymbols, provideDocumentFormattingEdits/Range/OnType, diagnostics, more TS-specific transforms.
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/typescript`
+- TypeScript LS: `https://github.com/microsoft/TypeScript/wiki/Using-the-Language-Service-API`
+
+
diff --git a/src/content/docs/services/vetur.mdx b/src/content/docs/services/vetur.mdx
new file mode 100644
index 0000000..4b2aa2f
--- /dev/null
+++ b/src/content/docs/services/vetur.mdx
@@ -0,0 +1,40 @@
+---
+title: volar-service-vetur
+description: Vetur compatibility features for Volar-based servers.
+---
+
+### What it does
+Provides Vetur-style features/compatibility layers (e.g. component data, tags/attributes sources, and related helpers) inside Volar.
+
+### How it works
+Implements compatibility shims and data sources to emulate or bridge Vetur capabilities via Volar service hooks.
+
+### Why use it
+- Smooth migration or coexistence with Vetur-powered workflows/tools.
+
+### Install
+
+```bash
+npm i volar-service-vetur
+```
+
+### Usage
+
+```ts
+import { create as createVetur } from 'volar-service-vetur';
+
+getServicePlugins() {
+  return [
+    createVetur(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements: provideCompletionItems/resolveCompletionItem (for tags/attrs), provideHover, provideDocumentSymbols, diagnostics (where applicable).
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/vetur`
+
+
diff --git a/src/content/docs/services/yaml.mdx b/src/content/docs/services/yaml.mdx
new file mode 100644
index 0000000..00e8055
--- /dev/null
+++ b/src/content/docs/services/yaml.mdx
@@ -0,0 +1,41 @@
+---
+title: volar-service-yaml
+description: Integrate yaml-language-server into Volar.
+---
+
+### What it does
+Provides YAML features including schema-based validation, completions, hovers, formatting, and symbols for `.yaml`/`.yml`.
+
+### How it works
+Embeds `yaml-language-server` through Volar’s service interface to serve LSP-like functionality for YAML.
+
+### Why use it
+- YAML authoring with JSON Schema support inside embedded-language projects.
+
+### Install
+
+```bash
+npm i volar-service-yaml
+```
+
+### Usage
+
+```ts
+import { create as createYaml } from 'volar-service-yaml';
+
+getServicePlugins() {
+  return [
+    createYaml(),
+  ];
+}
+```
+
+### API
+- Export: `create(options?) => ServicePlugin`
+- Implements (via YAML LS): provideCompletionItems/resolveCompletionItem, provideHover, provideDocumentSymbols, provideDocumentLinks, provideDocumentFormattingEdits/Range, provideFoldingRanges, diagnostics (schema-aware).
+
+### Links
+- Source: `https://github.com/volarjs/services/tree/master/packages/yaml`
+- Upstream LS: `https://github.com/redhat-developer/yaml-language-server`
+
+
diff --git a/src/content/docs/core-concepts/volar-labs-1.png b/src/content/docs/tools/volar-labs-1.png
similarity index 100%
rename from src/content/docs/core-concepts/volar-labs-1.png
rename to src/content/docs/tools/volar-labs-1.png
diff --git a/src/content/docs/core-concepts/volar-labs.mdx b/src/content/docs/tools/volar-labs.mdx
similarity index 100%
rename from src/content/docs/core-concepts/volar-labs.mdx
rename to src/content/docs/tools/volar-labs.mdx

From 4252737cca94b22b0d5eb25cdece9fb5498c8335 Mon Sep 17 00:00:00 2001
From: Luke Hagar <lukeslakemail@gmail.com>
Date: Tue, 11 Nov 2025 16:00:12 +0000
Subject: [PATCH 2/2] Add "Guides" section to astro.config.ts for
 autogeneration of documentation

---
 astro.config.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/astro.config.ts b/astro.config.ts
index 112bb11..955b15e 100644
--- a/astro.config.ts
+++ b/astro.config.ts
@@ -40,6 +40,10 @@ export default defineConfig({
           label: "Core Concepts",
           autogenerate: { directory: "core-concepts" },
         },
+        {
+          label: "Guides",
+          autogenerate: { directory: "guides" },
+        },
         {
           label: "Service Methods",
           autogenerate: { directory: "service-methods" },