use markdown-it-include pkg for re-usable content

Author: f-w

docs/.vuepress/config.js

@@ -1,8 +1,9 @@
-import packageJson, {description} from '../../package';
-import {defineUserConfig, defaultTheme} from 'vuepress';
-import {getDirname, path} from '@vuepress/utils';
-import {docsearchPlugin} from '@vuepress/plugin-docsearch';
 import codeCopyPlugin from '@snippetors/vuepress-plugin-code-copy';
+import { docsearchPlugin } from '@vuepress/plugin-docsearch';
+import { getDirname, path } from '@vuepress/utils';
+import markdownItInclude from 'markdown-it-include';
+import { defaultTheme, defineUserConfig } from 'vuepress';
+import packageJson, { description } from '../../package';
 
 const __dirname = getDirname(import.meta.url);
 
@@ -24,10 +25,13 @@ export default defineUserConfig({
    * ref：https://v1.vuepress.vuejs.org/config/#head
    */
   head: [
-    ['meta', {name: 'theme-color', content: '#3eaf7c'}],
-    ['meta', {name: 'apple-mobile-web-app-capable', content: 'yes'}],
-    ['meta', {name: 'apple-mobile-web-app-status-bar-style', content: 'black'}],
-    ['link', {rel: 'icon', type: 'image/x-icon', href: `${base}favicon.ico`}],
+    ['meta', { name: 'theme-color', content: '#3eaf7c' }],
+    ['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
+    [
+      'meta',
+      { name: 'apple-mobile-web-app-status-bar-style', content: 'black' },
+    ],
+    ['link', { rel: 'icon', type: 'image/x-icon', href: `${base}favicon.ico` }],
     [
       'link',
       {
@@ -60,6 +64,11 @@ export default defineUserConfig({
     codeCopyPlugin(),
   ],
 
+  extendsMarkdown: (md) => {
+    // use more markdown-it plugins!
+    md.use(markdownItInclude);
+  },
+
   /**
    * Theme configuration, here is the default theme configuration for VuePress.
    *

docs/docs/api/administrator.md

@@ -331,16 +331,25 @@ This API allows a super-admin or admin to search for administrators. An admin ca
   - super admin
   - admin
 - inputs
-  - a filter defining fields, where, include, order, offset, and limit. See [Loopback Querying Data](https://loopback.io/doc/en/lb4/Querying-data.html) for valid syntax and examples
-    - parameter name: filter
-    - required: false
-    - parameter type: query
-    - data type: object
+
+  - !!!include(./docs/shared/filterQueryParam.md)!!!
+
 - outcome
+
   - for super-admins, returns an array of _Administrators_ matching the filter
   - for admins, returns an array of one element - own record if the record matches the filter; empty array otherwise
   - forbidden otherwise
 
+- example
+
+  to retrieve administrators created in year 2023, run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/administrators!!!include(./docs/shared/filterQueryParamCode.md)!!!'
+  ```
+
+  !!!include(./docs/shared/filterQueryParamExample.md)!!!
+
 ## Update Administrators
 
 ```
@@ -388,16 +397,19 @@ This API allows a super-admin or admin to count administrators by filter. An adm
   - super admin
   - admin
 - inputs
-
-  - a [where filter](https://loopback.io/doc/en/lb4/Where-filter.html)
-    - parameter name: where
-    - required: false
-    - parameter type: query
-    - data type: object
-
+  - !!!include(./docs/shared/whereQueryParam.md)!!!
 - outcome
   - for super-admins or admin, a count matching the filter
   - forbidden otherwise
+- example
+
+  to retrieve the count of administrators created in year 2023 , run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/administrators/count!!!include(./docs/shared/whereQueryParamCode.md)!!!'
+  ```
+
+  !!!include(./docs/shared/whereQueryParamExample.md)!!!
 
 ## Delete an Administrator
 

docs/docs/api/config.md

@@ -79,28 +79,22 @@ GET /configurations
   - super admin
   - admin
 - inputs
-  - a [filter](https://loopback.io/doc/en/lb4/Querying-data.html#filters) defining fields, where, include, order, offset, and limit
-    - parameter name: filter
-    - required: false
-    - parameter type: query
-    - data type: object
+
+  - !!!include(./docs/shared/filterQueryParam.md)!!!
+
 - outcome
 
   For admin request, a list of config items matching the filter; forbidden for user request
 
 - example
 
-  to retrieve config items with name _rsa_, run
+  to retrieve configs created in year 2023, run
 
   ```sh
-  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/configurations?filter=%7B%22where%22%3A%20%7B%22name%22%3A%22rsa%22%7D%7D'
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/configurations!!!include(./docs/shared/filterQueryParamCode.md)!!!'
   ```
 
-  the value of filter query parameter is the [stringified JSON](https://loopback.io/doc/en/lb4/Querying-data.html#using-stringified-json-in-rest-queries)
-
-  ```json
-  {"where": {"name": "rsa"}}
-  ```
+  !!!include(./docs/shared/filterQueryParamExample.md)!!!
 
 ## Create a Configuration
 

docs/docs/api/notification.md

@@ -359,12 +359,11 @@ GET /notifications
   - admin
   - authenticated user
 - inputs
-  - a filter defining fields, where, include, order, offset, and limit. See [Loopback Querying Data](https://loopback.io/doc/en/lb4/Querying-data.html#filters) for valid syntax and examples
-    - parameter name: filter
-    - required: false
-    - parameter type: query
-    - data type: object
+
+  - !!!include(./docs/shared/filterQueryParam.md)!!!
+
 - outcome
+
   - for admin requests, returns unabridged array of notification data matching the filter
   - for authenticated user requests, in addition to filter, following constraints are imposed on the returned array
     - only inApp notifications
@@ -375,6 +374,16 @@ GET /notifications
     - the internal field _readBy_ and _deletedBy_ are removed
   - forbidden to anonymous user requests
 
+- example
+
+  to retrieve notifications created in year 2023, run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/notifications!!!include(./docs/shared/filterQueryParamCode.md)!!!'
+  ```
+
+  !!!include(./docs/shared/filterQueryParamExample.md)!!!
+
 ## Get Notification Count
 
 ```
@@ -386,11 +395,7 @@ GET /notifications/count
   - admin
   - authenticated user
 - inputs
-  - a [where filter](https://loopback.io/doc/en/lb4/Where-filter.html)
-    - parameter name: filter
-    - required: false
-    - parameter type: query
-    - data type: object
+  - !!!include(./docs/shared/whereQueryParam.md)!!!
 - outcome
 
   Validations rules are the same as _GET /notifications_. If passed, the output is a count of notifications matching the query
@@ -401,6 +406,16 @@ GET /notifications/count
   }
   ```
 
+- example
+
+  to retrieve the count of notifications created in year 2023, run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/notifications/count!!!include(./docs/shared/whereQueryParamCode.md)!!!'
+  ```
+
+  !!!include(./docs/shared/whereQueryParamExample.md)!!!
+
 ## Create/Send Notifications
 
 ```

docs/docs/api/subscription.md

@@ -266,19 +266,28 @@ GET /subscriptions
   - admin
   - authenticated user
 - inputs
-  - a filter defining fields, where, include, order, offset, and limit. See [Loopback Querying Data](https://loopback.io/doc/en/lb4/Querying-data.html) for valid syntax and examples
-    - parameter name: filter
-    - required: false
-    - parameter type: query
-    - data type: object
+
+  - !!!include(./docs/shared/filterQueryParam.md)!!!
+
 - outcome
+
   - for admin requests, returns unabridged array of subscription data matching the filter
   - for authenticated user requests, in addition to filter, following constraints are imposed on the returned array
     - only non-deleted subscriptions
     - only subscriptions created by the user
     - the _confirmationRequest_ field is removed.
   - forbidden for anonymous user requests
 
+- example
+
+  to retrieve subscriptions created in year 2023, run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/subscriptions!!!include(./docs/shared/filterQueryParamCode.md)!!!'
+  ```
+
+  !!!include(./docs/shared/filterQueryParamExample.md)!!!
+
 ## Get Subscription Count
 
 ```
@@ -290,11 +299,7 @@ GET /subscriptions/count?where[property]=value
   - admin
   - authenticated user
 - inputs
-  - a [where filter](https://loopback.io/doc/en/lb4/Where-filter.html)
-    - parameter name: where
-    - required: false
-    - parameter type: query
-    - data type: object
+  - !!!include(./docs/shared/whereQueryParam.md)!!!
 - outcome
 
   Validations rules are the same as _GET /subscriptions_. If passed, the output is a count of subscriptions matching the query
@@ -305,9 +310,15 @@ GET /subscriptions/count?where[property]=value
   }
   ```
 
-- examples
+- example
+
+  to retrieve the count of subscriptions created in year 2023, run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/subscriptions/count!!!include(./docs/shared/whereQueryParamCode.md)!!!'
+  ```
 
-  See LoopBack [Get instance count](http://loopback.io/doc/en/lb3/PersistedModel-REST-API.html#get-instance-count) for examples.
+  !!!include(./docs/shared/whereQueryParamExample.md)!!!
 
 ## Create a Subscription
 

docs/docs/shared/filterQueryParam.md

@@ -0,0 +1,30 @@
+a filter containing properties _where_, _fields_, _order_, _skip_, and _limit_
+
+    - parameter name: filter
+    - required: false
+    - parameter type: query
+    - data type: object
+
+    The filter can be expressed as either
+
+      1. URL-encoded stringified JSON object (see example below); or
+      2. in the format supported by [qs](https://github.com/ljharb/qs), for example `?filter[where][created][$gte]="2023-01-01"&filter[where][created][$lt]="2024-01-01"`
+
+    Regardless, the filter will have to be parsed into a JSON object conforming to
+
+    ```json
+    {
+        "where": {...},
+        "fields": ...,
+        "order": ...,
+        "skip": ...,
+        "limit": ...,
+    }
+    ```
+
+    All properties are optional. The syntax for each property is documented, respectively
+    - for *where* , see MongoDB [Query Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
+    - for *fields* , see Mongoose [select](https://mongoosejs.com/docs/api/query.html#Query.prototype.select())
+    - for *order*, see Mongoose [sort](https://mongoosejs.com/docs/api/query.html#Query.prototype.sort())
+    - for *skip*, see MongoDB [cursor.skip](https://www.mongodb.com/docs/manual/reference/method/cursor.skip/)
+    - for *limit*, see MongoDB [cursor.limit](https://www.mongodb.com/docs/manual/reference/method/cursor.limit/)

docs/docs/shared/filterQueryParamCode.md

@@ -0,0 +1 @@
+?filter=%7B%22where%22%3A%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D%7D

docs/docs/shared/filterQueryParamExample.md

@@ -0,0 +1,12 @@
+the value of the filter query parameter is URL-encoded stringified JSON object
+
+    ```json
+    {
+      "where": {
+        "created": {
+          "$gte": "2023-01-01",
+          "$lt": "2024-01-01"
+        }
+      }
+    }
+    ```

docs/docs/shared/whereQueryParam.md

@@ -0,0 +1,11 @@
+a _where_ query parameter with value conforming to MongoDB [Query Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
+
+    - parameter name: where
+    - required: false
+    - parameter type: query
+    - data type: object
+
+    The value can be expressed as either
+
+      1. URL-encoded stringified JSON object (see example below); or
+      2. in the format supported by [qs](https://github.com/ljharb/qs), for example `?where[created][$gte]="2023-01-01"&where[created][$lt]="2024-01-01"`

docs/docs/shared/whereQueryParamCode.md

@@ -0,0 +1 @@
+?where=%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D