fix(docs): sanitize emoji shortcodes in generated SDK docs by devin-ai-integration[bot] · Pull Request #780 · OpenRouterTeam/typescript-sdk

devin-ai-integration · 2026-08-10T20:50:19Z

Summary

The Parameters tables on openrouter.ai/docs/client-sdks/typescript/** render :heavy_check_mark: as literal text. Speakeasy emits GitHub-flavored emoji shortcodes; GitHub expands them, Mintlify does not, and the docs site mounts this repo's docs/ tree directly through a sourceRef entry in openrouter-web's projects/docs/docs.json.

Editing the generated MDX alone would not hold, because the next speakeasy run rewrites it. So this PR pairs a one-time pass with a post-generation step:

scripts/sanitize-docs-emoji.sh rewrites docs/**/*.mdx in place:
```
:heavy_check_mark: -> ✅
:heavy_minus_sign: -> ➖
:warning:          -> ⚠️
```
Scoped to docs/ only. Root README.md and the workflow YAML keep their shortcodes, which render correctly on GitHub and npm.
The script runs immediately after speakeasy run and before gen-docs-nav.sh in speakeasy_run_on_pr.yaml, so spec-change PRs land sanitized.
A new docs-nav.yaml mirrors the workflow python-sdk and go-sdk already have. This repo had no pull_request-triggered docs job, so the scheduled generation path in sdk_generation.yaml opens PRs that neither sanitize emoji nor regenerate navigation. The new workflow covers both on that path.
docs-nav.yaml and speakeasy_run_on_pr.yaml share one concurrency group keyed on the PR number, with cancel-in-progress: false. Both end with int128/update-generated-files-action@v2 pushing to the PR head branch, and a Speakeasy regeneration PR touches both .speakeasy/in.openapi.yaml and docs/**, so without serialization the second push would be rejected as non-fast-forward.
The one-time pass: 1,428 files, 6,933 shortcodes replaced (rebased onto main on 2026-10-03).
scripts/sanitize-docs-emoji.sh ends with a residual guard: if any standalone :[a-z][a-z0-9_+-]*: token (not preceded or followed by a word character or :) survives the substitution, it prints the file and line and exits non-zero, so a new shortcode Speakeasy starts emitting fails at generation time instead of shipping as literal text. Zero matches remain today, so the guard passes on current output.

Verification

Zero shortcode matches remain under docs/; the six :warning: occurrences in workflow YAML are untouched.
Re-running the script produces no diff.

Durability, now confirmed

Speakeasy regeneration PR #784 landed on main while this PR was open. It ran PR Validation, a plain pull_request workflow, which establishes that pull_request workflows do fire on the bot-authored regeneration PRs, so the sanitize step will run on future generations. auto-merge-speakeasy-pr.yaml waits for checks to complete before merging, so the sanitize commit has a window to land, but the poll can observe a momentarily-empty pending set between commits. That race predates this change and applies equally to gen-docs-nav.sh.

Rebase (2026-10-03)

Reopened after Pylon #4403 reported the same bug from a customer. The vendor's suggested script only rewrites description fields in OpenAPI files, and the spec has no shortcodes in it, so it doesn't fix this. The shortcodes come from Speakeasy's docs templates.

Rebuilt on current main: same .github and scripts changes, then the one-time pass was re-run fresh instead of replaying the old generated-docs commits.
The residual guard now ignores URN-style colon runs. New OAuth docs on main contain urn:ietf:params:oauth:token-type:jwt, which the old pattern flagged as :params: etc.:
```
- grep -HnE ':[a-z][a-z0-9_+-]*:'
+ grep -HnP '(?<![\w:]):[a-z][a-z0-9_+-]*:(?![\w:])'
```

Link to Devin session: https://openrouter.devinenterprise.com/sessions/1589ee9058c442958d427eac4e989f11
Open in Devin Desktop: https://openrouter.devinenterprise.com/desktop/session/1589ee9058c442958d427eac4e989f11?variant=devin

devin-ai-integration · 2026-08-10T20:50:20Z

Original prompt from jason.schrader

SYSTEM:
=== BEGIN THREAD HISTORY (in #gtm-agents) ===
<most_recent_message>
Jason Schrader (U0BLD9PFY30) [ts=1786394064.313869]: @Devin I found a few spots in our docs where emoji shortcodes are listed in text form and not displayed in tables, e.g. ✔️ renders as :heavy_check_mark: in the table instead of the actual icon. Let's identify the root cause then create a PR to get it all fixed up. From what I see, it's all under a table in the "Parameters" section of the different Client SDK files.
<https://openrouter.ai/docs/client-sdks/typescript/sdks/files/README|openrouter.ai/docs/…/README>
<https://openrouter.ai/docs/client-sdks/python/sdks/benchmarks/README|openrouter.ai/docs/…/README>
<https://openrouter.ai/docs/client-sdks/go/sdks/betaanalytics/README|openrouter.ai/docs/…/README>
</most_recent_message>
=== END THREAD HISTORY ===
Channel ID: C0AD8UNM761
Thread URL: https://openrouter.slack.com/archives/C0AD8UNM761/p1786394064313869?thread_ts=1786394064.313869&cid=C0AD8UNM761

The latest message is the one right above that tagged you. The <most_recent_message> is the message that you should use to guide your goals + task for this session, and you should use the rest of the slack thread as context.
A [ts=...] marker on a Slack message is that message's timestamp. To act on a specific message with the slack tool (e.g. adding an emoji reaction via the reaction command), pass that value as timestamp along with the Channel ID — no extra lookup call is needed.

devin-ai-integration · 2026-08-10T20:50:21Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR that start with 'DevinAI' or '@devin'.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment, CI, and merge conflict monitoring

mintlify · 2026-08-10T21:24:44Z