docs: Update to recommend workspace + deno.jsonc for dependency management

This commit updates the Denops documentation to reflect the new recommended
approach for managing dependencies using workspace configuration and import maps.

Key changes:
- Explain workspace + deno.jsonc pattern as the recommended approach
- Clarify separation between development config (root) and runtime deps (plugin)
- Update all examples to use deno.jsonc instead of direct URL imports
- Add import map support to all tutorials (Hello World and Maze)
- Document support for import_map.json(c) as an alternative
- Explain why plugin-specific config prevents conflicts in merged runtime paths

The documentation now properly guides users to:
1. Use root deno.jsonc for development tools (lint, fmt, test)
2. Use plugin-specific deno.jsonc for runtime dependencies
3. Understand that both deno.json and import_map.json formats are supported

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: lambdalisue

src/getting-started/README.md

@@ -8,21 +8,57 @@ Let's start by creating a simple plugin to learn how to develop Denops plugins.
 
 ## Create a Plugin
 
-Create a directory named `denops-getting-started` in your home directory and a
-file named `main.ts` within it, under `denops/denops-getting-started/`:
+Create a directory named `denops-getting-started` in your home directory with the following structure:
 
 ```
 $HOME
 └── denops-getting-started
+    ├── deno.jsonc
     └── denops
         └── denops-getting-started
+            ├── deno.jsonc
             └── main.ts
 ```
 
+First, create a root `deno.jsonc` file for development configuration:
+
+```json,title=deno.jsonc
+{
+  "workspace": [
+    "./denops/denops-getting-started"
+  ]
+}
+```
+
+> [!TIP]
+>
+> The root `deno.jsonc` is for development purposes. It enables commands like
+> `deno fmt`, `deno lint`, and `deno test` to work from your project root.
+> You can add development-specific settings here without affecting runtime.
+
+Then, create a `deno.jsonc` file inside `denops/denops-getting-started/` for runtime dependencies:
+
+```json,title=denops/denops-getting-started/deno.jsonc
+{
+  "imports": {
+    "@denops/std": "jsr:@denops/std@^7.0.0"
+  }
+}
+```
+
+> [!NOTE]
+>
+> Denops supports multiple configuration formats:
+> - `deno.json` and `deno.jsonc` (recommended)
+> - `import_map.json` and `import_map.jsonc` (legacy support)
+> 
+> We use `deno.jsonc` in examples as it allows comments and requires less
+> verbose configuration than import maps.
+
 Next, write the following TypeScript code in `main.ts`:
 
 ```typescript,title=denops/denops-getting-started/main.ts
-import type { Entrypoint } from "jsr:@denops/std@^7.0.0";
+import type { Entrypoint } from "@denops/std";
 
 export const main: Entrypoint = (denops) => {
   denops.dispatcher = {
@@ -33,6 +69,16 @@ export const main: Entrypoint = (denops) => {
 };
 ```
 
+> [!IMPORTANT]
+>
+> We separate development configuration from runtime dependencies:
+> - **Root `deno.jsonc`**: Contains workspace configuration for development tools
+> - **Plugin `deno.jsonc`**: Contains import maps for runtime dependencies
+> 
+> This separation is crucial because the root `deno.jsonc` is only used during
+> development, while the plugin-specific `deno.jsonc` is what Denops uses at
+> runtime to resolve imports.
+
 ## Activate the Plugin
 
 Add the following line to your Vim or Neovim configuration file (e.g.,

src/getting-started/explanation.md

@@ -106,15 +106,22 @@ Let's break down this code step by step.
 
 ### About Imports
 
+In the Getting Started example, we used direct URL imports:
+
 ```typescript
 import type { Entrypoint } from "jsr:@denops/std@^7.0.0";
 ```
 
-The first line imports the `Entrypoint` type from the [@denops/std] standard
-library. You can find detailed information about the library by checking the
-URL: `https://jsr.io/@denops/[email protected]` (replace `jsr:` to `https://jsr.io/`).
-We fixed the version in the import URL, so it's recommended to check for details
-and update to the latest version URL.
+However, with the recommended `deno.jsonc` configuration approach, this becomes:
+
+```typescript
+import type { Entrypoint } from "@denops/std";
+```
+
+The import is resolved through the import map defined in `deno.jsonc`. The
+[@denops/std] standard library provides essential types and utilities for Denops
+plugin development. You can find detailed information about the library at
+`https://jsr.io/@denops/std`.
 
 Note that we use `import type` syntax, which is part of TypeScript's
 [Type-Only Imports and Export](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html).
@@ -215,7 +222,7 @@ For example, use
 Vim's function instead of `denops.call` like:
 
 ```typescript
-import * as fn from "jsr:@denops/std@^7.0.0/function";
+import * as fn from "@denops/std/function";
 
 // Bad (result1 is `unknown`)
 const result1 = await denops.call("expand", "%");
@@ -227,6 +234,208 @@ const result2 = await fn.expand(denops, "%");
 If developers use `function` module instead, they can benefit from features like
 auto-completion and type checking provided by LSP (Language Server Protocol).
 
+## Managing Dependencies with Workspace and Import Maps
+
+While the examples above use direct URL imports, the recommended approach for Denops plugins is to separate development configuration from runtime dependencies:
+
+- **Development configuration**: The root `deno.jsonc` with workspace settings enables development tools (`deno lint`, `deno fmt`, etc.) to work from the project root
+- **Runtime dependencies**: The plugin-specific `deno.jsonc` contains only the import map needed at runtime
+- **No conflicts**: Since each Denops plugin has a unique directory under `denops/`, their configuration files never conflict when installed
+- **Clean separation**: Development tools configuration stays in the repository root, while runtime dependencies are isolated per plugin
+- **Flexible format**: Both `deno.json` and `deno.jsonc` are supported, but `deno.jsonc` is recommended for its comment support
+
+### Separation of Development and Runtime Configuration
+
+The workspace pattern serves two distinct purposes:
+
+1. **Development Time**: The root `deno.jsonc` enables development commands to work properly:
+   ```json
+   {
+     "workspace": [
+       "./denops/your-plugin-name"
+     ],
+     "lint": {
+       "rules": {
+         "tags": ["recommended"]
+       }
+     },
+     "fmt": {
+       "indentWidth": 2
+     }
+   }
+   ```
+
+2. **Runtime**: The plugin's `deno.jsonc` contains only what's needed for execution:
+   ```json
+   {
+     "imports": {
+       "@denops/std": "jsr:@denops/std@^7.0.0"
+     }
+   }
+   ```
+
+### Why This Separation Matters
+
+When Vim/Neovim loads plugins, it merges all plugin directories into the runtime path. If runtime dependencies were in the root configuration file, they would conflict:
+
+```
+# After installation, plugins are merged:
+~/.vim/pack/plugins/start/
+├── plugin-a/
+│   ├── deno.jsonc      # Development config (not used at runtime)
+│   └── denops/
+│       └── plugin-a/
+│           └── deno.jsonc  # Runtime dependencies (unique path)
+└── plugin-b/
+    ├── deno.jsonc      # Development config (not used at runtime)
+    └── denops/
+        └── plugin-b/
+            └── deno.jsonc  # Runtime dependencies (unique path)
+```
+
+### Setting up Your Plugin
+
+1. Create a `deno.jsonc` in your repository root for development:
+
+```json
+{
+  "workspace": [
+    "./denops/your-plugin-name"
+  ],
+  // Development-specific configuration
+  "lint": {
+    "rules": {
+      "tags": ["recommended"]
+    }
+  },
+  "fmt": {
+    "indentWidth": 2,
+    "lineWidth": 80
+  },
+  "test": {
+    "include": ["denops/**/*_test.ts"]
+  }
+}
+```
+
+2. Create a `deno.jsonc` inside your plugin directory for runtime dependencies:
+
+```json
+// denops/your-plugin-name/deno.jsonc
+{
+  "imports": {
+    "@denops/std": "jsr:@denops/std@^7.0.0",
+    "@denops/core": "jsr:@denops/core@^7.0.0",
+    "@core/unknownutil": "jsr:@core/unknownutil@^4.3.0"
+  }
+}
+```
+
+This separation ensures:
+- Development tools like `deno fmt` and `deno lint` work from your project root
+- Runtime dependencies are properly resolved when the plugin is installed
+- No conflicts occur between multiple installed Denops plugins
+
+### Alternative: Using import_map.json(c)
+
+While the examples above use `deno.jsonc`, Denops also supports `import_map.json(c)` files in the plugin directory:
+
+```
+denops/your-plugin-name/
+├── import_map.jsonc  # Alternative to deno.jsonc
+└── main.ts
+```
+
+However, there are important differences:
+
+1. **Import Maps Standard** (import_map.json) requires both entries for submodules:
+   ```json
+   {
+     "imports": {
+       "@denops/std": "jsr:@denops/std@^7.0.0",
+       "@denops/std/": "jsr:@denops/std@^7.0.0/"  // Required for submodules
+     }
+   }
+   ```
+
+2. **deno.json Format** (recommended) needs only one entry:
+   ```json
+   {
+     "imports": {
+       "@denops/std": "jsr:@denops/std@^7.0.0"  // Handles both cases
+     }
+   }
+   ```
+
+> [!IMPORTANT]
+>
+> We recommend using `deno.jsonc` over `import_map.jsonc` because:
+> - It requires less verbose configuration
+> - It's the standard Deno configuration format
+> - It supports additional configuration options beyond imports
+> - Tools like `deno add` and `deno remove` work seamlessly with it
+
+With this configuration, you can update your imports from:
+
+```typescript
+import type { Entrypoint } from "jsr:@denops/std@^7.0.0";
+import { assert, is } from "jsr:@core/unknownutil@^4.3.0";
+```
+
+To cleaner import statements:
+
+```typescript
+import type { Entrypoint } from "@denops/std";
+import { assert, is } from "@core/unknownutil";
+```
+
+### Using npm packages
+
+Import maps also simplify npm package usage. Instead of:
+
+```typescript
+import { Maze } from "npm:@thewizardbear/maze_generator@^0.4.0";
+```
+
+Add it to your import map:
+
+```json
+{
+  "imports": {
+    "@denops/std": "jsr:@denops/std@^7.0.0",
+    "maze_generator": "npm:@thewizardbear/maze_generator@^0.4.0"
+  }
+}
+```
+
+Then import it as:
+
+```typescript
+import { Maze } from "maze_generator";
+```
+
+### Import Map Structure
+
+The `deno.json` file in your Denops plugin directory should contain all the dependencies your plugin needs. This keeps dependency management isolated to each plugin while avoiding conflicts in the merged runtime directory.
+
+For example, if your plugin uses additional npm packages:
+
+```json
+{
+  "imports": {
+    "@denops/std": "jsr:@denops/std@^7.0.0",
+    "@denops/std/": "jsr:@denops/std@^7.0.0/",
+    "@core/unknownutil": "jsr:@core/unknownutil@^4.3.0",
+    "your-npm-lib": "npm:some-package@^1.0.0"
+  }
+}
+```
+
+> [!NOTE]
+>
+> Including both `@denops/std` and `@denops/std/` allows you to import both the
+> main module and submodules (e.g., `@denops/std/buffer`).
+
 ## Next Steps
 
 In the next step, follow the tutorial to learn how to develop a minimum Denops

src/introduction.md

@@ -18,9 +18,10 @@ features:
 - **Unified codebase for Vim and Neovim**:<br>Denops provides a unified API for
   both Vim and Neovim. You can write a plugin that functions on both Vim and
   Neovim with a single codebase.
-- **No worries about dependency management**:<br>Deno includes a built-in
-  dependency management system, allowing developers to write plugins with
-  third-party libraries without concerns about dependency management.
+- **Modern dependency management**:<br>Deno's built-in dependency system with
+  import maps provides clean, maintainable dependency management. The workspace
+  configuration ensures each plugin's dependencies are isolated, preventing
+  conflicts when multiple Denops plugins are installed together.
 - **Simple and efficient code**:<br>Deno utilizes the V8 engine, significantly
   faster than Vim script. You can write a plugin with straightforward code,
   without the need for complex optimizations solely for performance.

src/tutorial/helloworld/adding-an-api.md

@@ -3,12 +3,23 @@
 In the previous section, we created a minimal Denops plugin. In this section, we
 will enhance the plugin by adding an API.
 
-Open `denops/denops-helloworld/main.ts` and rewrite the content with the
+First, update your `denops/denops-helloworld/deno.jsonc` to include the unknownutil dependency:
+
+```json,title=denops/denops-helloworld/deno.jsonc
+{
+  "imports": {
+    "@denops/std": "jsr:@denops/std@^7.0.0",
+    "@core/unknownutil": "jsr:@core/unknownutil@^4.3.0"
+  }
+}
+```
+
+Then open `denops/denops-helloworld/main.ts` and rewrite the content with the
 following code:
 
 ```typescript,title=denops/denops-helloworld/main.ts
-import type { Entrypoint } from "jsr:@denops/std@^7.0.0";
-import { assert, is } from "jsr:@core/unknownutil@^4.3.0";
+import type { Entrypoint } from "@denops/std";
+import { assert, is } from "@core/unknownutil";
 
 export const main: Entrypoint = (denops) => {
   denops.dispatcher = {

src/tutorial/helloworld/calling-vim-features.md

@@ -5,8 +5,8 @@ the `denops` instance passed to the plugin's `main` function. You can rewrite
 `main.ts` as follows to register the `DenopsHello` as a Vim command:
 
 ```typescript,title=denops/denops-helloworld/main.ts
-import type { Entrypoint } from "jsr:@denops/std@^7.0.0";
-import { assert, is } from "jsr:@core/unknownutil@^4.3.0";
+import type { Entrypoint } from "@denops/std";
+import { assert, is } from "@core/unknownutil";
 
 export const main: Entrypoint = (denops) => {
   denops.dispatcher = {