Documentation site redesign: search, navigation, mobile support, and complete capability coverage - #1326
Merged
Paul Lizer (paullizer) merged 15 commits intoAug 20, 2026
Conversation
…stem Search was unusable: 84% of the 986 indexed pages were internal engineering notes, 88% of entries had no description, and no page body text was indexed at all, so search was a substring match over noisy titles. - Exclude the ~830 engineering notes under explanation/features and explanation/fixes from the build. They stay in the repo and remain readable on GitHub. Index drops from 986 to 165 entries. - Replace the title-only index with a content-bearing search-index.json and a Lunr-backed search with a /search/ results page, section filters, Ctrl+K, keyboard navigation, and highlighted excerpts. Lunr is vendored locally. - Add a media placeholder system. Screenshot and video slots render a card naming the exact file to create, and resolve automatically once the file is added. Videos link out to a poster card rather than embedding an iframe. - Add per-tab documentation for all 18 admin settings tabs, with settings tables, prerequisites, real procedures, and media placeholders. - Split the 452 KB release notes page into per-series pages, preserving the app-linked /explanation/release_notes/ permalink. - Fix path-scoped Jekyll defaults that used collection names and never applied, which is why every page fell back to a generic Docs section. - Fix a pre-existing desktop layout bug where .docs-main-content combined width 100% with a sidebar margin and overflowed by the sidebar width. - Standardize responsive breakpoints, contain wide tables and code blocks, and add a mobile search sheet. Remove unused jQuery, DataTables, marked, DOMPurify, and split.js. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Rebuild navigation so the top bar and sidebar expose the same six sections (Start, Guides, Features, Administration, Deploy and operate, Reference). Nav coverage goes from 27 URLs to 67, all verified to resolve. The 19 admin pages and the new search page were previously unreachable from navigation. - Vendor Bootstrap 5.3.0, Bootstrap Icons 1.11.3, Prism 1.29.0, and the Inter, JetBrains Mono, and Work Sans web fonts locally with their licenses, and point the runtime Prism dark-mode swap at the local files. The site now makes zero external requests, satisfying local_browser_assets.instructions.md. - Add ui_tests/test_docs_site_responsive.js covering five viewports from 360x640 to 1920x1080: horizontal overflow, search reachability, navigation reachability, search relevance, the mobile search sheet, media placeholder rendering, and absence of external asset requests. 100 checks pass. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Add functional_tests/test_docs_app_surface_coverage.py. It fails when a new capability toggle, admin settings tab, action plugin, or chat control ships without documentation, and verifies docs/_data/app_surface.yml is still in sync with the application. This is the mechanism that keeps docs current as pull requests land. - Add functional_tests/test_docs_site_quality.py covering the application's documentation deep links, absence of CDN browser assets, exclusion of engineering notes, navigation link resolution, top bar and sidebar agreement, and search index quality. - Stop recording the application version in app_surface.yml. SimpleChat bumps VERSION on every change, so embedding it would have made the inventory differ on every pull request and turned the sync check into constant noise. - Rewrite the homepage from 82 blocks of hand-written card HTML with zero markdown headings into plain markdown with 6 h2 and 9 h3 headings, so the on this page table of contents and heading anchors work. - Fix three scenario index pages whose front matter was never parsed because a filename comment preceded it, leaving them titled with their own path and rendered through a zero-byte layout. - Add the feature detail layout for the data-driven capability catalog. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Closes the content gaps that left most of the product undocumented. - 23 task guides under docs/guides/, each opening with what the task does and why before the steps, with prerequisites naming the governing enable_* key and linking to the admin page that turns it on. Covers creating actions, agents, agents with actions, multi-task workflows, triggering workflows, file sync, tags, tags in chat, tags on conversations, and exporting conversations, plus guides derived from the application surface. - docs/reference/chat-controls.md documenting all 47 chat controls, each with what it does, why you would use it, and the setting that enables it. - docs/reference/actions/ documenting all 27 actions, at full depth for the ten most-used and as overviews for the rest. - Extend navigation to 74 links so the new content is reachable. Documentation coverage of the application surface is now complete and enforced: 18/18 admin tabs, 27/27 actions, 47/47 chat controls, and 85 user-facing capability toggles, with 26 internal flags carrying written exemptions. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Add a data-driven feature catalog. All 111 capability toggles are claimed by exactly one of 38 capability entries in docs/_data/features.yml, grouped into eight areas, each rendering a detail page with why you would use it, the settings that control it, and links to the guides and admin page for it. The features index is now plain markdown with real headings instead of 119 blocks of card markup with none. - Add docs/explanation/features/DOCUMENTATION_SITE_REDESIGN.md documenting the measured problems, what changed, and how coverage is kept current. - Add release notes for 0.250.230 and regenerate the split release notes pages. Verified: 100 browser checks across five viewports, 6/6 documentation coverage checks, 6/6 site quality checks, and all three generators reporting in sync. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…tribution rule The FAQ, getting started page, and four section index pages were authored as hand-written HTML card markup with almost no markdown headings, so none of them had a working on-this-page table of contents or heading anchors. | Page | HTML blocks before/after | Markdown headings before/after | |---|---|---| | faqs.md | 138 / 0 | 0 / 17 | | setup_instructions.md | 101 / 0 | 0 / 5 | | tutorials/index.md | 9 / 0 | 0 / 4 | | how-to/index.md | 10 / 0 | 0 / 5 | | explanation/index.md | 15 / 0 | 1 / 8 | | reference/features.md | 19 / 0 | 2 / 11 | Every FAQ question is now its own heading with an anchor, so answers can be linked directly. Content preservation was verified by comparing the distinct content words of each page before and after; the only differences are decorative card labels such as 'Quick answer' and 'Jump to'. Also adds .github/instructions/docs_coverage.instructions.md, making it a contribution rule that new capability toggles, admin tabs, actions, chat controls, and user surfaces ship with documentation, and documenting how to regenerate the inventory and fill media placeholders. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ping pages - Add five admin lifecycle guides covering deploy, first configuration in dependency order, update, day-to-day operations, and the repeatable procedure for enabling any optional capability safely. These carry video placeholders for the planned admin video series, which runs from deployment through update to each settings tab. 14 screenshot and 5 video placeholders added. - Split setup_instructions_manual.md (47 KB) into a hub that keeps its original URL plus five focused pages under docs/deploy/manual/. - Rebuild admin_configuration.md as a configuration hub that defers to the 18 per-tab pages instead of duplicating them. - Retire two duplicate pages behind redirects: /reference/admin_configuration/ now redirects to /admin_configuration/, and /application_scaling/ redirects to /how-to/scaling_on_azure/. Both redirects verified in the built output. The documentation coverage test caught a real regression during this work: the retired reference page was the only place documenting enable_cross_format_compare_one_to_many. The key is now documented on the configuration hub, and coverage is back to 6/6. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The showcase layout wrapped 38 pages in a gradient hero with pill rows and an icon orb, which was a large part of why pages read as visually busy. The hero is replaced with plain documentation header markup, so those pages simplify without each one needing a front matter change. - showcase-page.html: 8.3 KB to 5.3 KB, with zero remaining hero, pill, icon orb, or hero art markup. - main.scss: removed the dead DataTables rules, left over from libraries that are no longer loaded, plus the now-unused showcase hero styles. An empirical scan of the built HTML confirmed every remaining latest-release class is still rendered by the 68 release highlight pages, so none were removed. Browser suite still passes 100 checks. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ink rot Guides were split across three URL spaces that all meant the same thing (/tutorials/, /how-to/, /guides/), and several orientation and reference pages sat at the site root with no section. 30 pages now live under the section they belong to, each carrying a redirect_from entry so existing links keep working. - /tutorials/* and /how-to/* consolidated into /guides/, including the ServiceNow tree, with kebab-case filenames. The misspelled azure_speech_managed_identity_manul_setup is fixed and redirected. - Orientation pages moved to /start/, deployment scenarios to /deploy/, and reference pages to /reference/. - /tutorials/ and /how-to/ remain as redirect stubs to /guides/. Two problems the agent's own link check missed were found and fixed: - 14 ServiceNow companion assets (agent instruction text files and OpenAPI specs) were left behind when the guides moved, breaking five download links from the asset management guide. The assets moved with their pages and the links now resolve. - The generated release notes pages had been edited directly instead of their source, breaking generator sync. Regenerated from source. Adds ui_tests/check_docs_links.js, which resolves relative links against the containing page rather than only checking absolute hrefs. Measured against a baseline build of the pre-move site: 31,658 internal links checked, zero newly broken links, and 16 pre-existing broken links repaired. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…notes Adds a user-facing note that documentation URLs now match their section and that existing links and bookmarks continue to work through redirects, plus the FAQ anchor and page hero changes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The documentation site had 40 broken internal links that predated the redesign. All are now resolved and the site has zero broken internal links. Images (24 of the 40): the Latest Release pages referenced release highlight screenshots that were never present in the docs tree, so every one rendered broken. The files already existed in the application at application/single_app/static/images/features/, where the in-app Latest Features gallery reads them, so the real screenshots are now published with the site rather than scaffolded as placeholders. GitHub Pages can only publish files inside docs/, so both copies are required; this is noted as a known limitation. Links (the remaining 16): - Repointed links to renamed pages: the retired reference configuration page, the FAQ, the ServiceNow guide index, the Databricks action, and the tutorial slugs that became guides. - Converted links targeting repository files that are not published on the site into GitHub blob URLs: the Custom Pages developer guide, the Teams app manifest, a CI workflow, and an engineering fix note. - Removed two references to a ServiceNow multi-action setup guide that was never written. check_docs_links.js now skips pages under custom_pages_examples/. Those are sample code, not documentation navigation, and reference application runtime paths and unrendered template variables that only resolve inside SimpleChat, so checking them produced permanent false failures. Verified: 31,650 internal links checked with zero broken, 100 browser checks across five viewports, 6/6 coverage checks, 6/6 site quality checks, and all three generators in sync. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Rebased onto Development, which shipped v0.260.001 and restructured the in-app Latest Features experience into three tiers. The documentation site was a full release behind, still presenting v0.250.001 as current. - Mirror the application's three-tier model: v0.260.001 current, v0.250.001 previous, v0.239.001-v0.241.007 archive. - Add 20 feature guides for the v0.260.001 release, sourced from the end-user copy already written in support_menu_config.py, and publish their 60 gallery images. - Track the branded 'Screenshot pending' placeholders the release ships. They render so cards are not broken, but they are now listed on the media status page with the exact paths to overwrite, so they are visible work rather than a silent gap. - Use the 14 real admin settings screenshots that already existed in the repository. Those tab pages had been rendering 'screenshot needed' placeholders for images we already had. The four tabs with no capture keep their placeholder so genuine gaps stay visible. - Update test_latest_release_docs_structure.py for the new tiers. Its pinned current-release slugs, guide titles, and image lists were still v0.250, and its admin screenshot assertion still pointed at the retired monolithic configuration page rather than the per-tab pages that now own those images. The assertion was verified to still fail when an image is fully orphaned. - Fix the release notes generator, which inlined a fixed number of releases on its index. The consolidated v0.260.001 rollup is large enough alone to push the index past the maximum page size and fail generation. The inline section now fills by size rather than by count. - Repoint archived release notes links at the repository, since the internal feature and fix note trees are intentionally unpublished. Verified: 100 browser checks across five viewports, 33,892 internal links with zero broken, 6/6 coverage checks, 6/6 site quality checks, the latest-release structure test, and all three generators in sync. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…lities
Rebased onto Development at v0.260.019. The only application surface change was
Admin Settings: capabilities, actions, chat controls, app pages, and feature
surfaces are all unchanged, which scoped the work precisely.
Admin Settings moved from 18 flat tabs to a grouped architecture of 14 groups,
44 tabs, and 93 sections, now declared in a new admin_settings_nav.py.
- Rewrite the inventory extractor to read that definition. It had scraped tab
markup out of admin_settings.html, which shrank from 12,492 lines to 620 when
the template was split into per-tab partials, so scraping returned a single
literal '{{ admin_tab.id }}' and admin coverage silently collapsed to one
bogus tab. Removed the now-dead HTML tab parser.
- Rebuild the 19 admin pages as 14 group pages, each tab reachable by its own
anchor. All 18 retired tab URLs still resolve, 13 by redirect and 5 because
the old tab id is now a group id. Inbound links and the feature catalog's
admin_tab values were repointed.
- Update the coverage test for the grouped structure: every group needs a page
and every tab id must appear as an anchor on its group page.
- Add a guide for collaborating in a conversation, covering the shared file
approvals and '@' mention Tab completion shipped in v0.260.005 and v0.260.006,
and document the Blob Storage action's managed identity and account key
options.
Two generator bugs surfaced and were fixed:
- Release notes pages failed the site build outright. Release notes quote
template syntax when describing template work, and an unescaped Jinja 'block'
tag was parsed as Liquid. Quoted syntax is now escaped and renders literally.
- Some release note entries linked to the unpublished engineering note trees.
Verified: 100 browser checks across five viewports, 32,483 internal links with
zero broken, 7/7 coverage checks, 6/6 site quality checks, the latest-release
structure test, and all three generators in sync.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
CodeQL flagged js/xss-through-dom in the documentation site's click-to-enlarge screenshot viewer. It assigned an image URL read from a data attribute in the rendered page, so page content flowed directly into a URL sink. The viewer now resolves the value against the document and requires a same-origin http or https URL whose path ends in an image extension. That rejects scheme-based payloads such as javascript: and data: URLs and any off-site source. All documentation media is local, so no legitimate image is affected, and the enlarge behavior is unchanged. Adds ui_tests/test_docs_media_lightbox_source_validation.js, which executes the real validation function against hostile and legitimate inputs so the guard cannot be quietly removed or weakened. It covers javascript: and data: URLs, off-site and protocol-relative sources, same-origin non-image paths, and non-string input, alongside the local image paths that must keep working. Verified in a browser as well as in isolation: legitimate screenshots still open in the viewer, and a javascript: URL leaves it closed. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The media lightbox regression test asserted an accepted URL by checking result.startsWith(ORIGIN). CodeQL correctly flagged that as js/incomplete-url-substring-sanitization: a prefix check is weak URL matching, because a host such as microsoft.github.io.example.com shares the prefix without sharing the origin. The assertion now parses the result and compares the origin field. The test still passes all 17 checks, so the guard it protects is unchanged. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
Author
CodeQL: fixed, and a note on
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rebuilds the documentation site at https://microsoft.github.io/simplechat/, and keeps it in step with the v0.260.001 release and the Admin Settings information-architecture rework.
/search/results page with section filters,Ctrl+K, and a mobile search sheet. Search was previously hidden entirely on phones.Linked issue
Refs #1293
Release Notes & Latest Features
Is this visible to end users?
Is this admin-facing (Admin Settings, governance, deployment, config)?
Should this become a Latest Feature card?
Documentation improvements are not an in-app feature card. The v0.260.001 Latest Features cards themselves are already covered: all 20 have documentation pages.
Screenshot needed for the card?
Version bump
application/single_app/config.pyVERSIONthird segment bumped —0.260.019to0.260.020deployers/version.txtbumped, or not needed becausedeployers/was not changedNo application runtime code changes. The only change outside
docs/,scripts/,functional_tests/,ui_tests/, and.github/instructions/is theVERSIONline.Testing / validation
cd docs; bundle exec jekyll build— clean buildnode ui_tests/test_docs_site_responsive.js— 100 checks passed across 360x640, 390x844, 768x1024, 1280x800, 1920x1080, covering horizontal overflow, search and navigation reachability, search relevance, the mobile search sheet, media placeholder rendering, and absence of external asset requestsnode ui_tests/check_docs_links.js docs/_site— 32,483 internal links checked, 0 brokenpython functional_tests/test_docs_app_surface_coverage.py— 7/7, covering 14/14 admin groups, 44/44 admin tabs, 27/27 actions, 47/47 chat controls, and 111/111 capability togglespython functional_tests/test_docs_site_quality.py— 6/6, including the application's documentation deep links, absence of CDN assets, and search index qualitypython functional_tests/test_latest_release_docs_structure.py— passedpython scripts/build_docs_inventory.py --check,scripts/generate_feature_pages.py --check,scripts/build_release_notes_pages.py --check— all in syncManual validation: verified the 18 retired admin tab URLs still resolve (13 by redirect, 5 because the old tab id is now a group id), and mutation-tested the admin screenshot assertion to confirm it still fails when an image becomes orphaned rather than having been weakened.
Documentation
docs/explanation/features/DOCUMENTATION_SITE_REDESIGN.mdAlso adds
.github/instructions/docs_coverage.instructions.mdso documentation coverage is a contribution rule going forward.Security checklist
@swagger_route(security=get_auth_security())— not applicable, no routes addedsanitize_settings_for_user()— not applicable, no application code changedThis PR removes the documentation site's CDN dependencies rather than adding any. jQuery, DataTables, marked, DOMPurify, and split.js were loaded but never used and are gone; Bootstrap, Bootstrap Icons, Prism, Lunr, and the web fonts are vendored locally under
docs/assets/vendor/with their licenses. The site now issues zero external requests, verified by the browser suite.Notable fixes found along the way
.docs-main-contentcombinedwidth: 100%with a sidebar margin, so every desktop viewport scrolled sideways by exactly the sidebar width. Long-standing defect on the published site.type, so they never applied and nearly every page fell back to a generic "Docs" section, which is why search facets were useless.blocksyntax unescaped, failing the site build with an unknown-tag error.Known gaps, deliberately left visible
/contributing/media-status/is the worklist, and the v0.260.001 branded "Screenshot pending" placeholders are tracked there with the exact paths to overwrite.workflow,governance,data-lifecycle,backup-recovery.