Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
#15 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
markdown, powershell, python

Research direction

Start by auditing skills/**/*.md and the mapping from PR #14, including the unresolved monitoring and inline-text questions. Use the listed Learn references to identify every in-repo .md link, then run scripts/validate-skills.ps1. Done means all applicable skill links resolve to canonical Learn URLs and the validator passes.

Written by the indexing model from the issue text.

Description

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/securitysecurity-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.

Dominant language
Shell
Stars
6
Forks
10
Avg merge
11d 20h
Merged PRs (30d)
2

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Azure/documentdb-agent-kit

All issues in Azure/documentdb-agent-kit

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.