Merge pull request #11 from vim-denops/v6-pre

📝 Rewrite documentation for denops v6

.github/workflows/mdbook.yml

@@ -2,7 +2,7 @@
 #
 # To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
 #
-name: Deploy mdBook site to Pages
+name: Deploy
 
 on:
   # Runs on pushes targeting the default branch
@@ -37,7 +37,7 @@ jobs:
           curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
           rustup update
           cargo install --version ${MDBOOK_VERSION} mdbook
-          cargo install mdbook-plantuml
+          cargo install mdbook-alerts
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v4

.github/workflows/test.yml

@@ -2,21 +2,18 @@ name: Test
 
 env:
   DENO_VERSION: 1.x
+  MDBOOK_VERSION: 0.4.36
 
 on:
   push:
-    branches:
-      - main
   pull_request:
-    branches:
-      - main
 
 jobs:
   test:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/cache@v2
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
         with:
           path: |
             ~/.cargo/bin/
@@ -26,17 +23,18 @@ jobs:
             target/
             .tools/
           key: ${{ runner.os }}-cargo
-      - uses: denoland/setup-deno@main
+      - uses: denoland/setup-deno@v1.1.4
         with:
           deno-version: ${{ env.DENO_VERSION }}
-      - uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-      - name: Format
-        run: make fmt-check
-      - name: Install tools
-        run: make tools
-      - name: Generate
+      - name: Install mdBook
         run: |
-          make gen
-          git diff --check
+          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
+          rustup update
+          cargo install --version ${MDBOOK_VERSION} mdbook
+          cargo install mdbook-alerts
+      - name: Build with mdBook
+        run: mdbook build
+      - name: Format
+        run: deno fmt --check
+      - name: Misspell
+        uses: reviewdog/[email protected]

.gitignore

@@ -1,2 +1 @@
-/.tools
 /book

README.md

@@ -1,10 +1,11 @@
-# Denops Documentation
+# denops-documentation
 
 [![Test](https://github.com/vim-denops/denops-documentation/actions/workflows/test.yml/badge.svg)](https://github.com/vim-denops/denops-documentation/actions/workflows/test.yml)
+[![Deploy](https://github.com/vim-denops/denops-documentation/actions/workflows/mdbook.yml/badge.svg)](https://github.com/vim-denops/denops-documentation/actions/workflows/mdbook.yml)
 [![Documentation](https://img.shields.io/badge/denops-Documentation-yellow.svg)](https://vim-denops.github.io/denops-documentation/)
 
-This is an official documentation of [denops.vim][denops.vim], an ecosystem of
-Vim/Neovim which allows developers to write plugins in [Deno][Deno].
+This is an official documentation of [denops.vim], an ecosystem of Vim/Neovim
+which allows developers to write plugins in [Deno].
 
 [denops.vim]: https://github.com/vim-denops/denops.vim
 [deno]: https://deno.land
@@ -20,26 +21,31 @@ To contribute, install the latest versions of the followings in your environment
 - [Rust](https://www.rust-lang.org/tools/install)
 - [Deno](https://deno.land/)
 
-Then, install [mdBook](https://github.com/rust-lang/mdBook) and its plugins in
-`.tools` directory by
+Then, install [mdBook](https://github.com/rust-lang/mdBook) and its plugins
 
 ```
-make tools
+cargo install mdbook
+cargo install mdbook-alerts
 ```
 
-Once required tools are installed, execute the following command to generate
-static files in [`./docs`](./docs) from markdown files in [`./src`](./src).
+Once required tools are installed, execute the following command to serve the
+book on http://localhost:3000
 
 ```
-make gen
+mdbook serve
 ```
 
-Note that all markdown files are formatted with
-[Deno's code formatter](https://deno.land/manual/tools/formatter) and checked by
-CI thus make sure to format codes by the following command
+Or build book into `book` directory
 
 ```
-make fmt
+mdbook build
+```
+
+Don't forget to format Markdown files with `deno fmt` before sending a pull
+request.
+
+```
+deno fmt
 ```
 
 ## See also

book.toml

@@ -5,5 +5,4 @@ multilingual = false
 src = "src"
 title = "Denops Documentation"
 
-[preprocessor.plantuml]
-plantuml-cmd="http://www.plantuml.com/plantuml"
+[preprocessor.alerts]

deno.jsonc

@@ -0,0 +1,3 @@
+{
+  "exclude": ["theme/**/*", "book/**/*"]
+}

src/SUMMARY.md

@@ -3,13 +3,18 @@
 [Introduction](./introduction.md)
 
 - [Install](./install.md)
-- [Tutorial](./tutorial.md)
-  - [Preparing Deno and Denops](./tutorial/preparing-deno-and-denops.md)
-  - [Developing Your First Plugin](./tutorial/developing-your-first-plugin.md)
-    - [Vim/Neovim Configuration](./tutorial/vimneovim-configuration.md)
-    - [Making a Plugin Directory Tree](./tutorial/making-a-directory-tree.md)
-    - [Adding a Skelton of Denops Plugin](./tutorial/adding-a-skelton-of-denops-plugin.md)
-    - [Adding an API](./tutorial/adding-an-api.md)
-    - [Calling Vim/Neovim Features](./tutorial/calling-vimneovim-features.md)
-    - [Developing More Applicative Plugin](./tutorial/developing-more-applicative-plugin.md)
-  - [Developing Your Next Plugins](./tutorial/developing-your-next-plugins.md)
+- [Getting Started](./getting-started/README.md)
+  - [Explanation of the Getting started](./getting-started/explanation.md)
+- [Tutorial (Hello world)](./tutorial/helloworld/README.md)
+  - [Creating a minimal Vim plugin](./tutorial/helloworld/creating-a-minimal-vim-plugin.md)
+  - [Creating a minimal Denops plugin](./tutorial/helloworld/creating-a-minimal-denops-plugin.md)
+  - [Adding Denops APIs](./tutorial/helloworld/adding-an-api.md)
+  - [Calling Vim features](./tutorial/helloworld/calling-vim-features.md)
+- [Tutorial (Maze)](./tutorial/maze/README.md)
+  - [Utilizing third-party library](./tutorial/maze/utilizing-third-party-library.md)
+  - [Outputting content to buffer](./tutorial/maze/outputting-content-to-buffer.md)
+  - [Adjusting maze size to fit the window](./tutorial/maze/adjusting-maze-size-to-fit-the-window.md)
+  - [Properly create a virtual buffer](./tutorial/maze/properly-create-a-virtual-buffer.md)
+  - [Properly configured the buffer](./tutorial/maze/properly-configured-the-buffer.md)
+  - [Reduce the number of RPC calls](./tutorial/maze/reduce-the-number-of-rpc-calls.md)
+- [FAQ](./faq.md)

src/faq.md

@@ -0,0 +1,24 @@
+# FAQ
+
+## How to Check Denops Startup Time
+
+To check the startup time of Denops or Denops plugins, utilize
+[denops-startup-recorder]. This plugin visualizes the timing of events related
+to Denops and Denops plugin startup.
+
+[denops-startup-recorder]: https://github.com/vim-denops/denops-startup-recorder.vim
+
+It shows the result in echo area like:
+
+![](./img/faq-1.png)
+
+## How to Check Denops Performance
+
+To assess Denops performance, employ [denops-benchmark]. This plugin measures
+the number of operations or characters that can be processed in milliseconds.
+
+[denops-benchmark]: https://github.com/vim-denops/denops-benchmark.vim
+
+It shows the result in a buffer like:
+
+![](./img/faq-2.png)

src/getting-started/README.md

@@ -0,0 +1,68 @@
+# Getting Started
+
+[Denops] ([/ˈdiːnoʊps/](http://ipa-reader.xyz/?text=%CB%88di%CB%90no%CA%8Aps),
+pronounced `dee-nops`) is an ecosystem for [Vim] / [Neovim] that empowers
+developers to write plugins in [TypeScript] / [JavaScript] powered by [Deno].
+
+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/`:
+
+```
+$HOME
+└── denops-getting-started
+    └── denops
+        └── denops-getting-started
+            └── main.ts
+```
+
+Next, write the following TypeScript code in `main.ts`:
+
+```typescript
+import type { Denops } from "https://deno.land/x/[email protected]/mod.ts";
+
+export function main(denops: Denops): void {
+  denops.dispatcher = {
+    async hello() {
+      await denops.cmd(`echo "Hello, Denops!"`);
+    },
+  };
+}
+```
+
+## Activate the Plugin
+
+Add the following line to your Vim or Neovim configuration file (e.g.,
+`~/.vimrc` or `~/.config/nvim/init.vim`):
+
+```vim
+set runtimepath+=~/denops-getting-started
+```
+
+Or Neovim Lua configuration file (e.g., `~/.config/nvim/init.lua`):
+
+```lua
+vim.opt.runtimepath:append("~/denops-getting-started")
+```
+
+## Try the Plugin
+
+Restart Vim/Neovim and execute the following command:
+
+```vim
+:call denops#request('denops-getting-started', 'hello', [])
+```
+
+You should see "Hello, Denops!" displayed on the screen like:
+
+![](./img/README-01.png)
+
+[Denops]: https://github.com/vim-denops/denops.vim
+[Vim]: https://www.vim.org/
+[Neovim]: https://neovim.io/
+[TypeScript]: https://www.typescriptlang.org/
+[JavaScript]: https://developer.mozilla.org/en-US/docs/Web/JavaScript
+[Deno]: https://deno.land/