do11y 0.2.11 → 0.2.13

package/README.md

@@ -84,16 +84,49 @@ interface Options {
   /**
    * The code highlighter.
    *   - Markdown code blocks
-   *   - `.vue?highlight` & `.vue?highlight&lang=css` imports
+   *   - `.vue?highlight`, `.vue?highlight&lang=css` & `.vue?highlight&styleless` imports
    *   - `highlightedSource` and `highlightedCssSource` props in SandboxIframe
    *
    * If using multiple themes - you can set the `data-theme` attribute
    * to switch between them, e.g. `data-theme="vitesse-light"`.
    */
   highlighter?: {
+    /**
+     * The available themes.
+     * The default shiki themes are always included.
+     */
     themes: (ThemeInput | StringLiteralUnion<BundledTheme, string>)[];
+
+    /**
+     * What the default theme should be.
+     * @default "The first theme in the array"
+     */
     defaultTheme?: string | StringLiteralUnion<BundledTheme, string>;
+
+    /**
+     * Custom transformers.
+     *
+     * These Shiki's default transformers are always included:
+     *   - transformerNotationHighlight
+     *   - transformerNotationDiff
+     *   - transformerNotationErrorLevel
+     */
     transformers?: ShikiTransformer[];
+
+    /**
+     * If comments should be filtered.
+     *   - Passing `true` removes all comments
+     *   - While `string[]` acts as a filter - removing comments that `include` any of these strings in them
+     *   - `false` keeps all comments
+     *
+     * @default ["prettier-ignore"]
+     */
+    removeComments?: boolean | string[];
+
+    /**
+     * If any postprocessing should be done.
+     * The element is a JSDOM HTMLPreElement.
+     */
     postprocess?: (pre: HTMLPreElement) => void;
   };
 

package/dist/docs/options.js

@@ -25,6 +25,7 @@ const resolveOptions = async () => {
             themesInput,
             transformers: options.highlighter?.transformers || [],
             postprocess: options.highlighter?.postprocess,
+            removeComments: options.highlighter?.removeComments ?? ["prettier-ignore"],
         },
     };
 };

package/dist/docs/plugins/highlight/highlight.js

@@ -14,6 +14,7 @@ export const highlightCode = (code, lang) => {
         lang,
         themes: do11yOptions.highlighter.themesInput,
         defaultColor: do11yOptions.highlighter.defaultTheme,
+        includeExplanation: true,
         transformers: [
             transformerNotationHighlight(),
             transformerNotationDiff(),
@@ -30,6 +31,52 @@ export const highlightCode = (code, lang) => {
                     }
                 },
             },
+            {
+                name: "remove-unwanted-comments",
+                tokens(tokens) {
+                    const filter = do11yOptions.highlighter.removeComments;
+                    if (filter === false) {
+                        return tokens;
+                    }
+                    const result = [];
+                    let previousLineWasRemoved = false;
+                    for (const line of tokens) {
+                        previousLineWasRemoved = false;
+                        const filteredLine = [];
+                        let hasComment = false;
+                        for (const token of line) {
+                            const isUnwantedComment = token.explanation?.some((exp) => {
+                                const isComment = exp.scopes.some((s) => s.scopeName.startsWith("comment"));
+                                if (!isComment) {
+                                    return false;
+                                }
+                                return typeof filter === "boolean"
+                                    ? true
+                                    : filter.some((query) => exp.content.includes(query));
+                            });
+                            if (isUnwantedComment) {
+                                hasComment = true;
+                            }
+                            else {
+                                filteredLine.push(token);
+                            }
+                        }
+                        /**
+                         * Remove lines that become empty after removing comments.
+                         * Additionally, if the next line after a removed comment line is empty too - remove it.
+                         */
+                        if (hasComment || previousLineWasRemoved) {
+                            const isAllWhitespace = filteredLine.every((token) => !token.content.trim());
+                            previousLineWasRemoved = isAllWhitespace;
+                            if (isAllWhitespace) {
+                                continue;
+                            }
+                        }
+                        result.push(filteredLine);
+                    }
+                    return result;
+                },
+            },
         ],
     });
 };

package/dist/docs/plugins/options.d.ts

@@ -38,9 +38,38 @@ export interface Options extends MarkdownPluginOptions {
      * to switch between them, e.g. `data-theme="vitesse-light"`.
      */
     highlighter?: {
+        /**
+         * The available themes.
+         * The default shiki themes are always included.
+         */
         themes: (ThemeInput | StringLiteralUnion<BundledTheme, string>)[];
+        /**
+         * What the default theme should be.
+         * @default "The first theme in the array"
+         */
         defaultTheme?: string | StringLiteralUnion<BundledTheme, string>;
+        /**
+         * Custom transformers.
+         *
+         * These Shiki's default transformers are always included:
+         *   - transformerNotationHighlight
+         *   - transformerNotationDiff
+         *   - transformerNotationErrorLevel
+         */
         transformers?: ShikiTransformer[];
+        /**
+         * If comments should be filtered.
+         *   - Passing `true` removes all comments
+         *   - While `string[]` acts as a filter - removing comments that `include` any of these strings in them
+         *   - `false` keeps all comments
+         *
+         * @default ["prettier-ignore"]
+         */
+        removeComments?: boolean | string[];
+        /**
+         * If any postprocessing should be done.
+         * The element is a JSDOM HTMLPreElement.
+         */
         postprocess?: (pre: HTMLPreElement) => void;
     };
 }
@@ -50,6 +79,7 @@ export interface ResolvedOptions extends Omit<Options, "highlighter"> {
         themesInput: Record<string, string>;
         defaultTheme: string;
         transformers: ShikiTransformer[];
+        removeComments: boolean | string[];
         postprocess?: (pre: HTMLPreElement) => void;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "do11y",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "A bare-bones tool to document Vue components.",
   "keywords": [
     "docs-generator",