Merge branch 'main' into feature/extensionless-urls

Author: reakaleek

.github/workflows/preview-build.yml

@@ -8,6 +8,9 @@ on:
       - reopened
       - labeled
       - unlabeled
+  push:
+    branches:
+      - main
   workflow_call:
     inputs:
       strict:
@@ -38,42 +41,67 @@ jobs:
     steps:
 
       - name: Get changed files
+        if: github.event_name == 'pull_request'
         id: check-files
         uses: tj-actions/changed-files@d6e91a2266cdb9d62096cebf1e8546899c6aa18f # v45.0.6
         with:
           files: ${{ inputs.path-pattern != '' && inputs.path-pattern || '**' }}
 
       - name: Checkout
-        if: steps.check-files.outputs.any_changed == 'true'
+        if: github.event_name != 'pull_request' || steps.check-files.outputs.any_changed == 'true'
         uses: actions/checkout@v4
         with: 
           persist-credentials: false
 
-      - name: Store PR data
+      - name: Generate path prefix
         env:
           PR_NUMBER: ${{ github.event.pull_request.number }}
-          PR_REF: ${{ github.event.pull_request.head.sha }}
-          ANY_CHANGED: ${{ steps.check-files.outputs.any_changed }}
         run: |
-          cat << EOF > pull_request.json
+          case "${GITHUB_EVENT_NAME}" in
+            "pull_request")
+              echo "PATH_PREFIX=/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}" >> $GITHUB_ENV
+              ;;
+            "push")
+              echo "PATH_PREFIX=/${GITHUB_REPOSITORY}/tree/${GITHUB_REF_NAME}" >> $GITHUB_ENV
+              if [[ ! "${GITHUB_REF_NAME}" =~ ^(main|master|16\.x)$ ]]; then
+                echo "Unsupported ref name: ${GITHUB_REF_NAME}";
+                exit 1;
+              fi
+              ;;
+            *)
+              echo "Unsupported event: ${GITHUB_EVENT_NAME}";
+              exit 1;
+              ;;
+          esac
+          
+      - name: Store deployment metadata
+        id: metadata
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REF: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+          SHOULD_DEPLOY: ${{ github.event_name == 'pull_request' && steps.check-files.outputs.any_changed || 'true' }}
+        run: |
+          cat << EOF > deployment_metadata.json
           {
-            "number": ${PR_NUMBER},
-            "ref": "${PR_REF}",
-            "any_changed": ${ANY_CHANGED}
+            "pr_number": "${PR_NUMBER}",
+            "ref": "${REF}",
+            "should_deploy": "${SHOULD_DEPLOY}",
+            "path_prefix": "${PATH_PREFIX}"
           }
           EOF
+          echo "should_deploy=${SHOULD_DEPLOY}" >> "${GITHUB_OUTPUT}"
       
-      - name: Upload PR data
+      - name: Upload deployment metadata
         uses: actions/upload-artifact@v4
         with:
-          name: pull-request-data
-          path: pull_request.json
+          name: deployment_metadata
+          path: deployment_metadata.json
           if-no-files-found: error
           retention-days: 1
           compression-level: 1
 
       - name: Bootstrap Action Workspace
-        if: github.repository == 'elastic/docs-builder' && steps.check-files.outputs.any_changed == 'true'
+        if: github.repository == 'elastic/docs-builder' && steps.metadata.outputs.should_deploy == 'true'
         uses: ./.github/actions/bootstrap
 
       - name: Set REDESIGN feature flag
@@ -83,22 +111,20 @@ jobs:
       # we run our artifact directly please use the prebuild
       # elastic/docs-builder@main GitHub Action for all other repositories!
       - name: Build documentation
-        if: github.repository == 'elastic/docs-builder' && steps.check-files.outputs.any_changed == 'true'
-        env:
-          PR_NUMBER: ${{ github.event.pull_request.number }}
+        if: github.repository == 'elastic/docs-builder' && steps.metadata.outputs.should_deploy == 'true'
         run: |
-          dotnet run --project src/docs-builder -- --strict --path-prefix "/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}"
+          dotnet run --project src/docs-builder -- --strict --path-prefix "${PATH_PREFIX}"
 
       - name: Build documentation
-        if: github.repository != 'elastic/docs-builder' && steps.check-files.outputs.any_changed == 'true'
+        if: github.repository != 'elastic/docs-builder' && steps.metadata.outputs.should_deploy == 'true'
         uses: elastic/docs-builder@main
         continue-on-error: ${{ fromJSON(inputs.continue-on-error != '' && inputs.continue-on-error || 'false') }}
         with:
-          prefix: "/${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
+          prefix: ${{ env.PATH_PREFIX }}
           strict: ${{ fromJSON(inputs.strict != '' && inputs.strict || 'true') }}
 
       - uses: actions/upload-artifact@v4
-        if: steps.check-files.outputs.any_changed == 'true'
+        if: steps.metadata.outputs.should_deploy == 'true'
         with:
           name: docs
           path: .artifacts/docs/html/

.github/workflows/preview-deploy.yml

@@ -14,53 +14,57 @@ permissions:
   actions: read
 
 jobs:
-  pull-request-data:
+  deployment-metadata:
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     runs-on: ubuntu-latest
     outputs: 
-      number: ${{ steps.pull_request.outputs.number }}
-      ref: ${{ steps.pull_request.outputs.ref }}
-      any_changed: ${{ steps.pull_request.outputs.any_changed }}
+      pr_number: ${{ steps.metadata.outputs.pr_number }}
+      ref: ${{ steps.metadata.outputs.ref }}
+      should_deploy: ${{ steps.metadata.outputs.should_deploy }}
+      path_prefix: ${{ steps.metadata.outputs.path_prefix }}
     steps:
-      - name: Download PR data
+      - name: Download deployment metadata
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           gh run download ${{ github.event.workflow_run.id }} \
             --repo "${GITHUB_REPOSITORY}" \
-            --name pull-request-data
-      - name: Get PR data
-        id: pull_request
+            --name deployment_metadata
+      - name: Get deployment metadata
+        id: metadata
         run: |
           {
-            echo "number=$(jq -r '.number' pull_request.json)"
-            echo "ref=$(jq -r '.ref' pull_request.json)"
-            echo "any_changed=$(jq -r '.any_changed' pull_request.json)"
+            echo "pr_number=$(jq -r '.pr_number' deployment_metadata.json)"
+            echo "ref=$(jq -r '.ref' deployment_metadata.json)"
+            echo "path_prefix=$(jq -r '.path_prefix' deployment_metadata.json)"
+            echo "should_deploy=$(jq -r '.should_deploy' deployment_metadata.json)"
           } >> "${GITHUB_OUTPUT}"
     
   deploy:
-    needs: pull-request-data
-    if: needs.pull-request-data.outputs.any_changed == 'true'
+    needs: deployment-metadata
+    if: needs.deployment-metadata.outputs.should_deploy == 'true'
     runs-on: ubuntu-latest
     concurrency: 
-      group: ${{ github.workflow }}-${{ needs.pull-request-data.outputs.number }}
+      group: ${{ github.workflow }}-${{ needs.deployment-metadata.outputs.pr_number }}
       cancel-in-progress: true
     steps:
       - name: Create Deployment
         uses: actions/github-script@v7
         id: deployment
         env:
-          PR_NUMBER: ${{ needs.pull-request-data.outputs.number }}
-          PR_REF: ${{ needs.pull-request-data.outputs.ref }}
+          PR_NUMBER: ${{ needs.deployment-metadata.outputs.pr_number }}
+          REF: ${{ needs.deployment-metadata.outputs.ref }}
         with:
           result-encoding: string
           script: |
             const { owner, repo } = context.repo;
+            const prNumber = process.env.PR_NUMBER;
+            const environment = prNumber ? `docs-preview-${prNumber}` : 'docs-preview';
             const deployment = await github.rest.repos.createDeployment({
                 owner,
                 repo,
-                ref: process.env.PR_REF,
-                environment: `docs-preview-${process.env.PR_NUMBER}`,
+                environment,
+                ref: process.env.REF,
                 auto_merge: false,
                 required_contexts: [],
             })
@@ -86,25 +90,27 @@ jobs:
 
       - name: Upload to S3
         env:
-          PR_NUMBER: ${{ needs.pull-request-data.outputs.number }}
+          PR_NUMBER: ${{ needs.deployment-metadata.outputs.pr_number }}
+          PATH_PREFIX: ${{ needs.deployment-metadata.outputs.path_prefix }}
         run: |
-          aws s3 sync ./html "s3://elastic-docs-v3-website-preview/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}" --delete
+          aws s3 sync ./html "s3://elastic-docs-v3-website-preview${PATH_PREFIX}" --delete
           aws cloudfront create-invalidation \
             --distribution-id EKT7LT5PM8RKS \
-            --paths "/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}" "/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}/*"
+            --paths "${PATH_PREFIX}" "/${PATH_PREFIX}/*"
 
       - name: Update deployment status
         uses: actions/github-script@v7
         if: always() && steps.deployment.outputs.result
         env:
-          PR_NUMBER: ${{ needs.pull-request-data.outputs.number }}
+          PR_NUMBER: ${{ needs.deployment-metadata.outputs.pr_number }}
+          PATH_PREFIX: ${{ needs.deployment-metadata.outputs.path_prefix }}
         with:
           script: |
             await github.rest.repos.createDeploymentStatus({
               owner: context.repo.owner,
               repo: context.repo.repo,
               deployment_id: ${{ steps.deployment.outputs.result }},
               state: "${{ job.status == 'success' && 'success' || 'failure' }}",
-              environment_url: `https://docs-v3-preview.elastic.dev/${context.repo.owner}/${context.repo.repo}/pull/${process.env.PR_NUMBER}`,
+              environment_url: `https://docs-v3-preview.elastic.dev${process.env.PATH_PREFIX}`,
               log_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
             })

docs/migration/guide/how-to-set-up-docs-previews.md

@@ -25,21 +25,25 @@ This way you only build and deploy the docs when there are changes to the docs a
 name: docs-build <1>
 
 on:
+  push: <2>
+    branches: 
+        - main 
   pull_request: ~
 
 jobs:
   docs-preview:
-    uses: elastic/docs-builder/.github/workflows/preview-build.yml <2>
+    uses: elastic/docs-builder/.github/workflows/preview-build.yml <3>
     with:
-      path-pattern: docs/** <3>
+      path-pattern: docs/** <4>
     permissions:
       contents: read
       pull-requests: read
 ```
 
 1. The naming is important so that the `docs-deploy` workflow is triggered.
-2. This should be the path to your docs folder.
+2. You can omit the `push` event if you only want to build the docs on PRs.
 3. Reusable workflow: [elastic/docs-builder/.github/workflows/preview-build.yml](https://github.com/elastic/docs-builder/blob/main/.github/workflows/preview-build.yml)
+4. This should be the path to your docs folder.
 
 
 ::::

docs/syntax/_snippets/reusable-snippet.md

@@ -1,4 +1,4 @@
-This is a snippet included on "{{page_title}}".
+This is a snippet included on "{{context.page_title}}".
 
 :::{tip}
 This is a snippet

docs/testing/nested/index.md

@@ -1,3 +1,13 @@
-# Testing Nesting
+---
+sub:
+  x: "Variable"
+navigation_title: "Testing nesting and {{x}}"
+---
+# Testing Nesting and {{x}}
 
-The files in this directory are used for testing purposes. Do not edit these files unless you are working on tests.
+The files in this directory are used for testing purposes. Do not edit these files unless you are working on tests.
+
+
+## Injecting a {{x}} is supported in headers.
+
+This should show up in the file's table of contents too.

src/Elastic.Markdown/Helpers/Interpolation.cs

@@ -2,7 +2,9 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using System.Diagnostics.CodeAnalysis;
 using System.Text.RegularExpressions;
+using Elastic.Markdown.Myst;
 
 namespace Elastic.Markdown.Helpers;
 
@@ -14,18 +16,60 @@ internal static partial class InterpolationRegex
 
 public static class Interpolation
 {
-	public static bool ReplaceSubstitutions(this ReadOnlySpan<char> span, Dictionary<string, string>? properties, out string? replacement)
+	public static string ReplaceSubstitutions(
+		this string input,
+		ParserContext context
+	)
+	{
+		var span = input.AsSpan();
+		if (span.ReplaceSubstitutions([context.Substitutions, context.ContextSubstitutions], out var replacement))
+			return replacement;
+		return input;
+	}
+
+
+	public static bool ReplaceSubstitutions(
+		this ReadOnlySpan<char> span,
+		ParserContext context,
+		[NotNullWhen(true)] out string? replacement
+	) =>
+		span.ReplaceSubstitutions([context.Substitutions, context.ContextSubstitutions], out replacement);
+
+	public static bool ReplaceSubstitutions(
+		this ReadOnlySpan<char> span,
+		IReadOnlyDictionary<string, string>? properties,
+		[NotNullWhen(true)] out string? replacement
+	)
+	{
+		replacement = null;
+		if (properties is null || properties.Count == 0)
+			return false;
+
+		if (span.IndexOf("}}") < 0)
+			return false;
+
+		return span.ReplaceSubstitutions([properties], out replacement);
+	}
+
+	public static bool ReplaceSubstitutions(
+		this ReadOnlySpan<char> span,
+		IReadOnlyDictionary<string, string>[] properties,
+		[NotNullWhen(true)] out string? replacement
+	)
 	{
 		replacement = null;
 		if (span.IndexOf("}}") < 0)
 			return false;
 
-		var substitutions = properties ?? new();
-		if (substitutions.Count == 0)
+		if (properties.Length == 0 || properties.Sum(p => p.Count) == 0)
 			return false;
 
+		var lookups = properties
+			.Select(p => p as Dictionary<string, string> ?? new Dictionary<string, string>(p, StringComparer.OrdinalIgnoreCase))
+			.Select(d => d.GetAlternateLookup<ReadOnlySpan<char>>())
+			.ToArray();
+
 		var matchSubs = InterpolationRegex.MatchSubstitutions().EnumerateMatches(span);
-		var lookup = substitutions.GetAlternateLookup<ReadOnlySpan<char>>();
 
 		var replaced = false;
 		foreach (var match in matchSubs)
@@ -35,14 +79,15 @@ public static bool ReplaceSubstitutions(this ReadOnlySpan<char> span, Dictionary
 
 			var spanMatch = span.Slice(match.Index, match.Length);
 			var key = spanMatch.Trim(['{', '}']);
+			foreach (var lookup in lookups)
+			{
+				if (!lookup.TryGetValue(key, out var value))
+					continue;
 
-			if (!lookup.TryGetValue(key, out var value))
-				continue;
-
-			replacement ??= span.ToString();
-			replacement = replacement.Replace(spanMatch.ToString(), value);
-			replaced = true;
-
+				replacement ??= span.ToString();
+				replacement = replacement.Replace(spanMatch.ToString(), value);
+				replaced = true;
+			}
 		}
 
 		return replaced;