docs: add highlight plugin for prism in docsify and use it where lines have to be added

- enhance documentation

Author: Mairu

.github_changelog_generator

@@ -5,3 +5,4 @@ release-branch=master
 issues-of-open-milestones=false
 unreleased=false
 output=docs/CHANGELOG.md
+exclude-tags-regex=.*-pre.*

docs/api.md

@@ -39,10 +39,12 @@ __Options:__
 - `versionPrefix` (*optional*) - Used for automatic tag and name generation for services
 - `include` (*optional*) - Object to configure for which services documentation will be generated, empty means all will be included:
   - `tags` - Array of tags for that service documentation will be generated
-  - `paths` - Array of paths (string or regex) for that service documentation will be generated, Notice: paths don't start with /
+  - `paths` - Array of paths (string or regex) for that service documentation will be generated, __Notice:__ paths don't start with /
+  - `filter(service, path)` - Function to filter services for that documentation will be generated, __Notice:__ paths don't start with /
 - `ignore` (*optional*) - Object to configure  to ignore with the following keys:
   - `tags` - Array of tags for that no service documentation will be generated
   - `paths` - Array of paths (string or regex) for that no service documentation will be generated, Notice: paths don't start with /
+  - `filter(service, path)` - Function to filter services for that documentation won't be generated, __Notice:__ paths don't start with /
 - `appProperty` (*optional*, default: `docs`) - Property of the feathers app object that the generated specification will be saved to, allows custom post-processing; set empty to disable
 - `defaults` (*optional*) - Object to customize the defaults for generation of the specification
   - `getOperationArgs({ service, path, config, apiPath, version })` - Function to generate args that the methods for operations will consume, can also customize default tag and model generation

docs/custom-methods.md

@@ -109,6 +109,6 @@ Check out the [example](/examples/custom_methods.md) to see it in action.
 
 ## Limitations
 
-- In Feathers 4 the custom methods are registered after the default methods of a service and therefor
-  the /service/:id route will "win" over a /server/custom route for all methods but POST.
+- In Feathers 4 the custom methods are registered after the default methods of a service and therefore
+  the /service/:id route will "win" over a /service/custom route for all methods but POST.
 - At least one default method has to be existent in a service to be registered

docs/docsify/prism-lines.js

@@ -0,0 +1,93 @@
+function install (hook, vm) {
+  const codeContainer = {
+    counter: 0,
+    codes: {}
+  };
+
+  hook.beforeEach(function (content) {
+    codeContainer.counter = 0;
+    codeContainer.codes = {};
+    return content;
+  });
+
+  hook.mounted(function () {
+    if (vm.compiler._marked.Renderer.prototype.code) {
+      const original = vm.compiler._marked.defaults.renderer.code;
+
+      const code = (code, infostring, escaped) => {
+        const infostringParts = infostring.split(' ');
+        let options;
+
+        if (infostringParts.length > 1) {
+          const [lang, ...rest] = infostringParts;
+          infostring = lang;
+          try {
+            options = JSON.parse(rest.join(' '));
+          } catch (e) {
+            console.error('invalid code options');
+          }
+        }
+
+        const originalResult = original(code, infostring, escaped);
+
+        if (typeof options === 'object') {
+          let { lineNumbers, highlight } = options;
+
+          if (typeof lineNumbers === 'boolean') {
+            lineNumbers = { enabled: lineNumbers };
+          } else if (typeof lineNumbers === 'number') {
+            lineNumbers = { enabled: true, start: lineNumbers };
+          }
+
+          const additionalAttributes = [];
+          if (typeof lineNumbers === 'object') {
+            if (lineNumbers.enabled) {
+              additionalAttributes.push(`class="language-${infostring} line-numbers"`);
+            }
+            if (lineNumbers.start) {
+              additionalAttributes.push(`data-start="${lineNumbers.start}"`);
+            }
+          }
+
+          if (typeof highlight === 'string') {
+            highlight = { line: highlight };
+          }
+
+          if (typeof highlight === 'object') {
+            if (highlight.line) {
+              additionalAttributes.push(`data-line="${highlight.line}"`);
+            }
+            if (highlight.lineOffset) {
+              additionalAttributes.push(`data-line-offset="${highlight.lineOffset}"`);
+            }
+          }
+
+          if (additionalAttributes.length) {
+            codeContainer.codes[codeContainer.counter] = code;
+            additionalAttributes.push(`data-code-counter="${codeContainer.counter}"`);
+            codeContainer.counter += 1;
+
+            return originalResult.replace(/^<pre /, `<pre ${additionalAttributes.join(' ')} `);
+          }
+        }
+
+        return originalResult;
+      };
+
+      vm.compiler._marked.use({ renderer: { code } });
+    }
+  });
+
+  hook.doneEach(function () {
+    document.querySelector('#main').querySelectorAll('pre[data-code-counter]').forEach(pre => {
+      const env = {
+        code: codeContainer.codes[pre.dataset.codeCounter],
+        element: pre.querySelector(':scope > code')
+      };
+
+      window.Prism.hooks.run('complete', env);
+    });
+  });
+}
+
+window.$docsify.plugins = [].concat(install, window.$docsify.plugins);

docs/docsify/replace.js

@@ -0,0 +1,17 @@
+function install (hook) {
+  let replacements;
+
+  hook.mounted(function () {
+    replacements = window.$docsify.replacements || [];
+  });
+
+  hook.beforeEach(function (content) {
+    let modifiedContent = content;
+    replacements.forEach(({ search, replace }) => {
+      modifiedContent = modifiedContent.replace(search, replace);
+    });
+    return modifiedContent;
+  });
+}
+
+window.$docsify.plugins = [].concat(install, window.$docsify.plugins);

docs/examples/authentication_v5.md

@@ -30,7 +30,7 @@
 2. Add documentation to the authentication service (`src/authentication.ts`).
    This example shows local authentication.
 
-   ```typescript
+   ```typescript {"highlight": "12-16, 21-71", "lineNumbers": true}
    import { AuthenticationService, JWTStrategy } from '@feathersjs/authentication';
    import { LocalStrategy } from '@feathersjs/authentication-local';
    import type { Application } from './declarations';
@@ -117,10 +117,11 @@
 4. If you want to provide simple authentication usage on the SwaggerUI using Email/Username and Password,
    you can use the [Swagger UI Plugin ApiKeyAuthForm](https://github.com/Mairu/swagger-ui-apikey-auth-form).
 
-   Here is an example of an `openapi.ts` swagger configuration file, that can used with `api.configure()`;
+   Here is an example of an `openapi.ts` swagger configuration file, that can used with `api.configure();`
 
    ```typescript
-   import swagger, { FnSwaggerUiGetInitializerScript } from 'feathers-swagger';
+   import swagger from 'feathers-swagger';
+   import type { FnSwaggerUiGetInitializerScript } from 'feathers-swagger';
    import type { Application } from './declarations';
 
    const getSwaggerInitializerScript: FnSwaggerUiGetInitializerScript = ({ docsJsonPath, ctx }) => {

docs/examples/custom_methods.md

@@ -1,7 +1,7 @@
 ## Custom Methods <!-- {docsify-ignore} -->
 
 ### Code (from example app) <!-- {docsify-ignore} -->
-[filename](https://raw.githubusercontent.com/feathersjs-ecosystem/feathers-swagger/master/example/openapi-v3/customMethods.js ':include')
+[filename](https://raw.githubusercontent.com/feathersjs-ecosystem/feathers-swagger/{GITHUB_BRANCH}/example/openapi-v3/customMethods.js ':include')
 
 ### Preview in SwaggerUI <!-- {docsify-ignore} -->
 

docs/examples/generated_service_v5.md

@@ -2,7 +2,7 @@
 
 1. Go into your `src/services/{$name}` folder, and open the service you want to edit `${name}.[tj]s`
 2. Import the helper function and import the schemas (example for user service):
-```js
+```js  {"highlight": "9-11", "lineNumbers": true}
   import { createSwaggerServiceOptions } from 'feathers-swagger';
   import {
       userDataValidator,
@@ -11,14 +11,13 @@
       userDataResolver,
       userQueryResolver,
       userExternalResolver,
-      // the lines below are added
       userDataSchema,
       userQuerySchema,
       userSchema,
   } from './users.schema';
 ```
 adjust the options when the service is generated
-```js
+```js {"highlight": "6-12", "lineNumbers": true}
   app.use('users', new UserService(getOptions(app)), {
       // A list of all methods this service exposes externally
       methods: ['find', 'get', 'create', 'update', 'patch', 'remove'],

docs/examples/index.md

@@ -1,6 +1,6 @@
 ## Examples <!-- {docsify-ignore} -->
 
-In addition to the examples you can access from the navigation, you can check out the [example application](https://github.com/feathersjs-ecosystem/feathers-swagger/tree/master/example) of the git repository.
+In addition to the examples you can access from the navigation, you can check out the [example application](https://github.com/feathersjs-ecosystem/feathers-swagger/tree/{GITHUB_BRANCH}/example) of the git repository.
 
 It contains many configurations and can be start with `npm start` when feathers-swagger have been checked out.
 

docs/getting-started.md

@@ -5,7 +5,7 @@
 
 Add [OpenAPI](https://swagger.io/resources/open-api/) documentation to your Feathers services and optionally show them in the [Swagger UI](https://swagger.io/tools/swagger-ui/).
 
-You can also add custom methods to feathers services that will be available as rest routes but not via the feathers client. 
+You can also add custom methods to feathers services that will be available as rest routes but not via feathers client. 
 
 This version is prepared to work with Swagger UI >= 4.9