electron · dsanders11 · Aug 12, 2024 · Jun 1, 2024 · Jun 3, 2024 · Jun 4, 2024
@@ -0,0 +1,51 @@
+{
+  "title": "JSON schema for API history blocks in Electron documentation",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$comment": "If you change this schema, remember to edit the TypeScript interfaces in the linting script.",
+  "definitions": {
+    "changeSchema": {
+      "type": "object",
+      "properties": {
+        "pr-url": {
+          "type": "string",
+          "pattern": "^https://github.com/electron/electron/pull/\\d+$"
+        },
+        "breaking-changes-header": {
+          "type": "string",
+          "minLength": 3
+        },
+        "description": {
+          "type": "string",
+          "minLength": 3,
+          "maxLength": 72
+        }
+      },
+      "required": [
+        "pr-url"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "type": "object",
+  "properties": {
+    "added": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/changeSchema"
+      }
+    },
+    "deprecated": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/changeSchema"
+      }
+    },
+    "changes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/changeSchema"
+      }
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/docs/latest/api/base-window.md b/docs/latest/api/base-window.md
@@ -1083,6 +1083,15 @@ win.setSheetOffset(toolbarRect.height)
 
 #### `win.flashFrame(flag)`
 
+```YAML history
+added:
+  - pr-url: https://github.com/electron/electron/pull/35658
+changes:
+  - pr-url: https://github.com/electron/electron/pull/41391
+    description: Made `window.flashFrame(bool)` flash continuously on macOS.
+    breaking-changes-header: behavior-changed-windowflashframebool-will-flash-dock-icon-continuously-on-macos
+```
+
 * `flag` boolean
 
 Starts or stops flashing the window to attract user's attention.

diff --git a/docs/latest/api/web-contents-view.md b/docs/latest/api/web-contents-view.md
@@ -41,6 +41,15 @@ Process: [Main](latest/glossary.md#main-process)
 
 ### `new WebContentsView([options])`
 
+```YAML history
+added:
+  - pr-url: https://github.com/electron/electron/pull/35658
+changes:
+  - pr-url: https://github.com/electron/electron/pull/42086
+    description: Extended `WebContentsView` to accept pre-existing `webContents` object.
+    breaking-changes-header: behavior-changed-browserviewsetautoresize-behavior-on-macos
+```
+
 * `options` Object (optional)
   * `webPreferences` [WebPreferences](latest/api/structures/web-preferences.md) (optional) - Settings of web page's features.
   * `webContents` [WebContents](latest/api/web-contents.md) (optional) - If present, the given WebContents will be adopted by the WebContentsView. A WebContents may only be presented in one WebContentsView at a time.

@@ -8,6 +8,7 @@ import apiOptionsClass from './src/transformers/api-options-class';
 import apiStructurePreviews from './src/transformers/api-structure-previews';
 import jsCodeBlocks from './src/transformers/js-code-blocks';
 import fiddleEmbedder from './src/transformers/fiddle-embedder';
+import apiHistory from './src/transformers/api-history';
 
 const config: Config = {
   title: 'Electron',
@@ -219,6 +220,7 @@ const config: Config = {
             apiStructurePreviews,
             jsCodeBlocks,
             fiddleEmbedder,
+            apiHistory,
             [npm2yarn, { sync: true, converters: ['yarn'] }],
           ],
         },

@@ -38,15 +38,22 @@
     "@docusaurus/remark-plugin-npm2yarn": "3.4.0",
     "@docusaurus/theme-mermaid": "3.4.0",
     "@mdx-js/react": "^3.0.0",
+    "adm-zip": "^0.5.14",
+    "ajv": "^8.16.0",
     "clsx": "^1.1.1",
     "docusaurus-plugin-sass": "^0.2.1",
+    "dotenv": "^16.0.3",
+    "execa": "^5.0.0",
+    "hast-util-from-html": "^2.0.1",
+    "mdast-util-from-markdown": "^2.0.1",
     "prism-react-renderer": "^2.3.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-markdown": "^9.0.1",
     "react-useportal": "^1.0.14",
     "sass": "^1.37.5",
-    "semver": "^7.5.4"
+    "semver": "^7.5.4",
+    "yaml": "^2.4.3"
   },
   "devDependencies": {
     "@crowdin/cli": "^3.9.3",
@@ -57,6 +64,7 @@
     "@electron/docs-parser": "^1.0.1",
     "@electron/lint-roller": "^2.2.0",
     "@tsconfig/docusaurus": "^2.0.3",
+    "@types/adm-zip": "^0.5.5",
     "@types/fs-extra": "^9.0.13",
     "@types/mdast": "^4.0.4",
     "@types/node": "^18.11.10",

@@ -14,6 +14,7 @@ import { addFrontmatterToAllDocs } from './tasks/add-frontmatter';
 import { createSidebar } from './tasks/create-sidebar';
 import { fixContent } from './tasks/md-fixers';
 import { copyNewContent } from './tasks/copy-new-content';
+import { preprocessApiHistory } from './tasks/preprocess-api-history';
 
 const DOCS_FOLDER = path.join(__dirname, '..', 'docs', 'latest');
 
@@ -65,6 +66,9 @@ const start = async (source: string): Promise<void> => {
   logger.info('Copying new content');
   await copyNewContent(DOCS_FOLDER);
 
+  logger.info('Finding, validating, and uncommenting API history blocks');
+  await preprocessApiHistory(DOCS_FOLDER);
+
   logger.info('Fixing markdown');
   await fixContent('docs', 'latest');
 

@@ -0,0 +1,199 @@
+import globby from 'globby';
+import path from 'path';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { visit } from 'unist-util-visit';
+import type { Html, Root } from 'mdast';
+import type { Node, Literal } from 'unist';
+import Ajv, { JSONSchemaType, ValidateFunction } from 'ajv';
+import { readFile, writeFile } from 'fs/promises';
+import { fromHtml } from 'hast-util-from-html';
+import logger from '@docusaurus/logger';
+import { parse as parseYaml } from 'yaml';
+
+const apiHistoryRegex = /<!--[\s\S]*?(```[\s\S]*?```)[\s\S]*?-->/;
+
+interface ChangeSchema {
+  'pr-url': string;
+  'breaking-changes-header'?: string;
+  description?: string;
+}
+
+interface ApiHistory {
+  added?: ChangeSchema[];
+  deprecated?: ChangeSchema[];
+  changes?: ChangeSchema[];
+}
+
+interface LiteralString extends Literal {
+  value: string;
+}
+
+// Copied from here: <https://github.com/electron/website/blob/feat/api-history/scripts/tasks/add-frontmatter.ts#L16-L23>
+const getMarkdownFiles = async (startPath: string) => {
+  const filesPaths = await globby(path.posix.join(startPath, '**/*.md'));
+
+  const files: Map<string, string> = new Map();
+  for (const filePath of filesPaths) {
+    const content = await readFile(filePath, 'utf-8');
+    files.set(filePath, content);
+  }
+
+  return files;
+};
+
+// Copied from here but slightly different: <https://github.com/electron/lint-roller/blob/bac245478ba69017c2a82e8ba1b2884a37647494/bin/lint-markdown-api-history.ts#L42-L67>
+function findPossibleApiHistoryBlocks(tree: Root) {
+  const codeBlocks: Html[] = [];
+
+  visit(
+    tree,
+    (node: Node) =>
+      node.type === 'html' &&
+      (node as LiteralString).value.toLowerCase().includes('```') &&
+      (node as LiteralString).value.toLowerCase().includes('yaml') &&
+      (node as LiteralString).value.toLowerCase().includes('history'),
+    (node) => {
+      codeBlocks.push(node as Html);
+    }
+  );
+
+  return codeBlocks;
+}
+
+function findValidApiHistoryBlocks(
+  possibleHistoryBlocks: Html[],
+  filePath: string,
+  validateAgainstSchema: ValidateFunction<ApiHistory>
+) {
+  const validHistoryBlocks: Html[] = [];
+
+  // All of the validation logic copied from here: <https://github.com/electron/lint-roller/blob/bac245478ba69017c2a82e8ba1b2884a37647494/bin/lint-markdown-api-history.ts#L117-L176>
+  for (const possibleHistoryBlock of possibleHistoryBlocks) {
+    const {
+      children: [htmlComment],
+    } = fromHtml(possibleHistoryBlock.value);
+
+    if (htmlComment.type !== 'comment') {
+      logger.warn(
+        `Possible API History block is not in a HTML comment (${logger.green(
+          filePath
+        )})`
+      );
+      continue;
+    }
+
+    const {
+      children: [codeBlock],
+    } = fromMarkdown(htmlComment.value);
+
+    if (
+      codeBlock.type !== 'code' ||
+      codeBlock.lang?.toLowerCase() !== 'yaml' ||
+      codeBlock.meta?.trim() !== 'history'
+    ) {
+      // TODO: Better error message
+      logger.warn(
+        `Error parsing possible history block in ${logger.green(filePath)}`
+      );
+      continue;
+    }
+
+    let unsafeHistory = null;
+
+    try {
+      unsafeHistory = parseYaml(codeBlock.value);
+    } catch (error) {
+      logger.warn(
+        `Error parsing YAML in possible history block (${logger.green(
+          filePath
+        )})`
+      );
+      continue;
+    }
+
+    const isValid = validateAgainstSchema(unsafeHistory);
+
+    if (!isValid) {
+      logger.warn(
+        `Error validating YAML in possible history block (${logger.green(
+          filePath
+        )})`
+      );
+      continue;
+    }
+
+    validHistoryBlocks.push(possibleHistoryBlock);
+  }
+
+  return validHistoryBlocks;
+}
+
+export const preprocessApiHistory = async (startPath: string) => {
+  // ? Allow for a custom schema to be passed in.
+  const schema = path.resolve(startPath, 'api-history.schema.json');
+
+  let validateAgainstSchema: ValidateFunction<ApiHistory> | null = null;
+
+  try {
+    const ajv = new Ajv();
+    const ApiHistorySchemaFile = await readFile(schema, { encoding: 'utf-8' });
+    const ApiHistorySchema = JSON.parse(
+      ApiHistorySchemaFile
+    ) as JSONSchemaType<ApiHistory>;
+    validateAgainstSchema = ajv.compile(ApiHistorySchema);
+  } catch (error) {
+    logger.error(`Error reading API history schema:\n${error}`);
+    return;
+  }
+
+  const files = await getMarkdownFiles(startPath);
+
+  for (const [filePath, content] of files) {
+    const tree = fromMarkdown(content);
+
+    const possibleHistoryBlocks = findPossibleApiHistoryBlocks(tree as Root);
+    const validHistoryBlocks = findValidApiHistoryBlocks(
+      possibleHistoryBlocks,
+      filePath,
+      validateAgainstSchema
+    );
+
+    if (validHistoryBlocks.length === 0) continue;
+
+    let newContent = content;
+    let fileLengthDifference = 0;
+
+    // Strip HTML comment tags from history blocks
+    for (const validHistoryBlock of validHistoryBlocks) {
+      const apiHistoryRegexMatches =
+        validHistoryBlock.value.match(apiHistoryRegex);
+
+      if (apiHistoryRegexMatches.length !== 2) {
+        logger.warn(
+          `Error extracting the API history block inside HTML comment in ${logger.green(
+            filePath
+          )}`
+        );
+        continue;
+      }
+
+      const [, historyBlockWithoutTags] = apiHistoryRegexMatches;
+
+      const start = newContent.substring(
+        0,
+        validHistoryBlock.position!.start.offset + fileLengthDifference
+      );
+      const end = newContent.substring(
+        validHistoryBlock.position!.end.offset + fileLengthDifference
+      );
+
+      // Stripping the HTML comment tags of a history block will offset the position of the next history block
+      fileLengthDifference +=
+        historyBlockWithoutTags.length - validHistoryBlock.value.length;
+
+      newContent = start + historyBlockWithoutTags + end;
+    }
+
+    await writeFile(filePath, newContent, { encoding: 'utf-8' });
+  }
+};