Visual and content update to Github Pages#858
Open
paullizer wants to merge 2 commits intoDevelopmentfrom
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refreshes the GitHub Pages documentation site to use a shared “showcase” visual layout (matching the latest-release styling), expands/rewrites a number of docs pages into the new format, and adds/updates UI regression coverage for the redesigned docs experience.
Changes:
- Introduces a new Jekyll
showcase-pagelayout (hero, cards, optional prev/next nav, shared feature-image modal) and ensures the feature-image modal JS handles link clicks correctly. - Migrates many docs pages (tutorials, how-to, reference, explanation, support) to the new showcase layout and content structure.
- Adds a Playwright UI test to validate key docs pages render at desktop/mobile breakpoints and that the features image modal opens.
Reviewed changes
Copilot reviewed 53 out of 60 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| ui_tests/test_docs_showcase_pages.py | Adds Playwright coverage for docs pages across viewports and validates feature-image modal behavior. |
| docs/_layouts/showcase-page.html | New shared docs “showcase” layout with hero, card styling, nav controls, and image modal. |
| docs/_layouts/latest-release-feature.html | Cache-busts latest-release.js include to ensure updated modal behavior ships. |
| docs/assets/js/latest-release.js | Prevents default click navigation so modal triggers don’t navigate away; sets modal image alt/title/caption. |
| docs/index.md | Reworks docs landing page into showcase layout and structured “start here” sections. |
| docs/features.md | Rewrites features page into structured showcase sections and adds modal image triggers for previews. |
| docs/faqs.md | Converts FAQ to showcase layout with collapsible sections and jump anchors. |
| docs/about.md | Converts About page to showcase layout with clearer navigation and positioning. |
| docs/admin_configuration.md | Converts admin configuration guide to showcase layout and new intro framing. |
| docs/application_workflows.md | Converts workflow docs to showcase layout and streamlines workflow narratives. |
| docs/application_scaling.md | Converts scaling guidance to showcase layout and simplifies scaling guidance presentation. |
| docs/demos.md | Converts demos page to showcase layout with embedded demo previews. |
| docs/external_apps_overview.md | Converts external apps overview to showcase layout and updates links to GitHub source. |
| docs/setup_instructions.md | Converts setup instructions page to showcase layout and reorganizes into “deployment options / prerequisites / next steps”. |
| docs/setup_instructions_manual.md | Converts manual setup page to showcase layout and adds overview cards. |
| docs/setup_instructions_special.md | Converts special setup scenarios page to showcase layout and adds overview cards. |
| docs/troubleshooting/troubleshooting.md | Converts troubleshooting page to showcase layout and improves Kusto query formatting and headings. |
| docs/tutorials/index.md | Converts tutorials index to showcase layout with card-based navigation. |
| docs/tutorials/getting_started.md | Converts tutorial 1 page to showcase layout with hero metadata + intro cards. |
| docs/tutorials/first_agent.md | Converts tutorial 2 page to showcase layout with hero metadata + intro cards. |
| docs/tutorials/uploading_documents.md | Converts tutorial 3 page to showcase layout with hero metadata + intro cards. |
| docs/tutorials/classifying_documents.md | Converts tutorial 4 page to showcase layout with hero metadata + intro cards. |
| docs/how-to/index.md | Adds how-to index page in showcase layout. |
| docs/how-to/add_documents.md | Adds “Add Documents” how-to page in showcase layout. |
| docs/how-to/create_agents.md | Adds “Create Agents” how-to page in showcase layout. |
| docs/how-to/use_managed_identity.md | Converts managed identity how-to to showcase layout and adds structured overview. |
| docs/how-to/upgrade_paths.md | Converts upgrade paths how-to to showcase layout and adds structured overview. |
| docs/how-to/scaling_on_azure.md | Converts scaling how-to to showcase layout and adds structured overview. |
| docs/how-to/docker_customization.md | Converts Docker customization how-to to showcase layout and updates intro framing. |
| docs/how-to/enterprise_networking.md | Converts enterprise networking how-to to showcase layout and adds structured overview. |
| docs/how-to/azure_speech_managed_identity_manul_setup.md | Converts Speech MI setup doc to showcase layout and expands overview. |
| docs/how-to/agents/ServiceNow/index.md | Adds ServiceNow how-to index page in showcase layout. |
| docs/how-to/agents/ServiceNow/SERVICENOW_INTEGRATION.md | Converts ServiceNow integration doc to showcase layout and fixes spacing in metadata line. |
| docs/how-to/agents/ServiceNow/SERVICENOW_OAUTH_SETUP.md | Converts ServiceNow OAuth setup doc to showcase layout. |
| docs/how-to/agents/ServiceNow/TWO_AGENT_SETUP.md | Converts ServiceNow two-agent doc to showcase layout. |
| docs/how-to/agents/ServiceNow/SERVICENOW_ASSET_MANAGEMENT_SETUP.md | Converts ServiceNow asset management setup doc to showcase layout. |
| docs/reference/deploy/index.md | Converts deploy reference index to showcase layout while retaining recommended order list. |
| docs/reference/deploy/azd-cli_deploy.md | Converts AZD deploy reference to showcase layout with stronger runtime-model framing. |
| docs/reference/deploy/azurecli_powershell_deploy.md | Converts Azure CLI + PowerShell deploy reference to showcase layout. |
| docs/reference/deploy/bicep_deploy.md | Converts Bicep deploy reference to showcase layout and refines workflow guidance. |
| docs/reference/deploy/terraform_deploy.md | Converts Terraform deploy reference to showcase layout and adds warning panel. |
| docs/reference/deploy/manual_deploy.md | Converts manual deploy notes reference to showcase layout and refines checklist formatting. |
| docs/reference/admin_configuration.md | Converts admin configuration reference to showcase layout with structured overview. |
| docs/reference/api_reference.md | Adds API reference page in showcase layout listing Swagger/OpenAPI endpoints. |
| docs/reference/features.md | Adds features reference page in showcase layout mapping features to dependencies and deeper docs. |
| docs/explanation/index.md | Converts explanation index to showcase layout with structured navigation. |
| docs/explanation/architecture.md | Converts architecture explanation page to showcase layout and adds overview cards. |
| docs/explanation/design_principles.md | Converts design principles page to showcase layout and adds overview cards. |
| docs/explanation/feature_guidance.md | Converts feature guidance page to showcase layout and adds rollout grouping table. |
| docs/explanation/running_simplechat_locally.md | Converts local runtime doc to showcase layout and updates doc version string. |
| docs/explanation/running_simplechat_azure_production.md | Converts Azure production runtime doc to showcase layout and updates doc version string. |
| docs/explanation/features/v0.241.006/AI_VOICE_CONVERSATIONS_SETUP_GUIDE.md | Adds feature doc page describing the AI Voice Conversations setup guide modal. |
| docs/explanation/fixes/v0.241.006/TABULAR_EXHAUSTIVE_RESULT_SYNTHESIS_FIX.md | Adds fix documentation page for tabular synthesis retry behavior. |
| docs/explanation/fixes/v0.241.006/TABULAR_RESULT_COVERAGE_REDUNDANT_COMPARISON_FIX.md | Adds fix documentation page for redundant comparisons cleanup. |
| docs/explanation/fixes/v0.241.006/SPEECH_VIDEO_INDEXER_GUIDANCE_FIX.md | Adds fix documentation page for multimedia setup guidance alignment. |
| docs/explanation/fixes/v0.241.006/SPEECH_RESOURCE_ID_BUILDER_FIX.md | Adds fix documentation page for Speech resource ID builder helper. |
| docs/explanation/fixes/v0.241.006/MEDIA_ENHANCED_CITATION_BADGE_FIX.md | Adds fix documentation page for media enhanced citation badge consistency. |
| docs/explanation/fixes/v0.241.006/GROUP_PROMPTS_ROLE_UI_NULL_GUARD_FIX.md | Adds fix documentation page for group prompts role UI null guarding. |
| docs/contributing.md | Adds a docs-site contributor guide in showcase layout (includes docs UI regression instructions). |
| CONTRIBUTING.md | Adds a root contributor guide aligned with the docs-site version. |
Comment on lines
+2
to
+6
| """ | ||
| UI test for docs showcase pages. | ||
| Version: 0.241.010 | ||
| Implemented in: 0.241.010 | ||
|
|
There was a problem hiding this comment.
The UI test header version (0.241.010) doesn’t match the current application VERSION in application/single_app/config.py (0.241.006). Please sync the test’s Version/Implemented-in values to the current config.py version (or source it dynamically) so version traceability stays accurate.
Comment on lines
+7
to
+11
| <article class="page-content latest-release-page docs-showcase-page latest-release-accent--{{ accent }}"> | ||
| <section class="latest-release-hero"> | ||
| <div class="latest-release-hero-copy"> | ||
| {% if page.breadcrumb and page.breadcrumb.url and page.breadcrumb.label %} | ||
| <div class="latest-release-breadcrumb"> |
There was a problem hiding this comment.
This new layout uses 2-space indentation throughout, but the repo’s HTML guide requires 4 spaces per indentation level. Re-indent this file (and keep it consistent) to avoid style drift in future edits.
Comment on lines
+35
to
+40
| <section class="latest-release-card-grid"> | ||
| <article class="latest-release-card"> | ||
| <div class="latest-release-card-icon"><i class="bi bi-diagram-2"></i></div> | ||
| <h2>Pick the right workspace</h2> | ||
| <p>Personal, group, and ephemeral content each serve a different purpose. Start by placing the file where the future conversation should happen.</p> | ||
| </article> |
There was a problem hiding this comment.
This embedded HTML uses tab indentation. The repo HTML guide requires 4-space indentation and no tabs; please replace tabs with spaces in these blocks so diffs stay consistent and formatting is predictable across editors.
Comment on lines
+27
to
+33
| <section class="latest-release-card-grid"> | ||
| <article class="latest-release-card"> | ||
| <div class="latest-release-card-icon"><i class="bi bi-rocket-takeoff"></i></div> | ||
| <h2>Getting Started</h2> | ||
| <p>Deploy Simple Chat, configure the basics, upload a document, and run the first grounded conversation.</p> | ||
| <p><a href="{{ '/tutorials/getting_started/' | relative_url }}">Open tutorial</a></p> | ||
| </article> |
There was a problem hiding this comment.
This page’s card grid HTML is indented with tabs. Please convert tabs to 4-space indentation per the repo HTML guide to keep formatting consistent across the docs site.
Comment on lines
+84
to
+89
| ## Related guides | ||
|
|
||
| - [Create Your First Agent](../tutorials/first_agent.md) | ||
| - [Admin Configuration Reference](../reference/admin_configuration.md) | ||
| - [API Reference](../reference/api_reference.md) | ||
| - [ServiceNow Agent Examples](./agents/ServiceNow/) |
There was a problem hiding this comment.
These related-guide links point at source .md files (e.g., ../tutorials/first_agent.md). With permalink: pretty and collection permalinks enabled, the built site URLs are directory-style (e.g., /tutorials/first_agent/), so these can become broken links in the rendered docs. Prefer permalink paths (or relative_url) instead of linking to .md source files.
Comment on lines
+80
to
+83
| - [Uploading and Managing Documents](../tutorials/uploading_documents.md) | ||
| - [Document Classification Tutorial](../tutorials/classifying_documents.md) | ||
| - [Application Workflows](../application_workflows.md) | ||
| - [Troubleshooting](../troubleshooting/troubleshooting.md) |
There was a problem hiding this comment.
The related-guide links here reference .md source paths (e.g., ../tutorials/uploading_documents.md). Since the site uses pretty permalinks and collection permalinks, these links can render as broken in the built docs. Use the permalink-style URLs (or relative_url) instead of .md source links.
Suggested change
| - [Uploading and Managing Documents](../tutorials/uploading_documents.md) | |
| - [Document Classification Tutorial](../tutorials/classifying_documents.md) | |
| - [Application Workflows](../application_workflows.md) | |
| - [Troubleshooting](../troubleshooting/troubleshooting.md) | |
| - [Uploading and Managing Documents]({{ "/tutorials/uploading_documents/" | relative_url }}) | |
| - [Document Classification Tutorial]({{ "/tutorials/classifying_documents/" | relative_url }}) | |
| - [Application Workflows]({{ "/application_workflows/" | relative_url }}) | |
| - [Troubleshooting]({{ "/troubleshooting/troubleshooting/" | relative_url }}) |
Comment on lines
+60
to
67
| ## Recommended order | ||
|
|
||
| 1. [Azure Developer CLI (`azd up`)](./azd-cli_deploy.md) | ||
| 2. [Azure CLI with PowerShell](./azurecli_powershell_deploy.md) | ||
| 3. [Bicep](./bicep_deploy.md) | ||
| 4. [Terraform](./terraform_deploy.md) | ||
| 5. [Manual deployment notes](./manual_deploy.md) | ||
|
|
There was a problem hiding this comment.
The “Recommended order” list links to ./*.md files. With pretty permalinks and collection permalinks enabled, the rendered pages typically live at directory URLs (e.g., /reference/deploy/azd-cli_deploy/), so these source-file links can break on the published site. Prefer permalink paths (or relative_url) for these entries.
Comment on lines
+29
to
+33
| <div class="latest-release-card-image"> | ||
| <img src="{{ '/images/UploadDocumentDemo.gif' | relative_url }}" alt="Animated demo showing document upload and metadata review in Simple Chat"> | ||
| </div> | ||
| <h2>Upload document and review metadata</h2> | ||
| <p>This flow shows how a document enters the system, how users confirm the upload worked, and where metadata becomes visible during processing.</p> |
There was a problem hiding this comment.
These <img> tags are not self-closed. The repo HTML guide requires self-closing void elements (e.g., <img ... />). Please update these image tags (and similar ones on the page) to match the convention.
Comment on lines
+28
to
+32
| <article class="latest-release-card"> | ||
| <div class="latest-release-card-image"> | ||
| <img src="{{ '/images/workflow-content_safety.png' | relative_url }}" alt="Workflow diagram for content safety screening before model execution"> | ||
| </div> | ||
| <h2>Content Safety</h2> |
There was a problem hiding this comment.
The embedded HTML here uses <img ...> without a trailing />. The repo HTML guide expects self-closing void tags (<img ... />), so please update these image tags to match the convention.
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.
This is just editing the docs files for github pages, ive merged this work into the dev > staging > main because it was getting too far out of sync so now it builds off main instead of the pages-documentation branch