[1/2] fix: remove every dead link from the API reference

.github/workflows/ci.yml

@@ -88,6 +88,9 @@ jobs:
           CODE_SAMPLES_PHP_DIR: ${{ runner.temp }}/php
         run: node tests/reference-code-samples.cjs
 
+      - name: Check reference links
+        run: node tests/reference-links.cjs
+
       - name: Dry run release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

api.oas3.yaml

@@ -259,6 +259,12 @@ components:
     RichTextAnimation:
       $ref: "./schemas/richtextproperties.yaml#/RichTextAnimation"
 
+    RichTextBorder:
+      $ref: "./schemas/richtextproperties.yaml#/RichTextBorder"
+
+    RichTextPadding:
+      $ref: "./schemas/richtextproperties.yaml#/RichTextPadding"
+
     CaptionFont:
       $ref: "./schemas/captionproperties.yaml#/CaptionFont"
 

build-docs.sh

@@ -39,6 +39,9 @@ sed -i -e 's/\/edit\/{version}\/assets/\/serve\/{version}\/assets/g' .shins/sour
 sed -i -e 's/\/edit\/{version}\/sources/\/ingest\/{version}\/sources/g' .shins/source/index.html.md
 sed -i -e 's/\/edit\/{version}\/upload/\/ingest\/{version}\/upload/g' .shins/source/index.html.md
 
+# Base URLs hold a {version} placeholder, so they are shown as code rather than as links that can't open
+sed -i -e 's#<a href="\(https://api\.shotstack\.io/[a-z]*/{version}\)">\1</a>#`\1`#g' .shins/source/index.html.md
+
 # Build the Shins docs HTML
 cd .shins
 rm -f index.html

paths/assetsrenderid.yaml

@@ -8,7 +8,7 @@
                 $ref: "../schemas/responses/assetrenderresponse.yaml#/AssetRenderResponse"
       description: |
         A render may generate more than one file, such as a video, thumbnail and poster image. When the assets are
-        created the only known id is the render id returned by the original [render request](#render-video), status 
+        created the only known id is the render id returned by the original [render request](#render-asset), status 
         request or webhook. This endpoint lets you look up one or more assets by the render id.
 
         **Base URL:** <a href="#">https://api.shotstack.io/serve/{version}</a>

paths/render.yaml

@@ -18,7 +18,7 @@
 
         **Video Preprocessing:**
         Video assets undergo automatic preprocessing to ensure compatibility. You can force 
-        preprocessing by setting `"transcode": true` on video assets. See [Preprocessing](#preprocessing) 
+        preprocessing by setting `"transcode": true` on video assets. See [VideoAsset](#tocs_videoasset) 
         for more details.
 
         **Base URL:** <a href="#">https://api.shotstack.io/edit/{version}</a>

paths/upload.yaml

@@ -10,7 +10,7 @@
         Request a signed URL to upload a file to. The response returns a signed URL that you use to upload the file to.
         The signed URL looks similar to:
 
-        https://shotstack-ingest-api-stage-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV7UWDMGTZLHTXP&Expires=1677209777&Signature=PKR4dGDDdOuMTAQmDASzLGmLOeo%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEGMaDmFwLX......56osBGByztm7WZdbmXzO09KR
+        `https://shotstack-ingest-api-stage-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV7UWDMGTZLHTXP&Expires=1677209777&Signature=PKR4dGDDdOuMTAQmDASzLGmLOeo%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEGMaDmFwLX......56osBGByztm7WZdbmXzO09KR`
 
         In a separate API call, use this signed URL to send a PUT request with the binary file. Using  cURL you can use
         a command like:

schemas/destinations/akamaiNetStorageDestination.yaml

@@ -1,6 +1,6 @@
     AkamaiNetStorageDestination:
       description: >-
-        Send videos and assets to [Akamai NetStorage](https://techdocs.akamai.com/netstorage-usage/docs). Send files to
+        Send videos and assets to [Akamai NetStorage](https://techdocs.akamai.com/netstorage/docs). Send files to
         your NetStorage upload directory with a custom path and filename. Akamai credentials are required and added via the
         [dashboard](https://dashboard.shotstack.io/integrations/akamai-netstorage), not in the request.
       properties:

schemas/destinations/muxDestination.yaml

@@ -1,6 +1,6 @@
     MuxDestination:
       description: >-
-        Send videos to the [Mux](https://shotstack.io/docs/guide/serving-assets/destinations/mux/) video hosting
+        Send videos to the [Mux](https://www.mux.com/docs) video hosting
         and streaming service. Mux credentials are required and added via the
         [dashboard](https://dashboard.shotstack.io/integrations/mux), not in the request.
       properties:

schemas/edit.yaml

@@ -29,7 +29,7 @@
           description: |
             **Notice: This option is now deprecated and will be removed. Disk types are handled automatically. Setting a disk type has no effect.**
 
-            The disk type to use for storing footage and assets for each render. See [disk types](https://shotstack.io/docs/guide/architecting-an-application/disk-types/) for more details.
+            The disk type to use for storing footage and assets for each render.
             <ul>
               <li>`local` - optimized for high speed rendering with up to 512MB storage</li>
               <li>`mount` - optimized for larger file sizes and longer videos with 5GB for source footage and 512MB for output render</li>

tests/reference-links.cjs

@@ -0,0 +1,16 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Reads the reference produced by `pnpm build:docs`. Every in-page link must land on an element.
+const html = fs.readFileSync(path.resolve(__dirname, '..', 'build/docs/index.html'), 'utf8');
+const ids = new Set([...html.matchAll(/\sid="([^"]+)"/g)].map((match) => match[1]));
+const targets = [...new Set([...html.matchAll(/href="#([^"]+)"/g)].map((match) => decodeURIComponent(match[1])))];
+const dead = targets.filter((target) => !ids.has(target));
+
+// A URL with a `{placeholder}` in it (a base URL, a path template) can't be opened, so it's shown as text.
+const placeholders = [...new Set([...html.matchAll(/href="(https?:\/\/[^"]*(?:[{}]|%7B|%7D)[^"]*)"/gi)].map((match) => match[1]))];
+
+assert.equal(dead.length, 0, `links to missing sections: ${dead.map((target) => `#${target}`).join(', ')}`);
+assert.equal(placeholders.length, 0, `links to placeholder URLs: ${placeholders.join(', ')}`);
+console.log(`Reference links: all ${targets.length} in-page targets exist, and no link is a placeholder URL`);