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

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

Aperta
  • Qualcosa non va?
#1,371 3 commenti 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@paullizer ci sta già lavorando.

Dal 1/9/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

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.

Lingua principale
Python
Stelle
155
Fork
116
Merge medio
7h 40m
PR unite (30g)
175

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

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 microsoft/simplechat

Tutte le issue di microsoft/simplechat

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.