Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Replace in-repo .md cross-references in skill content with Microsoft Learn URLs

Aperta
  • Qualcosa non va?
#15 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
52/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
markdown, powershell, python
Ambito
documentation, tooling

Direzione di ricerca

Inizia verificando skills/**/*.md e la mappatura di PR #14, incluse le domande ancora irrisolte su monitoring e inline-text. Usa i riferimenti Learn elencati per identificare ogni link .md nel repository, quindi esegui scripts/validate-skills.ps1. Il lavoro è completato quando tutti i link alle skill applicabili risolvono a URL Learn canonici e il validator ha esito positivo.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Problem

Skill rule files cross-reference each other and adjacent skills using relative .md paths (e.g. [security-private-endpoint](security-private-endpoint.md), [ha-cross-region-replica](../high-availability/ha-cross-region-replica.md)). When the skill content is consumed by an agent or rendered outside the repo, these in-repo links don't resolve — the consumer needs links to the official Microsoft Learn articles instead.

Proposed fix

Replace every *.md link inside skill content (rule files and SKILL.md) with the canonical Learn URL. Each rule already lists its primary Learn source in its ## References section, so the mapping is straightforward.

Mapping (from PR #14 audit)
Sibling rules — skills/security/
.md reference Replace with
security-private-endpoint.md https://learn.microsoft.com/azure/documentdb/how-to-private-link
security-firewall-rules.md https://learn.microsoft.com/azure/documentdb/how-to-configure-firewall
security-entra-rbac.md https://learn.microsoft.com/azure/documentdb/how-to-connect-role-based-access-control
security-database-roles.md https://learn.microsoft.com/azure/documentdb/how-to-connect-role-based-access-control
security-azure-rbac-actions.md https://learn.microsoft.com/azure/documentdb/how-to-connect-role-based-access-control
security-token-lifetime-revocation.md https://learn.microsoft.com/azure/documentdb/how-to-connect-role-based-access-control
security-cmk-encryption.md https://learn.microsoft.com/azure/documentdb/database-encryption-at-rest
security-cmk-troubleshooting.md https://learn.microsoft.com/azure/documentdb/how-to-database-encryption-troubleshoot
security-tls-required.md https://learn.microsoft.com/azure/documentdb/security
security-admin-password-and-identity-separation.md https://learn.microsoft.com/azure/documentdb/security
Cross-skill references
.md reference Replace with
../high-availability/ha-cross-region-replica.md https://learn.microsoft.com/azure/documentdb/cross-region-replication
../high-availability/ha-backup-retention.md https://learn.microsoft.com/azure/reliability/reliability-documentdb
../monitoring/ (directory ref) https://learn.microsoft.com/azure/documentdb/monitor-resource-logs (needs confirmation)
Open questions
  1. Four security rules collapse to the same RBAC Learn article (how-to-connect-role-based-access-control) — security-entra-rbac, security-database-roles, security-azure-rbac-actions, security-token-lifetime-revocation. That single Learn article is the source for all four. Acceptable, or do we want sub-section anchors?
  2. Two rules collapse to azure/documentdb/security — security-tls-required and security-admin-password-and-identity-separation. Both pulled from the "Secure your cluster" overview.
  3. Monitoring landing page — confirm the right canonical URL for the ../monitoring/ directory reference.
  4. Inline non-link text like `storage/` in SKILL.md (parenthetical "Premium SSD v1 only — see storage/") — convert to Learn link too, or leave as in-repo navigation hint?
Scope

This issue is about all skill folders, not just security/. PR #14 surfaced the issue but the same pattern almost certainly exists in high-availability/, storage/, and any future skill. Recommend a one-pass sweep across skills/**/*.md once the open questions are resolved.

Suggested implementation

A small PowerShell or Python script that walks skills/**/*.md, applies the mapping table above, and reports any unmapped .md) link for manual review. Validator (scripts/validate-skills.ps1) should pass after the sweep.

Originating context

Surfaced during review of PR #14 (docs/security-rbac). Mapping table was generated by auditing the ## References section of each affected rule file.

Lingua principale
Python
Stelle
6
Fork
11
Merge medio
3g 2h
PR unite (30g)
1

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Azure/documentdb-agent-kit

Tutte le issue di Azure/documentdb-agent-kit

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.