chore: introduce md templates (#17632)

docs/src/api/class-framelocator.md

@@ -125,7 +125,7 @@ Returns locator to the last matching frame.
 * since: v1.17
 - returns: <[Locator]>
 
-The method finds an element matching the specified selector in the FrameLocator's subtree.
+%%-template-locator-locator-%%
 
 ### param: FrameLocator.locator.selector = %%-find-selector-%%
 * since: v1.17

docs/src/api/class-locator.md

@@ -762,7 +762,7 @@ Returns locator to the last matching element.
 * since: v1.14
 - returns: <[Locator]>
 
-The method finds an element matching the specified selector in the `Locator`'s subtree. It also accepts filter options, similar to [`method: Locator.filter`] method.
+%%-template-locator-locator-%%
 
 ### param: Locator.locator.selector = %%-find-selector-%%
 * since: v1.14

docs/src/api/params.md

@@ -1057,3 +1057,7 @@ When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`,
 - %%-screenshot-option-type-%%
 - %%-screenshot-option-mask-%%
 - %%-input-timeout-%%
+
+## template-locator-locator
+
+The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to [`method: Locator.filter`] method.

packages/playwright-core/types/types.d.ts

@@ -9837,7 +9837,7 @@ export interface Locator {
   last(): Locator;
 
   /**
-   * The method finds an element matching the specified selector in the `Locator`'s subtree. It also accepts filter options,
+   * The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options,
    * similar to [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) method.
    * @param selector A selector to use when resolving DOM element. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
    * @param options
@@ -14738,7 +14738,8 @@ export interface FrameLocator {
   last(): FrameLocator;
 
   /**
-   * The method finds an element matching the specified selector in the FrameLocator's subtree.
+   * The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options,
+   * similar to [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) method.
    * @param selector A selector to use when resolving DOM element. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
    * @param options
    */

utils/doclint/api_parser.js

@@ -294,6 +294,14 @@ function applyTemplates(body, params) {
       if (!template)
         throw new Error('Bad template: ' + key);
       node.children.push(...template.children.map(c => md.clone(c)));
+    } else if (node.text && node.text.includes('%%-template-')) {
+      node.text.replace(/%%-template-[^%]+-%%/, templateName => {
+        const template = paramsMap.get(templateName);
+        if (!template)
+          throw new Error('Bad template: ' + templateName);
+        const nodeIndex = parent.children.indexOf(node);
+        parent.children = [...parent.children.slice(0, nodeIndex), ...template.children, ...parent.children.slice(nodeIndex + 1)];
+      });
     }
     for (const child of node.children || [])
       visit(child, node);