@diplodoc/transform 4.31.3 → 4.32.1

package/src/scss/_term.scss

@@ -1,6 +1,6 @@
 .yfm-term {
     &_title {
-        color: #027bf3;
+        color: var(--yfm-color-term-title);
         cursor: pointer;
 
         border-bottom: 1px dotted;
@@ -10,7 +10,7 @@
         font-style: normal;
 
         &:hover {
-            color: #004080;
+            color: var(--yfm-color-term-title-hover);
         }
     }
 
@@ -32,7 +32,7 @@
 
         padding: 10px;
 
-        background-color: rgb(255, 255, 255);
+        background-color: var(--yfm-color-term-dfn-background);
 
         font-size: inherit;
         line-height: inherit;
@@ -40,20 +40,17 @@
 
         border-radius: 4px;
 
-        box-shadow: 0 8px 20px rgba(0, 0, 0, 0.15);
+        box-shadow: 0 8px 20px var(--yfm-color-term-dfn-shadow);
         outline: none;
 
         &::before {
             content: '';
             position: absolute;
             z-index: -1;
-            top: 0;
-            right: 0;
-            bottom: 0;
-            left: 0;
+            inset: 0;
 
             border-radius: inherit;
-            box-shadow: 0 0 0 1px rgb(229, 229, 229);
+            box-shadow: 0 0 0 1px var(--yfm-color-term-dfn-pseudo-shadow);
         }
 
         &.open {

package/src/scss/brand.scss

@@ -0,0 +1,48 @@
+@mixin brand {
+    --yfm-color-base: var(--yfm-color-base-private);
+
+    --yfm-color-text: var(--yfm-color-text-private);
+    --yfm-color-link: var(--yfm-color-link-private);
+    --yfm-color-link-hover: var(--yfm-color-link-hover-private);
+
+    --yfm-color-table: var(--yfm-color-table-private);
+    --yfm-color-table-row-background: var(--yfm-color-table-row-background-private);
+
+    --yfm-color-border: var(--yfm-color-border-private);
+
+    --yfm-color-accent: var(--yfm-color-accent-private);
+
+    --yfm-color-inline-code: var(--yfm-color-inline-code-private);
+    --yfm-color-inline-code-background: var(--yfm-color-inline-code-background-private);
+    --yfm-color-code-background: var(--yfm-color-code-background-private);
+
+    --yfm-color-hljs-background: var(--yfm-color-hljs-background-private);
+    --yfm-color-hljs-subst: var(--yfm-color-hljs-subst-private);
+    --yfm-color-hljs-comment: var(--yfm-color-hljs-comment-private);
+    --yfm-color-hljs-deletion: var(--yfm-color-hljs-deletion-private);
+    --yfm-color-hljs-section: var(--yfm-color-hljs-section-private);
+    --yfm-color-hljs-pseudo: var(--yfm-color-hljs-pseudo-private);
+    --yfm-color-hljs-literal: var(--yfm-color-hljs-literal-private);
+    --yfm-color-hljs-addition: var(--yfm-color-hljs-addition-private);
+    --yfm-color-hljs-meta: var(--yfm-color-hljs-meta-private);
+    --yfm-color-hljs-meta-string: var(--yfm-color-hljs-meta-string-private);
+
+    --yfm-color-note-tip: var(--yfm-color-note-tip-private);
+    --yfm-color-note-tip-background: var(--yfm-color-note-tip-background-private);
+    --yfm-color-note-warning: var(--yfm-color-note-warning-private);
+    --yfm-color-note-warning-background: var(--yfm-color-note-warning-background-private);
+    --yfm-color-note-important: var(--yfm-color-note-important-private);
+    --yfm-color-note-important-background: var(--yfm-color-note-important-background-private);
+    --yfm-color-note-info-background: var(--yfm-color-note-info-background-private);
+
+    --yfm-color-term-title: var(--yfm-color-term-title-private);
+    --yfm-color-term-title-hover: var(--yfm-color-term-title-hover-private);
+    --yfm-color-term-dfn-background: var(--yfm-color-term-dfn-background-private);
+    --yfm-color-term-dfn-shadow: var(--yfm-color-term-dfn-shadow-private);
+    --yfm-color-term-dfn-pseudo-shadow: var(--yfm-color-term-dfn-presudo-shadow-private);
+
+    --yfm-color-modal-content: var(--yfm-color-modal-content-private);
+    --yfm-color-modal-actions-hover: var(--yfm-color-modal-actions-hover-private);
+    --yfm-color-modal-wide-content: var(--yfm-color-modal-wide-content-private);
+    --yfm-color-modal-wide-content-overlay: var(--yfm-color-modal-wide-content-overlay-private);
+}

package/src/scss/private.scss

@@ -0,0 +1,44 @@
+@mixin private-brand {
+    --yfm-color-text-private: rgba(0, 0, 0, 0.7);
+    --yfm-color-link-private: #027bf3;
+    --yfm-color-link-hover-private: #004080;
+    --yfm-color-base-private: #ffffff;
+    --yfm-color-table-private: #333;
+    --yfm-color-border-private: rgba(0, 0, 0, 0.07);
+    --yfm-color-table-row-background-private: rgba(0, 0, 0, 0.02);
+    --yfm-color-accent-private: #027bf3;
+
+    --yfm-color-inline-code-private: rgba(59, 96, 128, 1);
+    --yfm-color-inline-code-background-private: rgba(107, 132, 153, 0.12);
+    --yfm-color-code-background-private: rgba(107, 132, 153, 0.12);
+
+    --yfm-color-hljs-background-private: rgba(107, 132, 153, 0.12);
+    --yfm-color-hljs-subst-private: #444;
+    --yfm-color-hljs-comment-private: #888888;
+    --yfm-color-hljs-deletion-private: #880000;
+    --yfm-color-hljs-section-private: #880000;
+    --yfm-color-hljs-pseudo-private: #bc6060;
+    --yfm-color-hljs-literal-private: #78a960;
+    --yfm-color-hljs-addition-private: #397300;
+    --yfm-color-hljs-meta-private: #1f7199;
+    --yfm-color-hljs-meta-string-private: #4d99bf;
+
+    --yfm-color-note-tip-private: #56bd67;
+    --yfm-color-note-tip-background-private: rgba(63, 201, 46, 0.1);
+    --yfm-color-note-warning-private: #f19518;
+    --yfm-color-note-warning-background-private: rgba(255, 136, 0, 0.15);
+    --yfm-color-note-important-private: #ff4645;
+    --yfm-color-note-important-background-private: rgba(235, 50, 38, 0.08);
+    --yfm-color-note-info-background-private: rgba(2, 123, 243, 0.08);
+
+    --yfm-color-term-title-private: #027bf3;
+    --yfm-color-term-title-hover-private: #004080;
+    --yfm-color-term-dfn-background-private: rgb(255, 255, 255);
+    --yfm-color-term-dfn-shadow-private: rgba(0, 0, 0, 0.15);
+    --yfm-color-term-dfn-presudo-shadow-private: rgb(229, 229, 229);
+
+    --yfm-color-modal-content-private: rgb(255, 255, 255);
+    --yfm-color-modal-actions-hover-private: rgba(0, 0, 0, 0.05);
+    --yfm-color-modal-wide-content-private: rgba(0, 0, 0, 0.85);
+    --yfm-color-modal-wide-content-overlay-private: rgb(0, 0, 0);
+}

package/src/transform/frontmatter/common.ts

@@ -0,0 +1,27 @@
+export type FrontMatter = {
+    [key: string]: unknown;
+    metadata?: Record<string, unknown>[];
+};
+
+export const frontMatterFence = '---';
+
+/**
+ * Temporary workaround to enable parsing YAML metadata from potentially
+ * Liquid-aware source files
+ * @param content Input string which could contain Liquid-style substitution syntax (which clashes with YAML
+ * object syntax)
+ * @returns String with `{}` escaped, ready to be parsed with `js-yaml`
+ */
+export const escapeLiquidSubstitutionSyntax = (content: string): string =>
+    content.replace(/{{/g, '(({{').replace(/}}/g, '}}))');
+
+/**
+ * Inverse of a workaround defined above.
+ * @see `escapeLiquidSubstitutionSyntax`
+ * @param escapedContent Input string with `{}` escaped with backslashes
+ * @returns Unescaped string
+ */
+export const unescapeLiquidSubstitutionSyntax = (escapedContent: string): string =>
+    escapedContent.replace(/\(\({{/g, '{{').replace(/}}\)\)/g, '}}');
+
+export const countLineAmount = (str: string) => str.split(/\r?\n/).length;

package/src/transform/frontmatter/emplace.ts

@@ -0,0 +1,24 @@
+import {dump} from 'js-yaml';
+
+import {FrontMatter, frontMatterFence} from './common';
+
+export const serializeFrontMatter = (frontMatter: FrontMatter) => {
+    const dumped = dump(frontMatter, {lineWidth: -1}).trim();
+
+    // This empty object check is a bit naive
+    // The other option would be to check if all own fields are `undefined`,
+    // since we exploit passing in `undefined` to remove a field quite a bit
+    if (dumped === '{}') {
+        return '';
+    }
+
+    return `${frontMatterFence}\n${dumped}\n${frontMatterFence}\n`;
+};
+
+export const emplaceSerializedFrontMatter = (
+    frontMatterStrippedContent: string,
+    frontMatter: string,
+) => `${frontMatter}${frontMatterStrippedContent}`;
+
+export const emplaceFrontMatter = (frontMatterStrippedContent: string, frontMatter: FrontMatter) =>
+    emplaceSerializedFrontMatter(frontMatterStrippedContent, serializeFrontMatter(frontMatter));

package/src/transform/frontmatter/extract.ts

@@ -0,0 +1,94 @@
+import {YAMLException, load} from 'js-yaml';
+
+import {log} from '../log';
+
+import {
+    FrontMatter,
+    countLineAmount,
+    escapeLiquidSubstitutionSyntax,
+    frontMatterFence,
+    unescapeLiquidSubstitutionSyntax,
+} from './common';
+import {transformFrontMatterValues} from './transformValues';
+
+type ParseExistingMetadataReturn = {
+    frontMatter: FrontMatter;
+    frontMatterStrippedContent: string;
+    frontMatterLineCount: number;
+};
+
+const matchMetadata = (fileContent: string) => {
+    if (!fileContent.startsWith(frontMatterFence)) {
+        return null;
+    }
+
+    // Search by format:
+    // ---
+    // metaName1: metaValue1
+    // metaName2: meta value2
+    // incorrectMetadata
+    // ---
+    const regexpMetadata = '(?<=-{3}\\r?\\n)((.*\\r?\\n)*?)(?=-{3}\\r?\\n)';
+    // Search by format:
+    // ---
+    // main content 123
+    const regexpFileContent = '-{3}\\r?\\n((.*[\r?\n]*)*)';
+
+    const regexpParseFileContent = new RegExp(`${regexpMetadata}${regexpFileContent}`, 'gm');
+
+    return regexpParseFileContent.exec(fileContent);
+};
+
+const duplicateKeysCompatibleLoad = (yaml: string, filePath: string | undefined) => {
+    try {
+        return load(yaml);
+    } catch (e) {
+        if (e instanceof YAMLException) {
+            const duplicateKeysDeprecationWarning = `
+                In ${filePath ?? '(unknown)'}: Encountered a YAML parsing exception when processing file metadata: ${e.reason}.
+                It's highly possible the input file contains duplicate mapping keys.
+                Will retry processing with necessary compatibility flags.
+                Please note that this behaviour is DEPRECATED and WILL be removed in a future version
+                without further notice, so the build WILL fail when supplied with YAML-incompatible meta.
+            `
+                .replace(/^\s+/gm, '')
+                .replace(/\n/g, ' ')
+                .trim();
+
+            log.warn(duplicateKeysDeprecationWarning);
+
+            return load(yaml, {json: true});
+        }
+
+        throw e;
+    }
+};
+
+export const separateAndExtractFrontMatter = (
+    fileContent: string,
+    filePath?: string,
+): ParseExistingMetadataReturn => {
+    const matches = matchMetadata(fileContent);
+
+    if (matches && matches.length > 0) {
+        const [, metadata, , metadataStrippedContent] = matches;
+
+        return {
+            frontMatter: transformFrontMatterValues(
+                duplicateKeysCompatibleLoad(
+                    escapeLiquidSubstitutionSyntax(metadata),
+                    filePath,
+                ) as FrontMatter,
+                (v) => (typeof v === 'string' ? unescapeLiquidSubstitutionSyntax(v) : v),
+            ),
+            frontMatterStrippedContent: metadataStrippedContent,
+            frontMatterLineCount: countLineAmount(metadata),
+        };
+    }
+
+    return {
+        frontMatter: {},
+        frontMatterStrippedContent: fileContent,
+        frontMatterLineCount: 0,
+    };
+};

package/src/transform/frontmatter/index.ts

@@ -0,0 +1,4 @@
+export * from './extract';
+export * from './emplace';
+export * from './transformValues';
+export {countLineAmount} from './common';

package/src/transform/frontmatter/transformValues.ts

@@ -0,0 +1,22 @@
+import {FrontMatter} from './common';
+
+export const transformFrontMatterValues = (
+    frontMatter: FrontMatter,
+    valueMapper: (v: unknown) => unknown,
+): FrontMatter => {
+    const transformInner = (something: unknown): unknown => {
+        if (typeof something === 'object' && something !== null) {
+            return Object.fromEntries(
+                Object.entries(something).map(([k, v]) => [k, transformInner(v)]),
+            );
+        }
+
+        if (Array.isArray(something)) {
+            return something.map((el) => transformInner(el));
+        }
+
+        return valueMapper(something);
+    };
+
+    return transformInner(frontMatter) as FrontMatter;
+};

package/src/transform/index.ts

@@ -3,7 +3,7 @@ import type {EnvType, OptionsType, OutputType} from './typings';
 import {bold} from 'chalk';
 
 import {log} from './log';
-import liquid from './liquid';
+import liquidSnippet from './liquid';
 import initMarkdownit from './md';
 
 function applyLiquid(input: string, options: OptionsType) {
@@ -15,7 +15,9 @@ function applyLiquid(input: string, options: OptionsType) {
         isLiquided = false,
     } = options;
 
-    return disableLiquid || isLiquided ? input : liquid(input, vars, path, {conditionsInCode});
+    return disableLiquid || isLiquided
+        ? input
+        : liquidSnippet(input, vars, path, {conditionsInCode});
 }
 
 function handleError(error: unknown, path?: string): never {

package/src/transform/liquid/index.ts

@@ -1,5 +1,13 @@
 import type {Dictionary} from 'lodash';
 
+import {
+    countLineAmount,
+    emplaceSerializedFrontMatter,
+    separateAndExtractFrontMatter,
+    serializeFrontMatter,
+    transformFrontMatterValues,
+} from '../frontmatter';
+
 import applySubstitutions from './substitutions';
 import {prepareSourceMap} from './sourceMap';
 import applyCycles from './cycles';
@@ -66,7 +74,7 @@ function repairCode(str: string, codes: string[]) {
     return replace(fence, fence, (code) => codes[Number(code)], str);
 }
 
-function liquid<
+function liquidSnippet<
     B extends boolean = false,
     C = B extends false ? string : {output: string; sourceMap: Dictionary<string>},
 >(
@@ -141,6 +149,67 @@ function liquid<
     return output as unknown as C;
 }
 
-// 'export default' instead of 'export = ' because of circular dependency with './cycles.ts'.
-// somehow it breaks import in './cycles.ts' and imports nothing
-export default liquid;
+type TransformSourceMapOptions = {
+    emplacedResultOffset: number;
+    emplacedSourceOffset: number;
+};
+
+function transformSourceMap(
+    sourceMap: Dictionary<string>,
+    {emplacedResultOffset, emplacedSourceOffset}: TransformSourceMapOptions,
+) {
+    return Object.fromEntries(
+        Object.entries(sourceMap).map(([lineInResult, lineInSource]) => [
+            (Number(lineInResult) + emplacedResultOffset).toString(),
+            (Number(lineInSource) + emplacedSourceOffset).toString(),
+        ]),
+    );
+}
+
+function liquidDocument<
+    B extends boolean = false,
+    C = B extends false ? string : {output: string; sourceMap: Dictionary<string>},
+>(
+    originInput: string,
+    vars: Record<string, unknown>,
+    path?: string,
+    settings?: ArgvSettings & {withSourceMap?: B},
+): C {
+    const {frontMatter, frontMatterStrippedContent, frontMatterLineCount} =
+        separateAndExtractFrontMatter(originInput, path);
+
+    const transformedFrontMatter = transformFrontMatterValues(frontMatter, (v) =>
+        typeof v === 'string'
+            ? liquidSnippet(v, vars, path, {...settings, withSourceMap: false})
+            : v,
+    );
+    const transformedAndSerialized = serializeFrontMatter(transformedFrontMatter);
+
+    // -1 comes from the fact that the last line in serialized FM is the same as the first line in stripped content
+    const resultFrontMatterOffset = Math.max(0, countLineAmount(transformedAndSerialized) - 1);
+    const sourceFrontMatterOffset = Math.max(0, frontMatterLineCount - 1);
+
+    const liquidProcessedContent = liquidSnippet(frontMatterStrippedContent, vars, path, settings);
+
+    // typeof check for better inference; the catch is that return of liquidSnippet can be an
+    // object even with source maps off, see `substitutions.test.ts`
+    return (settings?.withSourceMap && typeof liquidProcessedContent === 'object'
+        ? {
+              output: emplaceSerializedFrontMatter(
+                  liquidProcessedContent.output,
+                  transformedAndSerialized,
+              ),
+              sourceMap: transformSourceMap(liquidProcessedContent.sourceMap, {
+                  emplacedResultOffset: resultFrontMatterOffset,
+                  emplacedSourceOffset: sourceFrontMatterOffset,
+              }),
+          }
+        : emplaceSerializedFrontMatter(
+              liquidProcessedContent as string,
+              transformedAndSerialized,
+          )) as unknown as C;
+}
+
+// both default and named exports for convenience
+export {liquidDocument, liquidSnippet};
+export default liquidDocument;

package/src/transform/plugins/file/README.md

@@ -10,25 +10,79 @@
 
 ## Attributes
 
-|Name|Required|Description|
-|---|---|---|
-|`src`|yes|URL of the file. Will be mapped to [`href` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href)|
-|`name`|yes|Name of the file. Will be mapped to [`download` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-download)|
-|`lang`|-|Language of the file content. Will be mapped to [`hreflang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-hreflang)|
-|`referrerpolicy`|-|[`referrerpolicy` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-referrerpolicy)|
-|`rel`|-|[`rel` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-rel)|
-|`target`|-|[`target` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target)|
-|`type`|-|[`type` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-type)|
+| Name             | Required | Description                                                                                                                                       |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`            | yes      | URL of the file. Will be mapped to [`href` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href)                      |
+| `name`           | yes      | Name of the file. Will be mapped to [`download` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-download)             |
+| `lang`           | -        | Language of the file content. Will be mapped to [`hreflang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-hreflang) |
+| `referrerpolicy` | -        | [`referrerpolicy` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-referrerpolicy)                                     |
+| `rel`            | -        | [`rel` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-rel)                                                           |
+| `target`         | -        | [`target` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target)                                                     |
+| `type`           | -        | [`type` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-type)                                                         |
 
 > _Note: other attributes will be ignored_
 
 ## Plugin options
 
-|Name|Type|Description|
-|---|---|---|
-|`fileExtraAttrs`|`[string, string][]`|Adds additional attributes to rendered hyperlink|
+| Name             | Type                 | Description                                      |
+| ---------------- | -------------------- | ------------------------------------------------ |
+| `fileExtraAttrs` | `[string, string][]` | Adds additional attributes to rendered hyperlink |
 
 ## CSS public variables
 
-* `--yfm-file-icon` – sets custom file icon image
-* `--yfm-file-icon-color` – sets custom file icon color
+- `--yfm-file-icon` – sets custom file icon image
+- `--yfm-file-icon-color` – sets custom file icon color
+
+  _common_
+
+- `--yfm-color-text`
+- `--yfm-color-link`
+- `--yfm-color-base`
+- `--yfm-color-link-hover`
+- `--yfm-color-table`
+- `--yfm-color-table-row-background`
+- `--yfm-color-border`
+- `--yfm-color-accent`
+
+  _code_
+
+- `--yfm-color-inline-code`
+- `--yfm-color-inline-code-background`
+- `--yfm-color-code-background`
+
+  _hightlight_
+
+- `--yfm-color-hljs-background`
+- `--yfm-color-hljs-subst`
+- `--yfm-color-hljs-comment`
+- `--yfm-color-hljs-deletion`
+- `--yfm-color-hljs-section`
+- `--yfm-color-hljs-pseudo`
+- `--yfm-color-hljs-literal`
+- `--yfm-color-hljs-addition`
+- `--yfm-color-hljs-meta`
+- `--yfm-color-hljs-meta-string`
+
+  _note_
+
+- `--yfm-color-note-tip`
+- `--yfm-color-note-tip-background`
+- `--yfm-color-note-warning`
+- `--yfm-color-note-warning-background`
+- `--yfm-color-note-important-background`
+- `--yfm-color-note-info-background`
+
+  _term_
+
+- `--yfm-color-term-title`
+- `--yfm-color-term-title-hover`
+- `--yfm-color-term-dfn-background`
+- `--yfm-color-term-dfn-shadow`
+- `--yfm-color-term-dfn-pseudo-shadow`
+
+  _modal_
+
+- `--yfm-color-modal-content`
+- `--yfm-color-modal-actions-hover`
+- `--yfm-color-modal-wide-content`
+- `--yfm-color-modal-wide-content-overlay`

package/src/transform/utilsFS.ts

@@ -4,7 +4,7 @@ import {readFileSync, statSync} from 'fs';
 import escapeRegExp from 'lodash/escapeRegExp';
 import {join, parse, relative, resolve, sep} from 'path';
 
-import liquid from './liquid';
+import liquidSnippet from './liquid';
 import {StateCore} from './typings';
 import {defaultTransformLink} from './utils';
 
@@ -68,7 +68,7 @@ export function getFileTokens(path: string, state: StateCore, options: GetFileTo
     let sourceMap;
 
     if (!disableLiquid) {
-        const liquidResult = liquid(content, builtVars, path, {
+        const liquidResult = liquidSnippet(content, builtVars, path, {
             withSourceMap: true,
             conditionsInCode,
         });

package/src/scss/_variables.scss

@@ -1,16 +0,0 @@
-$baseColor: #ffffff;
-$accentColor: #027bf3;
-
-$textColor: rgba(0, 0, 0, 0.7);
-$borderColor: rgba(0, 0, 0, 0.07);
-$backgroundColor: rgba(0, 0, 0, 0.02);
-
-$inlineCodeColor: rgba(59, 96, 128, 1);
-$inlineCodeBackgroundColor: rgba(107, 132, 153, 0.12);
-
-$codeBackgroundColor: rgba(107, 132, 153, 0.12);
-
-$tableRowBackgroundColor: rgba(0, 0, 0, 0.02);
-
-$linkColor: $accentColor;
-$linkHoverColor: #004080;