Merge branch 'main' into feature/extensionless-urls

Author: reakaleek

.github/workflows/preview-build.yml

@@ -6,13 +6,13 @@ on:
     inputs:
       strict:
         description: 'Treat warnings as errors'
-        type: boolean
-        default: true
+        type: string
+        default: 'true'
       continue-on-error:
         description: 'Do not fail to publish if build fails'
-        type: boolean
+        type: string
         required: false
-        default: true
+        default: 'true'
 
 permissions: 
   contents: read
@@ -23,6 +23,29 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with: 
+          persist-credentials: false
+          
+      - name: Store PR data
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_REF: ${{ github.event.pull_request.head.sha }}
+        run: |
+          cat << EOF > pull_request.json
+          {
+            "number": ${PR_NUMBER},
+            "ref": "${PR_REF}"
+          }
+          EOF
+      
+      - name: Upload PR data
+        uses: actions/upload-artifact@v4
+        with:
+          name: pull-request-data
+          path: pull_request.json
+          if-no-files-found: error
+          retention-days: 1
+          compression-level: 1
 
       - name: Bootstrap Action Workspace
         if: github.repository == 'elastic/docs-builder'
@@ -40,18 +63,16 @@ jobs:
       - name: Build documentation
         if: github.repository != 'elastic/docs-builder'
         uses: elastic/docs-builder@main
-        continue-on-error: true
+        continue-on-error: ${{ fromJSON(inputs.continue-on-error != '' && inputs.continue-on-error || 'false') }}
         with:
           prefix: "/${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
-          strict: true
-      - name: Add pull request number to build
-        env:
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          PR_REF: ${{ github.event.pull_request.head.sha }}
-        run: |
-          echo "${PR_NUMBER}" >> .artifacts/docs/html/pull_request_number.txt
-          echo "${PR_REF}" >> .artifacts/docs/html/pull_request_ref.txt
+          strict: ${{ fromJSON(inputs.strict != '' && inputs.strict || 'true') }}
       - uses: actions/upload-artifact@v4
         with:
           name: docs
           path: .artifacts/docs/html/
+          if-no-files-found: error
+          retention-days: 1
+          # The lower the compression-level, the faster the artifact will be uploaded.
+          # But the size of the artifact will be larger.
+          compression-level: 1

.github/workflows/preview-deploy.yml

@@ -17,16 +17,20 @@ jobs:
   docs-deploy:
     runs-on: ubuntu-latest
     steps:
-      - name: Download docs
+      - name: Download PR data
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh run download ${{ github.event.workflow_run.id }} --name docs --repo "${GITHUB_REPOSITORY}"
+          gh run download ${{ github.event.workflow_run.id }} \
+            --repo "${GITHUB_REPOSITORY}" \
+            --name pull-request-data
       - name: Get PR data
         id: pull_request
         run: |
-          echo "number=$(cat pull_request_number.txt)" >> "${GITHUB_OUTPUT}"
-          echo "ref=$(cat pull_request_ref.txt)" >> "${GITHUB_OUTPUT}"
+          {
+            echo "number=$(jq -r '.number' pull_request.json)"
+            echo "ref=$(jq -r '.ref' pull_request.json)"
+          } >> "${GITHUB_OUTPUT}"
 
       - name: Create Deployment
         uses: actions/github-script@v7
@@ -54,14 +58,23 @@ jobs:
                 log_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
             })
             return deployment.data.id
+            
+      - name: Download docs
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh run download ${{ github.event.workflow_run.id }} \
+            --repo "${GITHUB_REPOSITORY}" \
+            --name docs \
+            --dir html
 
       - uses: elastic/docs-builder/.github/actions/aws-auth@main
 
       - name: Upload to S3
         env:
           PR_NUMBER: ${{ steps.pull_request.outputs.number }}
         run: |
-          aws s3 sync . "s3://elastic-docs-v3-website-preview/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}" --delete --exclude "pull_request_number.txt"
+          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

docs/syntax/images.md

@@ -39,10 +39,49 @@ Or, use the `image` directive.
 ## Inline images
 
 ```markdown
-Here is the same image used inline ![Elasticsearch](img/observability.png)
+Here is the same image used inline ![Elasticsearch](img/observability.png "elasticsearch =50%x50%")
 ```
 
-Here is the same image used inline ![Elasticsearch](img/observability.png)
+Here is the same image used inline ![Elasticsearch](img/observability.png "elasticsearch =50%x50%")
+
+
+### Inline image titles
+
+Titles are optional making this the minimal syntax required
+
+```markdown
+![Elasticsearch](img/observability.png)
+```
+
+Including a title can be done by supplying it as an optional argument.
+
+```markdown
+![Elasticsearch](img/observability.png "elasticsearch")
+```
+
+### Inline image sizing
+
+Inline images are supplied at the end through the title argument.
+
+This is done to maintain maximum compatibility with markdown parsers
+and previewers. 
+
+```markdown
+![alt](img.png "title =WxH")
+![alt](img.png "title =W")
+```
+
+`W` and `H` can be either an absolute number in pixels or a number followed by `%` to indicate relative sizing.
+
+If `H` is omitted `W` is used as the height as well.
+
+```markdown
+![alt](img.png "title =250x330")
+![alt](img.png "title =50%x40%")
+![alt](img.png "title =50%")
+```
+
+
 
 ### SVG 
 

src/Elastic.Markdown/Myst/InlineParsers/DiagnosticLinkInlineParser.cs

@@ -4,6 +4,7 @@
 
 using System.Collections.Immutable;
 using System.IO.Abstractions;
+using System.Text.RegularExpressions;
 using Elastic.Markdown.Diagnostics;
 using Elastic.Markdown.IO;
 using Elastic.Markdown.Myst.Comments;
@@ -12,6 +13,7 @@
 using Markdig.Parsers;
 using Markdig.Parsers.Inlines;
 using Markdig.Renderers;
+using Markdig.Renderers.Html;
 using Markdig.Syntax.Inlines;
 
 namespace Elastic.Markdown.Myst.InlineParsers;
@@ -33,6 +35,14 @@ public void Setup(MarkdownPipelineBuilder pipeline) =>
 	public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer) { }
 }
 
+internal partial class LinkRegexExtensions
+{
+
+	[GeneratedRegex(@"\s\=(?<width>\d+%?)(?:x(?<height>\d+%?))?$", RegexOptions.IgnoreCase, "en-US")]
+	public static partial Regex MatchTitleStylingInstructions();
+
+}
+
 public class DiagnosticLinkInlineParser : LinkInlineParser
 {
 	// See https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml for a list of URI schemes
@@ -41,6 +51,7 @@ public class DiagnosticLinkInlineParser : LinkInlineParser
 	public override bool Match(InlineProcessor processor, ref StringSlice slice)
 	{
 		var match = base.Match(processor, ref slice);
+
 		if (!match || processor.Inline is not LinkInline link)
 			return match;
 
@@ -49,9 +60,38 @@ public override bool Match(InlineProcessor processor, ref StringSlice slice)
 			return match;
 
 		ValidateAndProcessLink(processor, link, context);
+
+		ParseStylingInstructions(processor, link, context);
+
 		return match;
 	}
 
+
+	private void ParseStylingInstructions(InlineProcessor processor, LinkInline link, ParserContext context)
+	{
+		if (string.IsNullOrWhiteSpace(link.Title) || link.Title.IndexOf('=') < 0)
+			return;
+
+		var matches = LinkRegexExtensions.MatchTitleStylingInstructions().Match(link.Title);
+		if (!matches.Success)
+			return;
+
+		var width = matches.Groups["width"].Value;
+		if (!width.EndsWith("%"))
+			width += "px";
+		var height = matches.Groups["height"].Value;
+		if (string.IsNullOrEmpty(height))
+			height = width;
+		else if (!height.EndsWith("%"))
+			height += "px";
+		var title = link.Title[..matches.Index];
+
+		link.Title = title;
+		var attributes = link.GetAttributes();
+		attributes.AddProperty("width", width);
+		attributes.AddProperty("height", height);
+	}
+
 	private static bool IsInCommentBlock(LinkInline link) =>
 		link.Parent?.ParentBlock is CommentBlock;
 

tests/authoring/Inline/InlineImages.fs

@@ -28,3 +28,46 @@ type ``relative path to image`` () =
         markdown |> convertsToHtml """
             <p><img src="_static/img/observability.png" alt="Elasticsearch" /></p>
         """
+
+type ``supplying a tittle`` () =
+    static let markdown = Setup.Markdown """
+![Elasticsearch](_static/img/observability.png "Hello world")
+"""
+
+    [<Fact>]
+    let ``validate HTML: includes title`` () =
+        markdown |> convertsToHtml """
+            <p><img src="_static/img/observability.png" alt="Elasticsearch" title="Hello world" /></p>
+        """
+
+type ``supplying a tittle with width and height`` () =
+    static let markdown = Setup.Markdown """
+![o](obs.png "Title =250x400")
+"""
+
+    [<Fact>]
+    let ``validate HTML: does not include width and height in title`` () =
+        markdown |> convertsToHtml """
+            <p><img src="obs.png" width="250px" height="400px" alt="o" title="Title"/></p>
+        """
+
+type ``supplying a tittle with width and height in percentage`` () =
+    static let markdown = Setup.Markdown """
+![o](obs.png "Title =50%x40%")
+"""
+
+    [<Fact>]
+    let ``validate HTML: does not include width and height in title`` () =
+        markdown |> convertsToHtml """
+            <p><img src="obs.png" width="50%" height="40%" alt="o" title="Title"/></p>
+        """
+type ``supplying a tittle with width only`` () =
+    static let markdown = Setup.Markdown """
+![o](obs.png "Title =30%")
+"""
+
+    [<Fact>]
+    let ``validate HTML: sets height to width if not supplied`` () =
+        markdown |> convertsToHtml """
+            <p><img src="obs.png" width="30%" height="30%" alt="o" title="Title"/></p>
+        """