Merge branch 'main' into feature/extensionless-urls

Author: reakaleek

.github/workflows/preview-build.yml

@@ -13,15 +13,29 @@ on:
         type: string
         required: false
         default: 'true'
+      path-pattern:
+        description: 'Path pattern to filter files. Only if changed files match the pattern, the workflow will continue.'
+        type: string
+        default: '**'
+        required: false
 
 permissions: 
   contents: read
+  pull-requests: read
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
+
+      - name: Get changed files
+        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'
         uses: actions/checkout@v4
         with: 
           persist-credentials: false
@@ -30,11 +44,13 @@ jobs:
         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
           {
             "number": ${PR_NUMBER},
-            "ref": "${PR_REF}"
+            "ref": "${PR_REF}",
+            "any_changed": ${ANY_CHANGED}
           }
           EOF
       
@@ -48,26 +64,28 @@ jobs:
           compression-level: 1
 
       - name: Bootstrap Action Workspace
-        if: github.repository == 'elastic/docs-builder'
+        if: github.repository == 'elastic/docs-builder' && steps.check-files.outputs.any_changed == 'true'
         uses: ./.github/actions/bootstrap
 
       # 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'
+        if: github.repository == 'elastic/docs-builder' && steps.check-files.outputs.any_changed == 'true'
         env:
           PR_NUMBER: ${{ github.event.pull_request.number }}
         run: |
           dotnet run --project src/docs-builder -- --strict --path-prefix "/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}"
 
       - name: Build documentation
-        if: github.repository != 'elastic/docs-builder'
+        if: github.repository != 'elastic/docs-builder' && steps.check-files.outputs.any_changed == '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 }}"
           strict: ${{ fromJSON(inputs.strict != '' && inputs.strict || 'true') }}
+
       - uses: actions/upload-artifact@v4
+        if: steps.check-files.outputs.any_changed == 'true'
         with:
           name: docs
           path: .artifacts/docs/html/

.github/workflows/preview-cleanup.yml

@@ -14,15 +14,9 @@ jobs:
   destroy:
     runs-on: ubuntu-latest
     steps:
-      - uses: elastic/docs-builder/.github/actions/aws-auth@main
-      - name: Delete s3 objects
-        env:
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        run: |
-            aws s3 rm "s3://elastic-docs-v3-website-preview/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}" --recursive
-
       - name: Delete GitHub environment
         uses: actions/github-script@v7
+        id: delete-deployment
         with:
           script: |
             const { owner, repo } = context.repo;
@@ -31,6 +25,7 @@ jobs:
               repo,
               environment: `docs-preview-${context.issue.number}`
             });
+            core.setOutput('is-empty', deployments.data.length === 0)
             for (const deployment of deployments.data) {
               await github.rest.repos.createDeploymentStatus({
                 owner,
@@ -45,3 +40,13 @@ jobs:
                 deployment_id: deployment.id
               });
             }
+
+      - uses: elastic/docs-builder/.github/actions/aws-auth@main
+        if: steps.delete-deployment.outputs.is-empty == 'false'
+
+      - name: Delete s3 objects
+        if: steps.delete-deployment.outputs.is-empty == 'false'
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          aws s3 rm "s3://elastic-docs-v3-website-preview/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}" --recursive

.github/workflows/preview-deploy.yml

@@ -14,8 +14,13 @@ permissions:
   actions: read
 
 jobs:
-  docs-deploy:
+  pull-request-data:
+    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 }}
     steps:
       - name: Download PR data
         env:
@@ -30,14 +35,23 @@ jobs:
           {
             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)"
           } >> "${GITHUB_OUTPUT}"
-
+    
+  deploy:
+    needs: pull-request-data
+    if: needs.pull-request-data.outputs.any_changed == 'true'
+    runs-on: ubuntu-latest
+    concurrency: 
+      group: ${{ github.workflow }}-${{ needs.pull-request-data.outputs.number }}
+      cancel-in-progress: true
+    steps:
       - name: Create Deployment
         uses: actions/github-script@v7
         id: deployment
         env:
-          PR_NUMBER: ${{ steps.pull_request.outputs.number }}
-          PR_REF: ${{ steps.pull_request.outputs.ref }}
+          PR_NUMBER: ${{ needs.pull-request-data.outputs.number }}
+          PR_REF: ${{ needs.pull-request-data.outputs.ref }}
         with:
           result-encoding: string
           script: |
@@ -72,21 +86,23 @@ jobs:
 
       - name: Upload to S3
         env:
-          PR_NUMBER: ${{ steps.pull_request.outputs.number }}
+          PR_NUMBER: ${{ needs.pull-request-data.outputs.number }}
         run: |
           aws s3 sync ./html "s3://elastic-docs-v3-website-preview/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}" --delete
           aws cloudfront create-invalidation --distribution-id EKT7LT5PM8RKS --paths "/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}/*"
 
       - name: Update deployment status
         uses: actions/github-script@v7
         if: always() && steps.deployment.outputs.result
+        env:
+          PR_NUMBER: ${{ needs.pull-request-data.outputs.number }}
         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/${{ steps.pull_request.outputs.number}}`,
+              environment_url: `https://docs-v3-preview.elastic.dev/${context.repo.owner}/${context.repo.repo}/pull/${process.env.PR_NUMBER}`,
               log_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
             })

docs/contribute/move.md

@@ -0,0 +1,31 @@
+# Move files and folders
+
+When you move a source file or folder, you must also update all inbound and outbound links to reflect the new file location. `docs-builder` provides tooling to handle this step for you.
+
+## `docs-builder mv`
+
+Move a file or folder from one location to another and update all links in the documentation. For example:
+
+```
+docs-builder mv ./old-location/ia.md ./new-location/ia.md
+```
+
+:::{important}
+The `docset.yml` and `toc.yml` files are not automatically updated when using this tool. You must update these references manually.
+:::
+
+## `docs-builder mv --help`
+
+```
+Usage: mv [arguments...] [options...] [-h|--help] [--version]
+
+Move a file or folder from one location to another and update all links in the documentation
+
+Arguments:
+  [0] <string?>    The source file or folder path to move from
+  [1] <string?>    The target file or folder path to move to
+
+Options:
+  --dry-run <bool?>      Dry run the move operation (Default: null)
+  -p|--path <string?>    Defaults to the`{pwd}` folder (Default: null)
+```

docs/docset.yml

@@ -18,6 +18,8 @@ external_hosts:
   - google.com
   - checkvist.com
   - commonmark.org
+  - github.io
+  - github.com
 exclude:
   - '_*.md'
 subs:
@@ -30,6 +32,7 @@ toc:
       - file: index.md
       - file: locally.md
       - file: on-the-web.md
+      - file: move.md
   - folder: migration
     children:
       - file: index.md
@@ -44,11 +47,11 @@ toc:
       - folder: guide
         children:
           - file: index.md
+          - file: working-in-docs-content.md
           - file: automated.md
           - file: tooling.md
-          - file: bug-bash.md
-          - file: file-structure.md
           - file: mapping.md
+          - file: how-to-set-up-docs-previews.md
   - folder: configure
     children:
       - file: index.md
@@ -68,10 +71,11 @@ toc:
   - folder: syntax
     children:
       - file: index.md
-      - file: md-extensions.md
       - file: admonitions.md
+      - file: applies.md
       - file: automated_settings.md
       - file: code.md
+      - file: comments.md
       - file: conditionals.md
       - file: dropdowns.md
       - file: example_blocks.md
@@ -81,7 +85,6 @@ toc:
       - file: line_breaks.md
       - file: links.md
       - file: passthrough.md
-      - file: applies.md
       - file: sidebars.md
       - file: substitutions.md
       - file: sundries.md

docs/migration/engineering.md

@@ -1,4 +1,4 @@
-# Reference docs guidelines
+# New reference guidelines
 
 ## Engineering ownership of reference documentation
 

docs/migration/guide/automated.md

@@ -1,4 +1,4 @@
-# Migrate Automated Content to V3
+# Migrate automated docs
 
 If you have automated documentation in Asciidoc (or any other format) that you need to migrate to Elastic docs V3, this guide walks you through the essentials. Elastic docs V3 (powered by `docs-builder`) allows engineering teams to keep code and reference docs closely integrated for easier updates and greater accuracy.
 
@@ -15,8 +15,8 @@ Once you have these files, follow the [Contribute Locally guide](../../contribut
 
 Elastic docs V3 fully supports [CommonMark](https://commonmark.org/) Markdown syntax. In addition, we support:
 
-* Custom directives — our main extension point over markdown (learn more [here](../../syntax/md-extensions.md#directives))
-* A few GitHub flavored markdown extensions (see the list [here](../../syntax/md-extensions.md#github-flavored-markdown))
+* Custom directives — our main extension point over markdown (learn more [here](../../syntax/index.md))
+* A few GitHub flavored markdown extensions (see the list [here](../../syntax/index.md))
 
 In most cases, plain Markdown covers basic needs, and directives add extra functionality as needed.
 
@@ -43,4 +43,4 @@ For more information, see [Navigation](../../configure/content-set/navigation.md
 
 ## Next steps
 
-That’s all you need to get started migrating automated docs to V3. As you add more pages or custom features, refer to the linked resources for details on configuring your docset, refining navigation, and leveraging the full power of V3 directives.
+That’s all you need to get started migrating automated docs to V3. As you add more pages or custom features, refer to the linked resources for details on configuring your docset, refining navigation, and leveraging the full power of V3 directives.