fix(specs): no links across API specs (#3643)

Co-authored-by: Pierre Millot <[email protected]>
algolia · Sep 2, 2024 · e3af955 · e3af955
1 parent f8e08a6
commit e3af955
Show file tree

Hide file tree

Showing 4 changed files with 8 additions and 4 deletions.
diff --git a/scripts/cts/runCts.ts b/scripts/cts/runCts.ts
@@ -128,7 +128,8 @@ export async function runCts(
 ): Promise<void> {
   const withBenchmarkServer =
     suites.benchmark && (clients.includes('search') || clients.includes('all') || languages.includes('swift'));
-  const withClientServer = suites.client && (clients.includes('search') || clients.includes('all'));
+  const withClientServer =
+    suites.client && (clients.includes('search') || clients.includes('all') || process.platform === 'darwin'); // the macos swift CI also runs the clients tests
   const closeTestServer = await startTestServer({
     ...suites,
     benchmark: withBenchmarkServer,

diff --git a/specs/insights/paths/deleteUserToken.yml b/specs/insights/paths/deleteUserToken.yml
@@ -6,7 +6,7 @@ delete:
   description: |
     Deletes all events related to the specified user token from events metrics and analytics.
     The deletion is asynchronous, and processed within 48 hours.
-    To delete a personalization user profile, see [Delete a user profile](/specs/personalization#tag/profiles/operation/deleteUserProfile).
+    To delete a personalization user profile, see `Delete a user profile` in the Personalization API.
   parameters:
     - name: userToken
       in: path

diff --git a/specs/query-suggestions/paths/qsConfig.yml b/specs/query-suggestions/paths/qsConfig.yml
@@ -68,7 +68,7 @@ delete:
     Deletes a Query Suggestions configuration.
 
     Deleting only removes the configuration and stops updates to the Query Suggestions index.
-    To delete the Query Suggestions index itself, use the Search API and the [Delete an index](/specs/search#tag/Indices/operation/deleteIndex) operation.
+    To delete the Query Suggestions index itself, use the Search API and the `Delete an index` operation.
   parameters:
     - $ref: '../common/parameters.yml#/IndexName'
   responses:

diff --git a/website/docs/docs.md b/website/docs/docs.md
@@ -28,7 +28,10 @@ To make using the specs in these contexts easier, follow these guidelines:
 - Don't use headings, except in [API descriptions](#api-descriptions).
 - Prefer using `externalDocs` objects over inline Markdown links.
 - Use inline Markdown links judiciously.
-  Don't link to readily searchable information, such as internet RFCs or Wikipedia.
+  They don't render in CLI/code environments.
+
+  - Don't link to readily searchable information, such as internet RFCs or Wikipedia.
+  - Don't link to endpoints of other Algolia APIs. These links won't be portable.
 
 ### Markdown in long descriptions