Merge branch 'main' into feature/index-documents

Author: Mpdreamz

.github/dependabot.yml

@@ -16,6 +16,12 @@ updates:
       interval: 'weekly'
       day: 'monday'
       time: '08:00'
+    groups:
+      tailwindcss:
+        patterns:
+          - 'tailwindcss'
+          - '@tailwindcss/postcss'
+          - 'prettier-plugin-tailwindcss'
     labels:
       - chore
   - package-ecosystem: nuget

.github/workflows/pr.yml renamed to .github/workflows/ci.yml

@@ -1,6 +1,9 @@
-name: PR
+name: ci
 
 on:
+  push:
+    branches:
+      - main
   pull_request:
 
 permissions:
@@ -14,7 +17,7 @@ env:
   NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
 
 jobs:
-  validate-navigation:
+  validate-assembler:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -23,9 +26,12 @@ jobs:
         id: bootstrap
         uses: ./.github/actions/bootstrap
 
-      - name: Build
+      - name: Validate Navigation
         run: dotnet run --project src/tooling/docs-assembler -c release -- navigation validate
 
+      - name: Validate Content Sources
+        run: dotnet run --project src/tooling/docs-assembler -c release -- content-source validate
+
   build-lambda:
     uses: ./.github/workflows/build-link-index-updater-lambda.yml
 

.github/workflows/preview-build.yml

@@ -10,6 +10,13 @@ on:
     branches:
       - main
       - master
+      # TODO remove these need to be added to individual repositories
+      - '\d+.\d+.\d+'
+      - '\d+.\d+'
+      - '\d+.x'
+    tags:
+      - 'v?\d+.\d+.\d+'
+      - 'v?\d+.\d+'
   workflow_call:
     inputs:
       strict:
@@ -44,6 +51,44 @@ permissions:
   pull-requests: read
 
 jobs:
+  match:
+    if: github.event.repository.fork == false # Skip running the job on the fork itself (It still runs on PRs on the upstream from forks)
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.head.ref || github.ref }}
+      cancel-in-progress: ${{ startsWith(github.event_name, 'pull_request') }}
+    runs-on: ubuntu-latest
+    outputs:
+      content-source-match: ${{ steps.event-check.outputs.content-source-match != '' && steps.event-check.outputs.content-source-match || steps.match.outputs.content-source-match }}
+      content-source-next: ${{ steps.event-check.outputs.content-source-next != '' && steps.event-check.outputs.content-source-next || steps.match.outputs.content-source-next }}
+      content-source-current: ${{ steps.event-check.outputs.content-source-current != '' && steps.event-check.outputs.content-source-current || steps.match.outputs.content-source-current }}
+      content-source-speculative: ${{ steps.event-check.outputs.content-source-speculative != '' && steps.event-check.outputs.content-source-speculative || steps.match.outputs.content-source-speculative }}
+    steps:
+      - name: Not a push event
+        id: event-check
+        if: contains(fromJSON('["merge_group", "pull_request", "pull_request_target"]'), github.event_name)
+        # we always want to run for pull requests, but we do not want to indicate its either content source
+        run: |
+          echo "content-source-match=true" >> $GITHUB_OUTPUT
+          echo "content-source-next=false" >> $GITHUB_OUTPUT
+          echo "content-source-current=false" >> $GITHUB_OUTPUT
+          echo "content-source-speculative=false" >> $GITHUB_OUTPUT
+      - name: Match for push events
+        id: match
+        if: contains(fromJSON('["push"]'), github.event_name)
+        uses: elastic/docs-builder/actions/assembler-match@main
+        with:
+          ref_name: ${{ github.ref_name }}
+          repository: ${{ github.repository }}
+      - name: Debug
+        run: |
+          echo "Non sensitive data, echo'ing here temporarily to validate this job before connecting it further into the build job"
+          echo "content-source-match=${{ steps.event-check.outputs.content-source-match != '' && steps.event-check.outputs.content-source-match || steps.match.outputs.content-source-match }}"
+          echo "content-source-next=${{ steps.event-check.outputs.content-source-next != '' && steps.event-check.outputs.content-source-next || steps.match.outputs.content-source-next }}"
+          echo "content-source-current=${{ steps.event-check.outputs.content-source-current != '' && steps.event-check.outputs.content-source-current || steps.match.outputs.content-source-current }}"
+          echo "content-source-speculative=${{ steps.event-check.outputs.content-source-speculative != '' && steps.event-check.outputs.content-source-speculative || steps.match.outputs.content-source-speculative }}"
+          echo "ref=${{ github.ref_name }}"
+          echo "repo=${{ github.repository }}"
+
   build:
     if: github.event.repository.fork == false # Skip running the job on the fork itself (It still runs on PRs on the upstream from forks)
     concurrency:
@@ -52,30 +97,36 @@ jobs:
     runs-on: ubuntu-latest
     env:
       GITHUB_PR_REF_NAME: ${{ github.event.pull_request.head.ref }}
+      MATCH: ${{ needs.match.outputs.content-source-match }}
+    needs: [ match ]
     steps:
 
       - name: Checkout
-        if:  contains(fromJSON('["push", "merge_group", "workflow_dispatch"]'), github.event_name)
+        if:  env.MATCH == 'true' && (contains(fromJSON('["push", "merge_group", "workflow_dispatch"]'), github.event_name))
         uses: actions/checkout@v4
         with:
           ref: ${{ github.event.pull_request.head.sha || github.ref }}
 
       - name: Get changed files
-        if: contains(fromJSON('["merge_group", "pull_request", "pull_request_target"]'), github.event_name)
+        if: env.MATCH == 'true' && (contains(fromJSON('["merge_group", "pull_request", "pull_request_target"]'), github.event_name))
         id: check-files
         uses: tj-actions/changed-files@2f7c5bfce28377bc069a65ba478de0a74aa0ca32 # v46.0.1
         with:
           files: ${{ inputs.path-pattern != '' && inputs.path-pattern || '**' }}
 
       - name: Checkout
-        if: startsWith(github.event_name, 'pull_request') && steps.check-files.outputs.any_modified == 'true'
+        if: env.MATCH == 'true' && (startsWith(github.event_name, 'pull_request') && steps.check-files.outputs.any_modified == 'true')
         uses: actions/checkout@v4
         with:
           ref: ${{ github.event.pull_request.head.sha || github.ref }}
           persist-credentials: false
 
       - name: Create Deployment
-        if: contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name) || (steps.check-files.outputs.any_modified == 'true' && startsWith(github.event_name, 'pull_request'))
+        if: |
+          env.MATCH == 'true' && 
+            (contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name) 
+                || (steps.check-files.outputs.any_modified == 'true' && startsWith(github.event_name, 'pull_request'))
+            )
         uses: actions/github-script@v7
         id: deployment
         env:
@@ -108,7 +159,7 @@ jobs:
             return deployment.data.id
 
       - name: Generate env.PATH_PREFIX
-        if: steps.deployment.outputs.result
+        if: env.MATCH == 'true' && (steps.deployment.outputs.result)
         env:
           PR_NUMBER: ${{ github.event.pull_request.number }}
           GITHUB_REF_NAME: ${{ github.ref_name }}
@@ -119,10 +170,6 @@ jobs:
               ;;
             "push" | "workflow_dispatch")
               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}'";
@@ -131,18 +178,22 @@ jobs:
           esac
 
       - name: Bootstrap Action Workspace
-        if: github.repository == 'elastic/docs-builder' && steps.deployment.outputs.result
+        if: env.MATCH == 'true' && (github.repository == 'elastic/docs-builder' && steps.deployment.outputs.result)
         uses: elastic/docs-builder/.github/actions/bootstrap@main
 
-      # we run our artifact directly please use the prebuild
+      # 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.deployment.outputs.result
+        if: env.MATCH == 'true' && (github.repository == 'elastic/docs-builder' && steps.deployment.outputs.result)
         run: |
           dotnet run --project src/tooling/docs-builder -- --strict --path-prefix "${PATH_PREFIX}"
 
       - name: Build documentation
-        if: github.repository != 'elastic/docs-builder' && (steps.deployment.outputs.result || (steps.check-files.outputs.any_modified == 'true' && github.event_name == 'merge_group'))
+        if: | 
+          env.MATCH == 'true' && 
+            (github.repository != 'elastic/docs-builder' && 
+                (steps.deployment.outputs.result || (steps.check-files.outputs.any_modified == 'true' && github.event_name == 'merge_group'))
+            )
         uses: elastic/docs-builder@main
         id: docs-build
         continue-on-error: ${{ fromJSON(inputs.continue-on-error != '' && inputs.continue-on-error || 'false') }}
@@ -152,32 +203,50 @@ jobs:
           metadata-only: ${{ fromJSON(inputs.metadata-only != '' && inputs.metadata-only || 'true') }}
 
       - name: 'Validate inbound links'
-        if: ${{ !cancelled() && steps.docs-build.outputs.skip != 'true' && (steps.deployment.outputs.result || (steps.check-files.outputs.any_modified == 'true' && github.event_name == 'merge_group')) }}
+        if: |
+          env.MATCH == 'true' && 
+          (!cancelled() && steps.docs-build.outputs.skip != 'true' 
+            && (steps.deployment.outputs.result || (steps.check-files.outputs.any_modified == 'true' && github.event_name == 'merge_group'))
+          )
         uses: elastic/docs-builder/actions/validate-inbound-local@main
 
       - name: 'Validate local path prefixes against those claimed by global navigation.yml'
-        if: ${{ !cancelled() && steps.docs-build.outputs.skip != 'true' && (steps.deployment.outputs.result || (steps.check-files.outputs.any_modified == 'true' && github.event_name == 'merge_group')) }}
+        if: |
+          env.MATCH == 'true' && 
+          (!cancelled() && steps.docs-build.outputs.skip != 'true' && 
+            (steps.deployment.outputs.result || (steps.check-files.outputs.any_modified == 'true' && github.event_name == 'merge_group'))
+          )
         uses: elastic/docs-builder/actions/validate-path-prefixes-local@main
 
       - uses: elastic/docs-builder/.github/actions/aws-auth@main
         if: ${{ !cancelled() && steps.docs-build.outputs.skip != 'true' && steps.deployment.outputs.result }}
 
       - name: Upload to S3
         id: s3-upload
-        if: ${{ !cancelled() && steps.docs-build.outputs.skip != 'true' && steps.deployment.outputs.result }}
+        if: |
+          env.MATCH == 'true' && 
+          (!cancelled() && steps.docs-build.outputs.skip != 'true' && steps.deployment.outputs.result)
         run: |
           aws s3 sync .artifacts/docs/html "s3://elastic-docs-v3-website-preview${PATH_PREFIX}" --delete --no-follow-symlinks
           aws cloudfront create-invalidation \
             --distribution-id EKT7LT5PM8RKS \
             --paths "${PATH_PREFIX}" "${PATH_PREFIX}/*"
 
       - name: Update Link Index
-        if: contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name) && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') && steps.s3-upload.outcome == 'success'
+        if: |
+          env.MATCH == 'true' && 
+          (contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name) 
+            && (
+                needs.match.outputs.content-source-current == 'true' 
+                || needs.match.outputs.content-source-next == 'true'
+                || needs.match.outputs.content-source-speculative == 'true'
+            ) 
+            && steps.s3-upload.outcome == 'success')
         uses: elastic/docs-builder/actions/update-link-index@main
 
       - name: Update deployment status
         uses: actions/github-script@v7
-        if: always() && steps.deployment.outputs.result
+        if: env.MATCH == 'true' && (always() && steps.deployment.outputs.result)
         env:
           PR_NUMBER: ${{ github.event.pull_request.number }}
           LANDING_PAGE_PATH: ${{ steps.docs-build.outputs.landing-page-path || env.PATH_PREFIX }}

.nvmrc

@@ -1 +1 @@
-22.13.1
+22.16.0

README.md

@@ -1,5 +1,7 @@
 # docs-builder
 
+[![ci](https://github.com/elastic/docs-builder/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/elastic/docs-builder/actions/workflows/ci.yml)
+
 You've reached the home of the latest incarnation of the documentation tooling.
 
 This repository is host to:

actions/assembler-config-validate/action.yml

@@ -0,0 +1,12 @@
+name: 'Documentation Assembler Configuration Validator'
+description: 'Ensures the assembler configuration is valid'
+
+branding:
+  icon: 'filter'
+  color: 'blue'
+
+runs:
+  using: 'docker'
+  image: "docker://ghcr.io/elastic/docs-assembler:edge"
+  env:
+    INPUT_COMMAND: "content-source validate"

actions/assembler-match/action.yml

@@ -16,8 +16,12 @@ inputs:
 outputs:
   content-source-match:
     description: 'true/false indicating the branch matches a content-source'
-  content-source-name:
-    description: "The name of the content source that matches (current/next) or empty"
+  content-source-next:
+    description: "true/false indicating the branch acts as the next content source"
+  content-source-current:
+    description: "true/false indicating the branch acts as the current content source"
+  content-source-speculative:
+    description: "true/false speculative match, used to build version branches before they are marked as current/next"
 
 runs:
   using: 'docker'

build/Targets.fs

@@ -34,7 +34,7 @@ let private version _ =
 
 let private format _ = exec { run "dotnet" "format" "--verbosity" "quiet" }
 
-let private watch _ = exec { run "dotnet" "watch" "--project" "src/docs-builder" "--no-hot-reload" "--" "serve" }
+let private watch _ = exec { run "dotnet" "watch" "--project" "src/tooling/docs-builder" "--no-hot-reload" "--" "serve" }
 
 let private lint _ =
     match exec {
@@ -164,4 +164,4 @@ let Setup (parsed:ParseResults<Build>) =
 
     for target in Build.Targets do
         let setup = wireCommandLine target 
-        setup target parsed
+        setup target parsed

docs-builder.sln

@@ -89,11 +89,18 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tooling", "tooling", "{73AB
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "authoring", "authoring", "{059E787F-85C1-43BE-9DD6-CE319E106383}"
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "assembler-filter", "assembler-filter", "{FB1C1954-D8E2-4745-BA62-04DD82FB4792}"
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "assembler-match", "assembler-match", "{FB1C1954-D8E2-4745-BA62-04DD82FB4792}"
 	ProjectSection(SolutionItems) = preProject
-		actions\assembler-filter\action.yml = actions\assembler-filter\action.yml
+		actions\assembler-match\action.yml = actions\assembler-match\action.yml
 	EndProjectSection
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "assembler-config-validate", "assembler-config-validate", "{E20FEEF9-1D1A-4CDA-A546-7FDC573BE399}"
+	ProjectSection(SolutionItems) = preProject
+		actions\assembler-config-validate\action.yml = actions\assembler-config-validate\action.yml
+	EndProjectSection
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Elastic.Documentation.LinkIndex", "src\Elastic.Documentation.LinkIndex\Elastic.Documentation.LinkIndex.csproj", "{FD1AC230-798B-4AB9-8CE6-A06264885DBC}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -155,6 +162,10 @@ Global
 		{CD94F9E4-7FCD-4152-81F1-4288C6B75367}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{CD94F9E4-7FCD-4152-81F1-4288C6B75367}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{CD94F9E4-7FCD-4152-81F1-4288C6B75367}.Release|Any CPU.Build.0 = Release|Any CPU
+		{FD1AC230-798B-4AB9-8CE6-A06264885DBC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{FD1AC230-798B-4AB9-8CE6-A06264885DBC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{FD1AC230-798B-4AB9-8CE6-A06264885DBC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{FD1AC230-798B-4AB9-8CE6-A06264885DBC}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{4D198E25-C211-41DC-9E84-B15E89BD7048} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A}
@@ -178,5 +189,7 @@ Global
 		{059E787F-85C1-43BE-9DD6-CE319E106383} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A}
 		{7D36DDDA-9E0B-4D2C-8033-5D62FF8B6166} = {059E787F-85C1-43BE-9DD6-CE319E106383}
 		{FB1C1954-D8E2-4745-BA62-04DD82FB4792} = {245023D2-D3CA-47B9-831D-DAB91A2FFDC7}
+		{E20FEEF9-1D1A-4CDA-A546-7FDC573BE399} = {245023D2-D3CA-47B9-831D-DAB91A2FFDC7}
+		{FD1AC230-798B-4AB9-8CE6-A06264885DBC} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A}
 	EndGlobalSection
 EndGlobal

docs/contribute/locally.md

@@ -44,11 +44,12 @@ This guide uses the first option. If you'd like to clone the repository and buil
 
 2. **Run docs-builder from a docs folder**
 
-   Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`:
+   Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000:
 
    ```sh
    docs-builder serve
    ```
+   The path to the `docset.yml` file that you want to build can be specified with `-p`.
 
 To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub. 
 
@@ -72,12 +73,12 @@ If you get a `Permission denied` error, make sure that you aren't trying to run
 
 2. **Run docs-builder from a docs folder**
 
-   Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`:
+   Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000:
 
    ```sh
    docs-builder serve
    ```
-   
+   The path to the `docset.yml` file that you want to build can be specified with `-p`.
 :::
 ::::
 
@@ -111,7 +112,7 @@ cd docs-content
 
 :::::{step} Run docs-builder
 
-Run the `docs-builder` binary with the `serve` command to build and serve the content set to http://localhost:3000. Specify the path to the `docset.yml` file that you want to build with `-p`.
+Run the `docs-builder` binary with the `serve` command to build and serve the content set to http://localhost:3000. If necessary, specify the path to the `docset.yml` file that you want to build with `-p`.
 
 For example: