Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Documentation remediation: repair broken links, fill missing media slots, and correct web search documentation

Đang mở
  • Có gì không ổn?
#1,371 3 bình luận 0 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@paullizer đang làm issue này rồi.

Từ ngày 1/9/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

bug documentation P1

Summary

The documentation site has two classes of decay that need a coordinated fix, plus one page whose content is factually out of date with the application.

The docs/how-to/*.md pages were renamed and relocated to docs/guides/*.md (snake_case to kebab-case) during the documentation site redesign (#1293). Jekyll redirects were added for the site, but repository-relative markdown links in README.md and the deployer READMEs still point at the old file paths. Those links resolve to 404 on GitHub, where Jekyll redirects do not apply. Separately, a large number of media slots registered by the redesign were never filled, and the use-web-search documentation still describes the retired Bing Web Search API rather than the Azure AI Foundry agent path that is actually implemented.

No documentation content was lost. Every page reported as "missing" exists under its new path.

Scope

1. Broken repository-relative links (46 of 183 checked)
Location Count Nature
README.md 3 docs/how-to/upgrade_paths.md (x2), docs/how-to/docker_customization.md
deployers/bicep/README.md 2 old docs/how-to/ paths
deployers/terraform/ReadMe.md 4 old docs/how-to/ paths, ../README.md
deployers/azurecli/README.md 2 ../README.md should be ../../README.md
docs/explanation/features/v*/, docs/explanation/fixes/v*/ 34 archived version-stamped docs linking siblings that were never migrated

Correct targets: docs/guides/upgrade-paths.md, docs/guides/docker-customization.md, docs/guides/enterprise-networking.md.

2. Broken site URLs (6 real, of 625 relative_url links checked)
  • /application_scaling/ (x3) in docs/index.md, docs/start/about.md, docs/guides/admin-operate-simplechat.md. Source page no longer exists; content moved to /guides/scale-simplechat-on-azure/.
  • /reference/admin_configuration/ (x2) in docs/guides/configure-branding-and-support-settings.md and docs/reference/features.md, plus 10 additional occurrences in docs/_data/features.yml. Correct target is /admin_configuration/.
  • /how-to/model_endpoint_identity_setup/ (x1) in docs/explanation/features/v0.241.001/WORKSPACE_MULTI_ENDPOINTS.md.
3. Missing documentation media (146 of 170 registered slots are empty)
Group Empty slots
guides/* images 63 across 30 pages
reference/actions/* configuration screenshots 27 (one per action page)
reference/chat-controls.md 9
admin/* overview screenshots 4
Video posters 43 (all 43 also have no video URL)

Only 17 image slots are currently filled. 328 images already exist under docs/images/ (127 at the root, 187 under latest-release, 14 under admin-settings), and a significant portion of the root images map directly onto empty slots, so a reuse pass should close a meaningful share before any new capture work begins.

4. Web search documentation is factually stale

docs/guides/use-web-search.md and its companions describe "Bing web search". The Bing Web Search API was removed in v0.229.001. The implemented path is an Azure AI Foundry agent using Grounding with Bing Search, configured through web_search_agent.other_settings.azure_ai_foundry.agent_id.

The documentation also understates a privacy property that the code guarantees. build_web_search_query_text() in route_backend_chats.py returns only the trimmed current user message; conversation history, workspace documents, uploaded file contents, and system prompts are never sent to the external search boundary. This was deliberately hardened in v0.241.022 (WEB_SEARCH_EGRESS_HARDENING_FIX) and should be a prominent, explicit section rather than a passing sentence.

Affected files: docs/guides/use-web-search.md, docs/guides/index.md, docs/features.md, docs/reference/chat-controls.md, docs/admin/knowledge.md.

Acceptance Criteria

  • A functional_tests/test_docs_link_integrity.py test fails on any broken relative .md link across README.md, docs/, and deployers/, and on any unresolved relative_url page link, including URLs declared in docs/_data/features.yml and _config.yml navigation.
  • All 12 broken links in README.md and the deployer READMEs resolve.
  • All 6 broken site URLs resolve, and the 10 features.yml occurrences are corrected.
  • Old URLs continue to resolve via redirect_from on the destination pages so existing bookmarks and external links do not break.
  • The 34 archived links are either repointed to a valid target or unlinked, preserving the prose.
  • docs/guides/use-web-search.md correctly describes the Azure AI Foundry agent path, carries a dedicated section stating exactly what data leaves the application, documents the Deep Research multi-query nuance, and reproduces the Grounding with Bing Search compliance-boundary notice.
  • Existing images under docs/images/ are reused for every slot where a suitable capture already exists, before new screenshots are taken.
  • A repeatable capture harness exists under scripts/, reusing the established ui_tests Playwright conventions (SIMPLECHAT_UI_BASE_URL, SIMPLECHAT_UI_STORAGE_STATE, SIMPLECHAT_UI_ADMIN_STORAGE_STATE).
  • Remaining screenshots are captured and committed in batches of 20.
  • A deliberate decision is recorded for the 43 video slots: either branded poster frames are generated, or the slots are removed from pages that will not receive a recording.
  • docs/_data/app_surface.yml is regenerated, and test_docs_app_surface_coverage.py, test_docs_site_quality.py, and the new link-integrity test all pass.
  • application/single_app/config.py version and deployers/version.txt are bumped, and release notes are updated.

Notes

Delivered in phases so each is independently reviewable and committable:

  1. Phase 0 - link and media integrity test (the regression guard; without it these links re-break in a few releases).
  2. Phase 1 - the 12 README.md and deployer links. Touches deployers/**, so deployers/version.txt is bumped.
  3. Phase 2 - the 6 site URLs and features.yml.
  4. Phase 3 - web search documentation rewrite.
  5. Phase 4 - archived link cleanup.
  6. Phase 5 - reuse existing images for empty slots (no capture cost).
  7. Phase 6 - Playwright capture harness.
  8. Phase 7 - screenshot capture in batches of 20, one commit per batch.
  9. Phase 8 - video poster decision.
  10. Phase 9 - version bump, full test pass, release notes.

Related to #1293, which introduced the reorganization and registered the media slots.

Ngôn ngữ chính
Python
Star
155
Fork
116
Merge trung bình
7 giờ 40 phút
Pull request đã merge (30 ngày)
175

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của microsoft/simplechat

Tất cả issue của microsoft/simplechat

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.