Skip to content

docs(sdk): link the TypeScript README by URL, not as a docs page - #752

Closed
thread3d wants to merge 1 commit into
NandhaKishorM:mainfrom
thread3d:docs/sdk-readme-url
Closed

thread3d wants to merge 1 commit into
NandhaKishorM:mainfrom
thread3d:docs/sdk-readme-url

Conversation

@thread3d

Copy link
Copy Markdown
Contributor

What

docs/typescript-sdk.md links the TypeScript SDK README as ../sdk/typescript/README.md. This
makes it an absolute GitHub URL instead.

Why

sdk/typescript/README.md is a Markdown file outside docs/, so zensical build --strict
tries to resolve it as a page and fails:

Warning: page does not exist
    ╭─[ typescript-sdk.md:67:21 ]
 67 │ See the [SDK guide](../sdk/typescript/README.md) for setup, examples, and npm
1 issue found

That makes the Docs workflow red on main (run 36606632973).

The docs workflow already states the rule in its own comment -- "Use absolute GitHub URLs for
files outside docs/ so links work when pages in docs/ are read on GitHub or on the site"
-- and
every other such link in docs/ follows it (BENCHMARKS.md, research/README.md, the notebook,
examples/docker/request.json, and 35 more). This was the only exception.

How it was verified

pip install -r requirements-docs.txt
zensical build --strict --clean
# Build started
# No issues found
# Build finished in 3.35s
# (no `griffe:` lines in the output)

ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120
# All checks passed!

python tests/test_packaging.py        # all packaging tests passed
python tests/test_structured_docs.py  # 87 checks passed, 0 failed
python tests/test_doc_tables.py       # passes
python tests/test_env_docs.py         # passes

Checklist

  • Focused on one change (split unrelated work into another PR)
  • Rebased on the latest main (branched from 6d942c9; the diff is this one file)
  • Tests pass locally
  • Docs or examples updated when the public API changed

`docs/typescript-sdk.md` linked `../sdk/typescript/README.md`, a Markdown file
outside `docs/`, so `zensical build --strict` fails with "page does not exist"
and the Docs workflow goes red. The failure is inherited from upstream 6d942c9
-- NandhaKishorM/laya's own Docs run fails on the identical link -- and the docs
workflow's own comment says to use absolute GitHub URLs for files outside
`docs/`, which every other such link already does.

Verified: `zensical build --strict --clean` reports "No issues found" with zero
`griffe:` lines; ruff, test_packaging, test_structured_docs, test_doc_tables and
test_env_docs still pass.

@Bruce-Yii Bruce-Yii left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This and #742 are the same change, and as things stand they will conflict. One of the two needs to close.

Both branch from the same commit as main and touch only docs/typescript-sdk.md:67. I compared the resulting file at each head rather than eyeballing the diffs:

  • resulting file size: 3444 bytes at your head, 3444 bytes at #742's
  • whitespace-normalized content: identical
  • the only difference is line wrapping

Same hunk, same base, different wrapping means whichever lands second gets a conflict rather than a clean no-op. Worth settling before either is merged rather than after.

The one thing that actually differs is line width. Longest line in the file:

longest line
main 104
this PR 104 (unchanged)
#742 122

So your rewrap introduces no line longer than main already has, while #742's one-line version pushes the file's worst line from 104 to 122 (+17%). That is the only substantive argument between them, and it cuts your way. Against it: #742 is the smaller diff (one line versus three) and already carries an approval, so it is the lower-friction merge. Genuinely close — the call is yours, but neither fact should need reconstructing to make it.

One clarification, since an absolute URL reads like a shortcut around the checker: it is what .github/workflows/docs.yml already prescribes. The build step is annotated "Use absolute GitHub URLs for files outside docs/ so links work when pages in docs/ are read on GitHub or on the site." And no relative path can work here — the site is built from docs/ only, and sdk/typescript/README.md sits outside it, so ../sdk/typescript/README.md has no target inside the build. Making it relative would mean moving or duplicating the SDK README into the docs tree, which is a far larger change than either of us is proposing. So this is a duplicate-ownership question, not a correctness one; both approaches are right.

Whichever you keep, closing the other unblocks every open PR currently sitting behind docs (strict build).

@thread3d

Copy link
Copy Markdown
Contributor Author

Closing in favour of #742, which was opened first (00:41Z against 07:18Z here) and already carries your approval. Normalising whitespace, the two heads are the same file, so there is nothing here worth a conflict.

For the record, the line-width point is the weaker of the two: 122 characters is unremarkable across docs/ (docs/cli-mcp.md runs to 360, docs/langchain.md to 350, docs/index.md to 253) and nothing in the build lints line width. A one-line diff is the better shape for a link fix.

Thanks for comparing the two heads instead of the two diffs — that is what made this decidable rather than a coin toss.

@thread3d thread3d closed this Sep 30, 2026
@thread3d
thread3d deleted the docs/sdk-readme-url branch September 30, 2026 12:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants