Skip to content

docs: cleanup Confluence-export link debris + add confluence-html-link lint rule#55

Merged
jduval23 merged 1 commit into
rokudev:v2.0from
bblietz:fix/confluence-export-links
May 20, 2026
Merged

docs: cleanup Confluence-export link debris + add confluence-html-link lint rule#55
jduval23 merged 1 commit into
rokudev:v2.0from
bblietz:fix/confluence-export-links

Conversation

@bblietz
Copy link
Copy Markdown

@bblietz bblietz commented May 20, 2026

Summary

Audit step 4 partial: kills the 11 known <Name>_<digits>.html Confluence-export link artifacts left over from the original Confluence-to-Markdown migration. Each was repointed at the current in-repo doc that supersedes the dead Confluence page.

The audit called these "not aliasable" but the human-readable filename prefix maps every target unambiguously to a file that exists in the repo today.

Link rewrites (3 files / 11 edits)

File Line Was Now
DEVELOPER/core-concepts/xml-components/component-initialization-order.md 18 children_1608551.html /docs/references/scenegraph/xml-elements/children.md
same 23 interface_1608549.html /docs/references/scenegraph/xml-elements/interface.md
same 28 script_1608550.html /docs/references/scenegraph/xml-elements/script.md
same 58 PosterGrid_1607203.html /docs/references/scenegraph/list-and-grid-nodes/postergrid.md
same 66 Remote-Control-Events_1607636.html ../scenegraph-xml/remote-control-events.md
same 67 Scene_1607315.html /docs/references/scenegraph/scene.md
DEVELOPER/core-concepts/xml-components/scenegraph-compilation.md 24 component_1608292.html /docs/references/scenegraph/xml-elements/component.md
same 31 Scene_1607315.html /docs/references/scenegraph/scene.md
same 32 OverhangPanelSetScene_1613108.html /docs/references/scenegraph/sliding-panels-nodes/overhangpanelsetscene.md
same 34 Component-Initialization-Order_1611697.html component-initialization-order.md (sibling file)
REFERENCES/brightscript/interfaces/ifpath.md 74 https://sdkdocs-archive.staging.web.roku.com/roAssociativeArray_1611481.html /docs/references/brightscript/components/roassociativearray.md

Path-convention notes

9 of 11 use lowercase absolute paths (/docs/references/...) matching the proven-working pattern: all 226 working in-repo absolute links in the repo today use the lowercase form, and the renderer resolves them case-insensitively to the uppercase docs/REFERENCES/ filesystem.

2 use relative paths (the Remote Control Events and Component Initialization Order references): both source files are under docs/DEVELOPER/core-concepts/, and there are zero working /docs/developer/... precedents in the repo, so a sibling-relative path is the safer choice. Filesystem resolution confirmed for both.

New lint rule

.github/scripts/docs-lint/rules/links.mjs

Rule id: confluence-html-link (error)

Catches:

  • Relative or absolute link targets matching <Name>_<digits>.html (anywhere in the URL path)
  • External URLs to sdkdocs-archive.staging.web.roku.com/

Wired into index.mjs RULES array. Lint baseline preserved (same 3 pre-existing ifscreen.md findings as before; ZERO new errors after the sweep).

Test plan

  • node .github/scripts/docs-lint/index.mjs -> 0 confluence-html-link errors after sweep
  • All 11 rewrite targets verified to exist in the repo today (mapping confidence HIGH for every one; ambiguous case for "Remote Control Events" resolved by reading the surrounding context, which is about the focus chain and event flow -- not the onKeyEvent() API)
  • Lint baseline preserved (3 pre-existing findings in ifscreen.md unchanged)
  • CI run on this PR

Out of scope (deferred to follow-up PRs of audit step 4)

  • 151 broken-prefix in-repo absolute links (/docs/developer-program/ 112, /dev/docs/ 19, /docs/specs/ 17, /docs/references/ 2, /trc-docs/ 1)
  • 8 anchor mismatches in DEVELOPER/release-notes/index.md
  • 55 unique dead/errored external URLs identified by HTTP HEAD pass
  • 5 misc broken relative paths
  • 2,855 doc:slug ReadMe-legacy links (separate Tier-2 future migration)

Related

Part of the May 16 audit cleanup plan (dev-doc-review-report-2026-05-16.md step 4 -- broken-link sweep). Step 1 (Quick Wins) is in flight as PR #52. Step 2 (BrightScript fence sweep + lint rule) is in flight as PR #54.

…k lint rule

Audit step 4 partial: kills the 11 known `<Name>_<digits>.html`
Confluence-export link artifacts left over from the original
Confluence-to-Markdown migration. Each was repointed at the current
in-repo doc that supersedes the dead Confluence page. The audit called
these "not aliasable" but the human-readable filename prefix maps every
target unambiguously.

Link rewrites (3 files / 11 edits):

docs/DEVELOPER/core-concepts/xml-components/component-initialization-order.md
  L18  children_1608551.html
       -> /docs/references/scenegraph/xml-elements/children.md
  L23  interface_1608549.html
       -> /docs/references/scenegraph/xml-elements/interface.md
  L28  script_1608550.html
       -> /docs/references/scenegraph/xml-elements/script.md
  L58  PosterGrid_1607203.html
       -> /docs/references/scenegraph/list-and-grid-nodes/postergrid.md
  L66  Remote-Control-Events_1607636.html
       -> ../scenegraph-xml/remote-control-events.md
  L67  Scene_1607315.html
       -> /docs/references/scenegraph/scene.md

docs/DEVELOPER/core-concepts/xml-components/scenegraph-compilation.md
  L24  component_1608292.html
       -> /docs/references/scenegraph/xml-elements/component.md
  L31  Scene_1607315.html
       -> /docs/references/scenegraph/scene.md
  L32  OverhangPanelSetScene_1613108.html
       -> /docs/references/scenegraph/sliding-panels-nodes/overhangpanelsetscene.md
  L34  Component-Initialization-Order_1611697.html
       -> component-initialization-order.md  (sibling file)

docs/REFERENCES/brightscript/interfaces/ifpath.md
  L74  https://sdkdocs-archive.staging.web.roku.com/roAssociativeArray_1611481.html
       -> /docs/references/brightscript/components/roassociativearray.md

Path-convention notes:
- 9 of 11 use lowercase absolute paths (`/docs/references/...`) matching
  the proven-working pattern: all 226 working in-repo absolute links in
  the repo today use the lowercase form, and the renderer resolves them
  case-insensitively to the uppercase `docs/REFERENCES/` filesystem.
- 2 use relative paths (the `Remote Control Events` and `Component
  Initialization Order` references): both source files are under
  `docs/DEVELOPER/core-concepts/`, and there are zero working
  `/docs/developer/...` precedents in the repo, so a sibling-relative
  path is the safer choice. Filesystem resolution confirmed for both.

New lint rule:
  .github/scripts/docs-lint/rules/links.mjs
  Rule id: `confluence-html-link`  (error)
  Catches:
    - Relative or absolute link targets matching `<Name>_<digits>.html`
    - External URLs to `sdkdocs-archive.staging.web.roku.com/`
  Wired into index.mjs RULES array.

Verification:
  $ node .github/scripts/docs-lint/index.mjs
  ...
  brightscript-fence-required:    0
  confluence-html-link:           0
  pipe-no-blank-above:            1  (pre-existing, ifscreen.md)
  html-blank-between-tags:        2  (pre-existing, ifscreen.md)

Out of scope (deferred to follow-up PRs of audit step 4):
- 151 broken-prefix in-repo absolute links (`/docs/developer-program/`,
  `/dev/docs/`, `/docs/specs/`, `/docs/references/`, `/trc-docs/`)
- 8 anchor mismatches in DEVELOPER/release-notes/index.md
- 55 unique dead/errored external URLs identified by HTTP HEAD pass
- 5 misc broken relative paths
- 2,855 doc:slug ReadMe-legacy links (Tier-2 future migration)
@jduval23 jduval23 marked this pull request as ready for review May 20, 2026 20:58
@jduval23 jduval23 merged commit 80a3008 into rokudev:v2.0 May 20, 2026
1 check failed
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.

2 participants