doc: improve doc style

website/catalog/Catalog.vue

@@ -0,0 +1,27 @@
+<script setup>
+import RuleItem from './RuleItem.vue'
+const rules = [
+  'rule1'
+]
+</script>
+<template>
+  <div class="rule-filter">
+    <label>
+      <input type="checkbox"/>
+      Single Pattern
+    </label>
+    <label>
+      <input type="checkbox"/>
+      YAML Rule
+    </label>
+    <label>
+      <input type="checkbox"/>
+      Has Fix
+    </label>
+  </div>
+  <ul>
+    <li v-for="rule in rules">
+      <RuleItem :title="rule"/>
+    </li>
+  </ul>
+</template>

website/catalog/RuleItem.vue

@@ -0,0 +1,9 @@
+<script setup>
+import { defineProps } from 'vue'
+defineProps({
+  title: String,
+})
+</script>
+<template>
+  <h1>{{ title }}</h1>
+</template>

website/catalog/index.md

@@ -0,0 +1,12 @@
+# Rule Catalog
+
+Get confused what ast-grep is? This is a list of rewriting rule to inspire you!
+
+Explore the power of ast-grep with these rewriting rules that can transform your code in seconds!
+
+----
+<script setup>
+import Catalog from './Catalog.vue'
+</script>
+
+<Catalog/>

website/guide/api-usage.md

@@ -13,7 +13,7 @@ Then, import the language object from the napi package. Every language object ha
 
 `parse` transforms string to a `SgRoot`. Example:
 
-```js
+```js{4}
 import { js } from '@ast-grep/napi';
 
 const source = `console.log("hello world")`
@@ -113,22 +113,24 @@ The return value of `findInFiles` is a `Promise` object. The promise resolves to
 See https://github.com/ast-grep/ast-grep/issues/206.
 :::
 
-If you have a lot of files and `findInFiles` prematurely returns, you can use the total files returned by `findInFiles` as a check point. Maintain a counter outside of `findInFiles` and increment it in callback. If the counter equals the total number, we can conclude all files are processed. The following code is an example.
+If you have a lot of files and `findInFiles` prematurely returns, you can use the total files returned by `findInFiles` as a check point. Maintain a counter outside of `findInFiles` and increment it in callback. If the counter equals the total number, we can conclude all files are processed. The following code is an example, with core logic highlighted.
 
-```ts
-function countedPromise<F extends (t: any, cb: any) => Promise<number>>(func: F) {
+```ts:line-numbers {11,16-18}
+type Callback = (t: any, cb: any) => Promise<number>
+function countedPromise<F extends Callback>(func: F) {
   type P = Parameters<F>
   return async (t: P[0], cb: P[1]) => {
     let i = 0
     let fileCount: number | undefined = undefined
-    let resolve = () => {} // will be called after all files are processed
+    // resolve will be called after all files are processed
+    let resolve = () => {}
     function wrapped(...args: any[]) {
       let ret = cb(...args)
       if (++i === fileCount) resolve()
       return ret
     }
     fileCount = await func(t, wrapped as P[1])
-    // all files are not processed, wait the resolve function to be called
+    // not all files are processed, await `resolve` to be called
     if (fileCount > i) {
       await new Promise<void>(r => resolve = r)
     }

website/guide/editor-integration.md

@@ -29,6 +29,6 @@ Please see [coc-ast-grep](https://github.com/yaegassy/coc-ast-grep)
 
 You need to have coc.nvim installed for this extension to work. e.g. vim-plug:
 
-```
+```vim
 Plug 'yaegassy/coc-ast-grep', {'do': 'yarn install --frozen-lockfile'}
 ```

website/guide/pattern-syntax.md

@@ -77,15 +77,15 @@ We can use `$$$` to match zero or more AST nodes, including function arguments,
 For example, `console.log($$$)` can match
 
 ```javascript
-console.log()
-console.log('hello world')
-console.log('debug: ', key, value)
-console.log(...args) // it also matches spread
+console.log()                       // matches zero AST node
+console.log('hello world')          // matches one node
+console.log('debug: ', key, value)  // matches multiple nodes
+console.log(...args)                // it also matches spread
 ```
 
 ### Function parameters
 
-`function $FUNC($$$) { $$$ }` will match
+`function $FUNC($$$ARGS) { $$$ }` will match
 
 ```javascript
 function foo(bar) {
@@ -99,6 +99,14 @@ function add(a, b, c) {
 }
 ```
 
+:::details `ARGS` will be populated with a list of AST nodes. Click to see details.
+|Code|Match|
+|---|----|
+|`function foo(bar) { ... }` | [`bar`] |
+|`function noop() {}` | [] |
+|`function add(a, b, c) { ... }` | [`a`, `b`, `c`] |
+:::
+
 ## Meta Variable Capturing
 
 Meta variable is also similar to [capture group](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Backreferences) in regular expression.

website/guide/quick-start.md

@@ -12,10 +12,10 @@ First, install `ast-grep`. It is distributed by [npm](https://www.npmjs.com/pack
 ```shell
 # install via npm
 npm i @ast-grep/cli -g
-
 # install via cargo
 cargo install ast-grep
-
+# install via pip
+pip install ast-grep-cli
 # install via homebrew
 brew install ast-grep
 ```
@@ -77,7 +77,7 @@ It is a valid `ast-grep` pattern! We can use it in command line! Use `pattern` a
 and also `lang` is needed to tell ast-grep our target code language.
 
 ```shell
-sg --pattern '$PROP && $PROP()' --lang ts TypeScript/src # path to TypeScript source
+sg --pattern '$PROP && $PROP()' --lang ts TypeScript/src # path to TS source
 ```
 
 ## Rewrite

website/guide/scan-project.md

@@ -66,11 +66,13 @@ Let's change the `pattern` inside `rule` and change the rule's message.
 
 ```yml
 id: no-eval
-message: Do not use eval! Dangerous! Hazardous! Perilous!
+message: Add your rule message here.... // [!code --]
+message: Do not use eval! Dangerous! Hazardous! Perilous! // [!code ++]
 severity: error
 language: JavaScript
 rule:
-  pattern: eval($CODE)
+  pattern: Your Rule Pattern here... // [!code --]
+  pattern: eval($CODE) // [!code ++]
 ```
 
 Okay! The pattern syntax works just like what we have learnt before.

website/guide/tooling-overview.md

@@ -94,7 +94,7 @@ Let's see an example in action. Combining with `curl`, `ast-grep` and `jq`, we c
 
 ```bash
 curl -s https://schedule2021.scipy.org/2022/conference/  |
-  sg --pattern '<div $$$> $$$ <i>$AUTHORS</i> </div>' --lang html --json |
+  sg -p '<div $$$> $$$ <i>$AUTHORS</i> </div>' --lang html --json |
   jq '
     .[]
     | .metaVariables
@@ -103,6 +103,7 @@ curl -s https://schedule2021.scipy.org/2022/conference/  |
 
 The command above will produce a list of authors from the SciPy 2022 conference website.
 
+:::details JSON output of the author list
 ```json
 "Ben Blaiszik"
 "Qiming Sun"
@@ -112,6 +113,7 @@ The command above will produce a list of authors from the SciPy 2022 conference
 "Cliff Kerr"
 ...
 ```
+:::
 
 With this feature, even if your preferred language does not have native bindings for ast-grep, you can still parse code from standard input (StdIn) to use ast-grep programmatically from the command line.