تشغيل أي مهارة في Manus بنقرة واحدة

docs-link-audit

النجوم١٢

التفرعات٢

آخر تحديث١٥ مايو ٢٠٢٦ في ١٨:٤٣

Docs 사이트 (`site/` Next.js) 의 본문/JSX/markdown 링크 audit. broken 내부 링크 탐지, build-time copy 인지, 옵트인 HTTP probe. 신규 페이지 추가 / slug 이전 / chapter 삭제 후 회귀 방지. Triggered by "broken link", "404", "docs link", "hyperlink", "링크 점검", "링크 깨짐", "audit links", "link checker" 키워드.

التثبيت

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

تشغيل في Manus

المصدر

mangowhoiscloud

mangowhoiscloud/geode

فتح مستودع GitHub عرض مستودعات المنشئ

تنزيل

تشغيل في Manus

المهن ذات الصلةSOC

استنادا إلى تصنيف SOC المهني

مطوّرو الويبمهن الحاسوب والرياضيات·SOC 15-1254

SKILL.md

readonly

name	docs-link-audit
description	Docs 사이트 (`site/` Next.js) 의 본문/JSX/markdown 링크 audit. broken 내부 링크 탐지, build-time copy 인지, 옵트인 HTTP probe. 신규 페이지 추가 / slug 이전 / chapter 삭제 후 회귀 방지. Triggered by "broken link", "404", "docs link", "hyperlink", "링크 점검", "링크 깨짐", "audit links", "link checker" 키워드.
user-invocable	false

Docs Link Audit

site/ Next.js docs 사이트의 모든 본문 링크를 정적 + 옵션 HTTP 로 검사한다. scripts/check_docs_links.py 가 본 워크플로의 1차 도구.

언제 가동되는가

신규 페이지 추가 / chapter 삭제 / slug 이전 / cross-link 개정 후. 또한 사용자가 "404 뜨는 부분 잡자" / "링크 깨진 것 확인해줘" 같은 요청을 했을 때.

1차 도구 — `scripts/check_docs_links.py`

$ python3 scripts/check_docs_links.py              # 정적 audit (1초)
$ python3 scripts/check_docs_links.py --http       # + 외부 reachability (~10초)
$ python3 scripts/check_docs_links.py --quiet      # broken 만 출력 (CI 적합)

분류 4 종

Category	매칭 패턴	검증 방법
internal /docs/...	`href="/docs/runtime/foo"`	`site/src/app/docs/**/page.tsx` slug set 과 차집합
internal /...	`/portfolio`, `/petri-bundle/`, `/llms.txt`	app route + `site/public/` asset + build-time copy 와 대조
anchor #section	`href="#tier-3"`	같은 page.tsx 의 `id="..."` 와 대조
external https://	`<a href="https://github.com/...">`	`--http` 옵트인 시 HEAD/GET, concurrency 8, 8s timeout, 200/3xx OK

Link 패턴 추출 — 2 개 정규식

Pattern	매칭 예시
`\b(?:href\|src\|to)\s=\s\{?\s*['"`]([^'"`{}\s]+)['"`]`	`href="..."`, `href={"..."}`, `href={`...`}`, `src="/img.svg"`, `to="/portfolio"`
`\]$([^)\s]+)$`	markdown `[text](url)` — `MarkdownLite` 가 렌더하는 CHANGELOG entry 등

특이 처리

/geode/ deploy basepath 정규화 — /geode/docs/foo 도 source-side /docs/foo 와 매칭
Build-time copy 인지 — .github/workflows/pages.yml 의 docs/petri-bundle/ → site/out/petri-bundle/ copy step 알기 때문에 /petri-bundle/ 가 source 에 없어도 OK
${...} 보간 + relative URL → unresolved 로 분리 (broken 아님)
스킴 스킵 — mailto:, tel:, javascript:, data:, blob:
requests 미설치 시 --http 옵션 자동 비활성

Exit codes — CI guard 가능

Code	의미
0	broken 없음
1	1+ broken 발견
2	argparse / IO 에러

Workflow — 새 페이지 또는 cross-link 수정 후

1. 변경 → 본 변경이 새 페이지 추가 / slug 이전 / chapter 삭제 / cross-link 갱신 중 하나
        ↓
2. python3 scripts/check_docs_links.py
        ↓
3. broken 0 → 통과; PR 으로 진행
   broken N → 메시지의 file:line 으로 이동 + slug 정정
        ↓
4. (선택) --http 도 돌려서 외부 URL reachability 확인
        ↓
5. PR cascade — fix(docs): broken link N 종 정정 (M 사이트)

잘못된 link 의 4 흔한 원인

패턴	발생 시점	해결책
Chapter 삭제 후 cross-link leftover	옛 `build/` 챕터 삭제했는데 다른 페이지가 `/docs/build/add-domain` 참조	이전 destination 확인 후 새 slug 로 교체 — sitemap.ts 의 새 entry 가 1차 단서
Section 이전	`/docs/ops/observability` → `/docs/verification/observability` 로 옮겼는데 cross-link 갱신 누락	동일
Slug 오타	페이지 처음 작성 시 디렉터리 명 오타	typo 수정
External URL 만료	외부 doc 의 link 가 404 (e.g. dev portal 페이지 이전)	`--http` 가 잡음. 새 URL 또는 archive.org 로 교체

CI wiring (선택, 별 PR)

A. Pages build pre-step — pages.yml 의 build job 최상단에 추가:

- name: Verify docs links
  run: python3 scripts/check_docs_links.py

→ broken 들어오면 deploy 차단.

B. Lint job — ci.yml 에 별 job, dispatch 시 --http 포함:

docs-links:
  if: github.event_name == 'workflow_dispatch'
  steps:
    - run: pip install requests
    - run: python3 scripts/check_docs_links.py --http

→ 매일/주간 schedule cron 으로 외부 link rot 감지.

실제 case study

날짜	broken 수	정정 방식
2026-05-16 PR #1157	3 broken × 6 ref site	모든 destination 이 sitemap 에 다른 slug 로 존재. 단순 경로 교체
2026-05-16 PR #1161	0 (script 도입)	check_docs_links.py 추가 + 위 case study 결과 0 broken 측정

PR #1157 의 3 broken:

/docs/build/add-domain → /docs/runtime/domains (build/ chapter D 스프린트에서 삭제됨)
/docs/build/add-tool → /docs/runtime/tools/protocol
/docs/ops/observability → /docs/verification/observability (section 이전)

ad-hoc grep 으로 잡았지만 본 스크립트가 다음번부터는 1 명령으로 검출.

한계 + 알려진 false positive

항목	한계
Dynamic `href={url}`	변수 보간된 link 는 정적 분석 불가 → `unresolved` (broken 아님)
External URL rate-limit / login wall	`--http` 가 401/403 받으면 broken 으로 분류 — 일부 사이트 (Anthropic dev portal 등) 가 anti-bot 으로 403 가능
Anchor 검사 단위	같은 page.tsx 내 anchor 만 검증. 크로스 페이지 anchor `/docs/foo#bar` 는 `/docs/foo` 만 OK 면 통과 (anchor 자체는 검증 안 됨)
MarkdownLite regex 패턴 문자열	`markdown-lite.tsx:14,133` 의 regex 안의 `url` 문자열이 markdown link `]( )` 패턴 매칭 — 2 unresolved 항상 발생 (false positive, 무시)

Docs Link Audit

site/ Next.js docs 사이트의 모든 본문 링크를 정적 + 옵션 HTTP 로 검사한다. scripts/check_docs_links.py 가 본 워크플로의 1차 도구.

언제 가동되는가

신규 페이지 추가 / chapter 삭제 / slug 이전 / cross-link 개정 후. 또한 사용자가 "404 뜨는 부분 잡자" / "링크 깨진 것 확인해줘" 같은 요청을 했을 때.

1차 도구 — `scripts/check_docs_links.py`

$ python3 scripts/check_docs_links.py              # 정적 audit (1초)
$ python3 scripts/check_docs_links.py --http       # + 외부 reachability (~10초)
$ python3 scripts/check_docs_links.py --quiet      # broken 만 출력 (CI 적합)

분류 4 종

Category	매칭 패턴	검증 방법
internal /docs/...	`href="/docs/runtime/foo"`	`site/src/app/docs/**/page.tsx` slug set 과 차집합
internal /...	`/portfolio`, `/petri-bundle/`, `/llms.txt`	app route + `site/public/` asset + build-time copy 와 대조
anchor #section	`href="#tier-3"`	같은 page.tsx 의 `id="..."` 와 대조
external https://	`<a href="https://github.com/...">`	`--http` 옵트인 시 HEAD/GET, concurrency 8, 8s timeout, 200/3xx OK

Link 패턴 추출 — 2 개 정규식

Pattern	매칭 예시
`\b(?:href\|src\|to)\s=\s\{?\s*['"`]([^'"`{}\s]+)['"`]`	`href="..."`, `href={"..."}`, `href={`...`}`, `src="/img.svg"`, `to="/portfolio"`
`\]$([^)\s]+)$`	markdown `[text](url)` — `MarkdownLite` 가 렌더하는 CHANGELOG entry 등

특이 처리

/geode/ deploy basepath 정규화 — /geode/docs/foo 도 source-side /docs/foo 와 매칭
Build-time copy 인지 — .github/workflows/pages.yml 의 docs/petri-bundle/ → site/out/petri-bundle/ copy step 알기 때문에 /petri-bundle/ 가 source 에 없어도 OK
${...} 보간 + relative URL → unresolved 로 분리 (broken 아님)
스킴 스킵 — mailto:, tel:, javascript:, data:, blob:
requests 미설치 시 --http 옵션 자동 비활성

Exit codes — CI guard 가능

Code	의미
0	broken 없음
1	1+ broken 발견
2	argparse / IO 에러

Workflow — 새 페이지 또는 cross-link 수정 후

1. 변경 → 본 변경이 새 페이지 추가 / slug 이전 / chapter 삭제 / cross-link 갱신 중 하나
        ↓
2. python3 scripts/check_docs_links.py
        ↓
3. broken 0 → 통과; PR 으로 진행
   broken N → 메시지의 file:line 으로 이동 + slug 정정
        ↓
4. (선택) --http 도 돌려서 외부 URL reachability 확인
        ↓
5. PR cascade — fix(docs): broken link N 종 정정 (M 사이트)

잘못된 link 의 4 흔한 원인

패턴	발생 시점	해결책
Chapter 삭제 후 cross-link leftover	옛 `build/` 챕터 삭제했는데 다른 페이지가 `/docs/build/add-domain` 참조	이전 destination 확인 후 새 slug 로 교체 — sitemap.ts 의 새 entry 가 1차 단서
Section 이전	`/docs/ops/observability` → `/docs/verification/observability` 로 옮겼는데 cross-link 갱신 누락	동일
Slug 오타	페이지 처음 작성 시 디렉터리 명 오타	typo 수정
External URL 만료	외부 doc 의 link 가 404 (e.g. dev portal 페이지 이전)	`--http` 가 잡음. 새 URL 또는 archive.org 로 교체

CI wiring (선택, 별 PR)

A. Pages build pre-step — pages.yml 의 build job 최상단에 추가:

- name: Verify docs links
  run: python3 scripts/check_docs_links.py

→ broken 들어오면 deploy 차단.

B. Lint job — ci.yml 에 별 job, dispatch 시 --http 포함:

docs-links:
  if: github.event_name == 'workflow_dispatch'
  steps:
    - run: pip install requests
    - run: python3 scripts/check_docs_links.py --http

→ 매일/주간 schedule cron 으로 외부 link rot 감지.

실제 case study

날짜	broken 수	정정 방식
2026-05-16 PR #1157	3 broken × 6 ref site	모든 destination 이 sitemap 에 다른 slug 로 존재. 단순 경로 교체
2026-05-16 PR #1161	0 (script 도입)	check_docs_links.py 추가 + 위 case study 결과 0 broken 측정

PR #1157 의 3 broken:

/docs/build/add-domain → /docs/runtime/domains (build/ chapter D 스프린트에서 삭제됨)
/docs/build/add-tool → /docs/runtime/tools/protocol
/docs/ops/observability → /docs/verification/observability (section 이전)

ad-hoc grep 으로 잡았지만 본 스크립트가 다음번부터는 1 명령으로 검출.

한계 + 알려진 false positive

항목	한계
Dynamic `href={url}`	변수 보간된 link 는 정적 분석 불가 → `unresolved` (broken 아님)
External URL rate-limit / login wall	`--http` 가 401/403 받으면 broken 으로 분류 — 일부 사이트 (Anthropic dev portal 등) 가 anti-bot 으로 403 가능
Anchor 검사 단위	같은 page.tsx 내 anchor 만 검증. 크로스 페이지 anchor `/docs/foo#bar` 는 `/docs/foo` 만 OK 면 통과 (anchor 자체는 검증 안 됨)
MarkdownLite regex 패턴 문자열	`markdown-lite.tsx:14,133` 의 regex 안의 `url` 문자열이 markdown link `]( )` 패턴 매칭 — 2 unresolved 항상 발생 (false positive, 무시)

docs-link-audit

Docs Link Audit

언제 가동되는가

1차 도구 — `scripts/check_docs_links.py`

분류 4 종

Link 패턴 추출 — 2 개 정규식

특이 처리

Exit codes — CI guard 가능

Workflow — 새 페이지 또는 cross-link 수정 후

잘못된 link 의 4 흔한 원인

CI wiring (선택, 별 PR)

실제 case study

한계 + 알려진 false positive

관련 skill

Docs Link Audit

언제 가동되는가

1차 도구 — `scripts/check_docs_links.py`

분류 4 종

Link 패턴 추출 — 2 개 정규식

특이 처리

Exit codes — CI guard 가능

Workflow — 새 페이지 또는 cross-link 수정 후

잘못된 link 의 4 흔한 원인

CI wiring (선택, 별 PR)

실제 case study

한계 + 알려진 false positive

관련 skill

Pattern	매칭 예시
`\b(?:href\|src\|to)\s=\s\{?\s*['"`]([^'"`{}\s]+)['"`]`	`href="..."`, `href={"..."}`, `href={`...`}`, `src="/img.svg"`, `to="/portfolio"`
`\]\(([^)\s]+)\)`	markdown `[text](url)` — `MarkdownLite` 가 렌더하는 CHANGELOG entry 등

docs-link-audit

Docs Link Audit

언제 가동되는가

1차 도구 — scripts/check_docs_links.py

분류 4 종

Link 패턴 추출 — 2 개 정규식

특이 처리

Exit codes — CI guard 가능

Workflow — 새 페이지 또는 cross-link 수정 후

잘못된 link 의 4 흔한 원인

CI wiring (선택, 별 PR)

실제 case study

한계 + 알려진 false positive

관련 skill

المزيد من هذا المستودع

المزيد من هذا المستودع

Docs Link Audit

언제 가동되는가

1차 도구 — scripts/check_docs_links.py

분류 4 종

Link 패턴 추출 — 2 개 정규식

특이 처리

Exit codes — CI guard 가능

Workflow — 새 페이지 또는 cross-link 수정 후

잘못된 link 의 4 흔한 원인

CI wiring (선택, 별 PR)

실제 case study

한계 + 알려진 false positive

관련 skill

1차 도구 — `scripts/check_docs_links.py`

1차 도구 — `scripts/check_docs_links.py`