Include code examples and images from QuestPDF.DocumentationExamples

.github/workflows/update-examples.yml

@@ -0,0 +1,63 @@
+name: Update examples
+
+# Exports the code examples and images from QuestPDF.DocumentationExamples (QuestPDF repository)
+# into docs/snippets and docs/public, and commits the changes to the branch it runs on.
+
+on:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      questpdf-ref:
+        description: QuestPDF branch or tag to take the examples from
+        required: true
+        default: main
+
+permissions: {}
+
+env:
+  QUESTPDF_REF: ${{ inputs.questpdf-ref || 'docs-examples/snippet-export' }}
+
+jobs:
+  update:
+    name: Update examples
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout documentation
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref || github.ref_name }}
+
+      - name: Checkout QuestPDF
+        uses: actions/checkout@v4
+        with:
+          repository: QuestPDF/QuestPDF
+          ref: ${{ env.QUESTPDF_REF }}
+          path: .questpdf
+          sparse-checkout: src/dotnet/library
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Export examples
+        run: dotnet run .questpdf/src/dotnet/library/tools/export-documentation-snippets.cs -- docs
+
+      - name: Commit changes
+        run: |
+          git add docs/snippets docs/public
+
+          if git diff --cached --quiet; then
+            echo "The examples are up to date."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "Update examples from QuestPDF $QUESTPDF_REF ($(git -C .questpdf rev-parse --short HEAD))"
+          git push

docs/.vitepress/theme/VitepressAdjustments.css

@@ -118,15 +118,18 @@ body {
     }
 }
 
-html:not(.dark) .VPDoc img[alt=example] {
+html:not(.dark) .VPDoc img[alt=example],
+html:not(.dark) .VPDoc img.example {
     border: 1px solid #888;
 }
 
-html.dark .VPDoc img[alt=example] {
+html.dark .VPDoc img[alt=example],
+html.dark .VPDoc img.example {
     opacity: 0.75;
 }
 
-.VPDoc img[alt=example] {
+.VPDoc img[alt=example],
+.VPDoc img.example {
     box-shadow: 0 13px 27px -5px rgb(50 50 93 / 15%), 0 8px 16px -8px rgb(0 0 0 / 10%), 0 -6px 16px -6px rgb(0 0 0 / 5%);
     margin-bottom: 16px;
     border-radius: 8px;

docs/api-reference/background.md

@@ -18,41 +18,9 @@ Sets a solid background color behind its content.
 .Background(Colors.Green.Lighten2)
 ```
 
-```csharp{30}
-using QuestPDF.Helpers;
-
-var colors = new[]
-{
-    Colors.LightBlue.Darken4,
-    Colors.LightBlue.Darken3,
-    Colors.LightBlue.Darken2,
-    Colors.LightBlue.Darken1,
-
-    Colors.LightBlue.Medium,
-
-    Colors.LightBlue.Lighten1,
-    Colors.LightBlue.Lighten2,
-    Colors.LightBlue.Lighten3,
-    Colors.LightBlue.Lighten4,
-    Colors.LightBlue.Lighten5,
-
-    Colors.LightBlue.Accent1,
-    Colors.LightBlue.Accent2,
-    Colors.LightBlue.Accent3,
-    Colors.LightBlue.Accent4,
-};
-
-container
-    .Height(150)
-    .Width(420)
-    .Row(row =>
-    {
-        foreach (var color in colors)
-            row.RelativeItem().Background(color);
-    });
-```
+<<< @/snippets/background/solid.cs{28 csharp}
 
-![example](/api-reference/background-solid.webp)
+![Fourteen equal-width stripes, each filled edge to edge with one shade of the LightBlue palette: from dark to light (Darken4 to Lighten5), then the four Accent shades.](/api-reference/background-solid.webp){.example}
 
 
 ## Gradient
@@ -61,26 +29,9 @@ Applies a linear gradient background to the container with the specified angle a
 
 The first argument is the angle in degrees, and the second argument is an array of colors that define the gradient.
 
-```csharp{6,10,14}
-.Column(column =>
-{
-    column.Spacing(25);
-
-    column.Item()
-        .BackgroundLinearGradient(0, [Colors.Red.Lighten2, Colors.Blue.Lighten2])
-        .AspectRatio(2);
-
-    column.Item()
-        .BackgroundLinearGradient(45, [Colors.Green.Lighten2, Colors.LightGreen.Lighten2, Colors.Yellow.Lighten2])
-        .AspectRatio(2);
-
-    column.Item()
-        .BackgroundLinearGradient(90, [Colors.Yellow.Lighten2, Colors.Amber.Lighten2, Colors.Orange.Lighten2])
-        .AspectRatio(2);
-});
-```
+<<< @/snippets/background/gradient.cs{6,10,14 csharp}
 
-![example](/api-reference/background-gradient.webp)
+![Three gradients showing the angle convention: 0° runs from left (red) to right (blue), 45° from the top-left corner (green) to the bottom-right corner (yellow), and 90° from top (yellow) to bottom (orange).](/api-reference/background-gradient.webp){.example}
 
 
 ## Rounded Corners
@@ -91,12 +42,6 @@ Sets the corner radius for the background, creating rounded corners.
 Read more about [rounded corners](/api-reference/rounded-corners.md).
 :::
 
-```csharp{2-3}
-container
-    .Background(Colors.Grey.Lighten2)
-    .CornerRadius(25)
-    .Padding(25)
-    .Text("Content with rounded corners");
-```
+<<< @/snippets/background/rounded-corners.cs{3-4 csharp}
 
-![example](/api-reference/background-rounded-corners.webp)
+![The grey background follows the rounded corners, and the box is only as wide as its padded text.](/api-reference/background-rounded-corners.webp){.example}