Proposal: define vp doc around documentation adapters

[kazupon]

The Q3 roadmap says that vp doc will support multiple documentation generators and that each project can select one, following the package-manager approach. Before writing an RFC, I think we should define which problem Vite+ is solving and which semantics should remain stable across generators.

This proposal calls each Vite+ integration a documentation adapter. VitePress, TypeDoc, and similar projects remain the underlying tools or generators. An adapter is the Vite+ layer that detects one of those tools, declares its supported actions, and maps the common vp doc actions to its native CLI.

I hope this discussion can serve as a starting point for the pre-RFC design conversation and help shape the eventual RFC.

There is no established meaning for a doc command:

• npm docs opens a package's documentation URL.
• cargo doc generates API reference HTML.
• go doc and deno doc can print API information in the terminal.
• VitePress provides dev, build, and preview for a documentation site.
• TypeDoc generates API documentation from TypeScript exports and comments.
• Ox Content is an unofficial, framework-agnostic documentation generator and Markdown toolkit. Its Vite plugin combines Markdown SSG, JSDoc/TypeScript API docs, search, theming, and OG images, and runs the docs app through Vite or Vite+ commands such as vp dev.

Because these tools solve different problems, vp doc should not silently mean "open a URL", "generate API docs", or "start a site" based on whether Vite+ guesses that the project is a library or an application.

Proposed value

vp doc should provide a stable entry point for a project's documentation workflow through a selected adapter.

This gives projects:

• one documented command for contributors, CI, and coding agents;
• an explicit, version-controlled adapter selection;
• consistent adapter discovery, workspace targeting, errors, and exit codes;
• the ability to change the underlying tool without changing the basic build command;
• access to native tool configuration instead of a lowest-common-denominator Vite+ configuration layer.

Vite+ should own adapter selection and orchestration. Each adapter should own tool detection, capability declaration, and command mapping. The underlying tool should continue to own content, API extraction, rendering, themes, and tool-specific options.

This is similar to the package-manager model in one important way: Vite+ resolves the adapter selected by the project, the adapter maps a common operation to the underlying tool, and Vite+ executes it. It should not imply that documentation tools have the same capabilities or interchangeable configuration.

Proposed command model

vp doc                          # Show the selected adapter, tool, and supported actions
vp doc init [adapter]           # Explicitly select and set up an adapter
vp doc build                    # Generate production documentation
vp doc dev                      # Start the underlying tool's authoring/watch mode
vp doc preview                  # Preview a previous production build
vp doc <action> -- <args...>    # Forward native arguments to the underlying tool

build should be the only required adapter capability. dev and preview should be optional capabilities declared by each adapter.

vp doc build should include the underlying tool's native validation. For example, unresolved links or undocumented public APIs should make the command fail when the tool's configured strictness treats them as errors.

The initial contract should not expose a separate vp doc check action. deno doc --lint provides standalone documentation linting, while TypeDoc validation runs during conversion or rendering and VitePress dead-link detection runs as part of a build. Vite+ should not hide that difference by running an implicit temporary build or inventing its own generic documentation linter.

Bare vp doc should not generate files or start a long-running process. It should report the resolved adapter, its underlying tool, where the selection came from, and the actions that adapter supports. A --json form would make the same information usable by agents and tooling.

For an unsupported action, Vite+ should fail explicitly instead of emulating it or choosing another adapter:

error: The TypeDoc adapter does not support `vp doc preview`.
Supported actions: build, dev

Tool-specific arguments should be an escape hatch after --. Teams should prefer the underlying tool's native config file for repeatable settings.

Adapter selection

The project should be able to make the selection explicit in vite.config.ts:

import { defineConfig } from 'vite-plus';

export default defineConfig({
  doc: {
    adapter: 'vitepress',
  },
});

I propose this resolution order:

1. Use doc.adapter from the applicable Vite+ config.
2. If it is absent, detect supported adapters from installed documentation tools and their native config files.
3. If exactly one adapter candidate exists, use it and explain the detection source.
4. If no candidate or multiple candidates exist, fail with actionable guidance. Do not silently apply a precedence rule.

vp doc init would be the explicit mutating operation. It may prompt for an adapter, add the required underlying tool as a development dependency through the project's package manager, and write the adapter selection after confirmation.

Normal commands such as vp doc build must not install packages or modify project configuration. The selected adapter should execute the project-local tool, preserve its stdout, stderr, and exit status, and report a clear error when the underlying tool is not installed. The tool version should remain controlled by package.json and the lockfile, not by Vite+.

The Vite+ config should initially store orchestration data such as the selected adapter. Tool-specific settings should remain in files such as .vitepress/config.ts or typedoc.json.

Libraries, applications, and monorepos

Vite+ should not infer a documentation product from the project type.

• A library may select a TypeDoc adapter for API reference, a VitePress adapter for a guide, or an adapter for a site generator that integrates API output.
• An application may select a documentation-site adapter for architecture, operations, or user documentation. It should not receive API docs merely because source files exist.
• A project with no documentation adapter should receive setup guidance, not generated documentation based on a guess.

For the first version, I suggest one primary documentation adapter per applicable Vite+ config. The underlying tool may compose other tools through its native plugins or build process. Named documentation targets could be added later if real projects need multiple independently invoked outputs in the same package.

Monorepo targeting should follow the existing built-in command model:

vp -C docs doc dev
vp -C packages/sdk doc build

At a workspace root:

1. A root doc config represents an integrated workspace documentation site.
2. defaultPackage.doc may select a fixed documentation package.
3. If exactly one package has a configured or detected adapter, Vite+ may select it.
4. If several packages match, use the existing package picker in an interactive terminal and print vp -C ... doc ... choices in non-interactive environments.

vp doc build should not implicitly build every package in a workspace. Projects that need that behavior can define a Vite Task or package script and run it recursively with vp run. Vite+ should not invent automatic cross-generator site merging in the first version.

Adapter contract

An adapter needs to provide only a small contract:

• adapter identifier and associated tool package/binary names;
• deterministic tool and config detection signals;
• supported capabilities;
• command and argument mapping for each capability;
• optional metadata such as expected output directories.

The contract should be validated with at least one site-generator adapter and one API-generator adapter, for example VitePress and TypeDoc, before it is considered stable. This would expose invalid assumptions that are hidden when designing around only one category of tool.

Non-goals for the first version

• publishing documentation or managing hosting credentials;
• opening a package homepage like npm docs;
• terminal-level symbol lookup like go doc;
• replacing native tool configuration;
• automatically combining every package's output into one monorepo site;
• providing a Vite+-specific generic documentation linter or output-free check command;
• downloading or installing an underlying tool during normal dev, build, or preview commands.

Questions for the RFC

1. Should bare vp doc only report the selected adapter, underlying tool, and capabilities, or should it alias one action?
2. Is one primary adapter per config sufficient for the first version, or do we need named targets immediately?
3. Should unambiguous adapter detection from dependencies and native config files be accepted, or should doc.adapter always be required?
4. Which two adapters best validate both site-generation and API-generation use cases?
5. Are build, dev, and preview the right stable capability names?

My recommendation is to keep the first contract narrow: explicit adapter selection, a required build action, capability-based optional actions, native tool configuration, and existing Vite+ workspace targeting. That provides a useful common workflow without pretending that all documentation tools do the same job.

Appendix: existing documentation CLI prior art

The following commands informed this proposal. Commands with similar names expose materially different products: opening existing documentation, querying APIs, generating API references, running a documentation site, or publishing generated output.

Commands named doc or docs

Command	Model	Relevant behavior
npm docs	Open a URL	Infers and opens a package documentation URL. With no argument it uses the current package.json name. It supports multiple packages and workspace selection but does not generate documentation. Its alias is npm home.
rustup doc	Open local documentation	Opens the standard library, Rust Book, and other documentation installed with a Rust toolchain. It does not generate project documentation.
cargo doc	Generate API documentation	Generates documentation for the current Rust package and its dependencies under target/doc. It supports --open, --no-deps, private items, and explicit workspace/package/exclusion scopes.
go doc	Query and serve APIs	Prints package, symbol, method, or field documentation in the terminal. go doc -http serves HTML locally.
deno doc	Query, generate, and lint APIs	Prints exported JS/TS APIs by default, generates HTML or JSON, and uses --lint to diagnose public types and JSDoc. It accepts multiple entry points and npm: or jsr: packages.
dart doc	Generate and validate APIs	Generates public Dart API reference under doc/api. --dry-run reports problems without saving output. Serving the result requires a separate HTTP server.
crystal docs	Generate API documentation	Generates a static API site and index.json, using src/**/*.cr by default or explicit source entry points.
nim doc	Generate API documentation	Generates HTML from public symbols and documentation comments. --project covers a project, with related LaTeX and JSON commands available separately.
gleam docs build	Generate and publish documentation	Builds searchable package HTML. gleam publish publishes documentation with the package.
sbt doc	Generate API documentation as a task	Runs Javadoc for Java-only sources or Scaladoc when Scala is present, using task scopes such as Compile / doc.

Equivalent workflows under other names

Command/tool	Model	Relevant behavior
python -m pydoc	Query, generate, and serve APIs	Prints docstrings, writes HTML with -w, starts a local server with -p, or starts a server and browser with -b. It documents modules resolved in the active import environment.
javadoc	Generate API documentation	Generates HTML from Java declarations and documentation comments, using explicit packages, source files, or modules as input.
TypeDoc	Generate TypeScript API documentation	Generates HTML or JSON from TypeScript exports and comments. It can infer entry points from exports or main, expand source files, and combine package-mode results.
mix docs with ExDoc	Generate and compose documentation	An external dependency adds the task to Mix. It can combine API reference and additional documents, emit several formats, open output, fail on warnings, and aggregate or separate umbrella applications.
cabal haddock	Generate package or project API documentation	cabal haddock targets selected packages, while cabal haddock-project combines all local packages under ./haddocks.
dune build @doc	Generate project documentation	Uses odoc to build project HTML and associate additional .mld documents with packages. dune ocaml doc provides the same workflow through a dedicated command.
swift package generate-documentation	Generate documentation through a plugin	Swift-DocC adds a common command to Swift Package Manager and supports selecting a target with --target.
VitePress CLI	Develop, build, and preview a site	vitepress dev, build, and preview manage a Markdown documentation site. They do not extract an API reference from source code.
Ox Content	Generate documentation through a Vite plugin	This unofficial, framework-agnostic project combines Markdown SSG, JSDoc/TypeScript API docs, search, theming, and OG images. Its documentation app uses the Vite/Vite+ lifecycle, including vp dev, rather than adding a standalone doc command.

Cross-cutting observations

• There is no shared industry meaning for doc: it may open existing documentation, print API information, generate static output, run a site, validate content, or publish artifacts.
• The official pnpm CLI and Yarn CLI do not provide a built-in equivalent of npm docs. Opening a package URL is therefore npm-specific behavior, not a common JavaScript package-manager operation.
• Library generators commonly start from public entry points or exported symbols. Applications may have no stable public API and often need authored architecture, operations, or user documentation instead.
• Monorepo tools expose different scopes: the current package, a selected package, one combined workspace site, or separate output for every package. Cargo, TypeDoc, ExDoc, and Cabal make different choices and usually require an explicit scope.

These differences are why the proposal makes adapter selection explicit and gives each adapter a small, capability-based command contract instead of defining vp doc as a wrapper around one existing tool.

[fengmk2]

Similar to cargo doc, go doc, and deno doc, generating documentation through code is not what vp doc intends to support. I would choose to adapt document tools that fit the Vite ecosystem, such as pure documentation tools like VitePress, OxContent, Vocs, and Starlight.

[fengmk2]

vp doc RFC #2476 ，looking forward to hear your feedbacks.