# VolarJS Documentation Hub

VolarJS powers Vue tooling across editors, yet the official docs are scattered. This repository collects practical, engineer-focused notes about the Volar language server so teams can understand, extend, and debug it without spelunking through source code.

## Scope
- Explain Volar architecture: core packages, key entrypoints, and how they plug into editor hosts.
- Document the LSP surface that Volar implements (capabilities, custom requests, known quirks).
- Share recipes for common tasks such as adding diagnostics, language features, or IDE integrations.
- Track ecosystem tooling (volar-service modules, language plugins, CLI utilities) and their compatibility.
- Publish getting-started and integration guides (e.g., combining Volar with JSON/YAML language services).

## Roadmap
1. **Landscape survey** – catalogue existing blog posts, RFCs, and source references.
2. **LSP deep dive** – map each request / notification to the Volar handlers and note deviations from the spec.
3. **Extensibility guide** – document how to write and register custom language features.
4. **Debugging playbook** – logging, tracing, and profiling techniques for the Volar server process.

## Repo Structure
Planned directories:
- `docs/` – longer-form guides (architecture, extensibility, debugging). See the [docs index](docs/README.md) for a full table of contents.
- `docs/live-examples.md` – curated list of real projects using VolarJS (VS Code extension, Neovim/LSP integrations, online IDEs, CLI tooling, community plugins).
- Key guides (see [docs index](docs/README.md) for the full list):
  - [`docs/getting-started.md`](docs/getting-started.md)
  - [`docs/building-lsp-json-yaml.md`](docs/building-lsp-json-yaml.md)
  - [`docs/plugin-authoring.md`](docs/plugin-authoring.md)
  - [`docs/source-map-and-code-gen.md`](docs/source-map-and-code-gen.md)
  - [`docs/configuration-and-projects.md`](docs/configuration-and-projects.md)
  - [`docs/performance-and-debugging.md`](docs/performance-and-debugging.md)
  - [`docs/testing-and-ci.md`](docs/testing-and-ci.md)
  - [`docs/telemetry-and-observability.md`](docs/telemetry-and-observability.md)
  - [`docs/workspace-diagnostics.md`](docs/workspace-diagnostics.md)
  - [`docs/error-handling-and-resilience.md`](docs/error-handling-and-resilience.md)
  - [`docs/ux-best-practices.md`](docs/ux-best-practices.md)
  - [`docs/lsp-benchmarking.md`](docs/lsp-benchmarking.md)
  - [`docs/troubleshooting-faq.md`](docs/troubleshooting-faq.md)
  - [`docs/release-and-upgrade.md`](docs/release-and-upgrade.md)
  - [`docs/vetur-migration.md`](docs/vetur-migration.md)
  - [`docs/custom-diagnostics.md`](docs/custom-diagnostics.md)
  - [`docs/monaco-playground.md`](docs/monaco-playground.md)
  - [`docs/volar-kit-and-editor.md`](docs/volar-kit-and-editor.md)
  - [`docs/typescript-plugin-deep-dive.md`](docs/typescript-plugin-deep-dive.md)
  - [`docs/volar-service-catalog.md`](docs/volar-service-catalog.md)
  - [`docs/cli-integration.md`](docs/cli-integration.md)
  - [`docs/editor-integration-alt.md`](docs/editor-integration-alt.md)
  - [`docs/cross-language-recipes.md`](docs/cross-language-recipes.md)
  - [`docs/package-api-reference.md`](docs/package-api-reference.md)
  - [`docs/response-formatting.md`](docs/response-formatting.md)
  - [`docs/cross-language-recipes.md`](docs/cross-language-recipes.md)
  - [`docs/package-api-reference.md`](docs/package-api-reference.md)
  - [`docs/telemetry-and-observability.md`](docs/telemetry-and-observability.md)
- `reference/` – API and protocol notes, ideally generated from code comments over time.
- `examples/` – minimal projects showing custom Volar features in action.
  - `examples/json-yaml-lsp` – runnable server that mixes Volar with JSON/YAML services.

## Contributing
Issues and PRs are welcome. Please prefer:
- Real-world examples that demonstrate a concept.
- Links back to Volar source or specs for verification.
- Clear reproduction steps for bugs or editor quirks.

---
This repo is intentionally lightweight—start by dropping notes in Markdown, then iterate toward polished docs once content stabilizes.