Updates to Markdown files (links, lint, wording) (#1700)

* Add GitHub action

* Add GitHub action

* Markdown lint, try to get running

* Markdown lint

* Update markdown lint

* Fix markdown lint issues

Author: pamelafox

.github/workflows/lint-markdown.yml

@@ -0,0 +1,22 @@
+name: Validate Markdown
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - '**.md'
+
+jobs:
+  lint-markdown:
+    name: Check for Markdown linting errors
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Run markdownlint
+        uses: articulate/actions-markdownlint@v1
+        with:
+          config: .github/workflows/markdownlint-config.json
+          files: '**/*.md'
+          ignore: data/

.github/workflows/markdownlint-config.json

@@ -0,0 +1,5 @@
+{
+    "default": true,
+    "line-length": false,
+    "MD033": { "allowed_elements": ["br", "details", "summary"] }
+}

.github/workflows/validate-markdown.yml

@@ -3,7 +3,7 @@ name: Validate Markdown
 on:
   # Trigger the workflow on pull request
   pull_request_target:
-    branches: 
+    branches:
       - main
     paths:
       - '**.md'

CHANGELOG.md

@@ -1,9 +1,6 @@
-# ChatGPT + Enterprise data with Azure OpenAI and AI Search
+# ChatGPT-like app with your data using Azure OpenAI and Azure AI Search (Python)
 
-> [!IMPORTANT]
-> As of November 15, 2023, Azure Cognitive Search has been renamed to Azure AI Search.
-
-### Announcing [**JavaScript**](https://aka.ms/azai/js/code), [**.NET**](https://aka.ms/azai/net/code), and [**Java**](https://aka.ms/azai/java/code) samples based on this one ([**Python**](https://aka.ms/azai/py/code)). Learn more at  https://aka.ms/azai.
+This solution's backend is written in Python. There are also [**JavaScript**](https://aka.ms/azai/js/code), [**.NET**](https://aka.ms/azai/net/code), and [**Java**](https://aka.ms/azai/java/code) samples based on this one. Learn more about [developing AI apps using Azure AI Services](https://aka.ms/azai).
 
 ## Table of Contents
 
@@ -55,11 +52,11 @@ The repo includes sample data so it's ready to try end to end. In this sample ap
 
 **IMPORTANT:** In order to deploy and run this example, you'll need:
 
-* **Azure account**. If you're new to Azure, [get an Azure account for free](https://azure.microsoft.com/free/cognitive-search/) and you'll get some free Azure credits to get started. See [guide to deploying with the free trial](docs/deploy_lowcost.md).
-* **Azure subscription with access enabled for the Azure OpenAI service**. You can request access with [this form](https://aka.ms/oaiapply). If your access request to Azure OpenAI service doesn't match the [acceptance criteria](https://learn.microsoft.com/legal/cognitive-services/openai/limited-access?context=%2Fazure%2Fcognitive-services%2Fopenai%2Fcontext%2Fcontext), you can use [OpenAI public API](https://platform.openai.com/docs/api-reference/introduction) instead. Learn [how to switch to an OpenAI instance](docs/deploy_existing.md#openaicom-openai).
-* **Azure account permissions**:
-  * Your Azure account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [Role Based Access Control Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview), [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator), or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner). If you don't have subscription-level permissions, you must be granted [RBAC](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview) for an existing resource group and [deploy to that existing group](docs/deploy_existing.md#resource-group).
-  * Your Azure account also needs `Microsoft.Resources/deployments/write` permissions on the subscription level.
+- **Azure account**. If you're new to Azure, [get an Azure account for free](https://azure.microsoft.com/free/cognitive-search/) and you'll get some free Azure credits to get started. See [guide to deploying with the free trial](docs/deploy_lowcost.md).
+- **Azure subscription with access enabled for the Azure OpenAI service**. You can request access with [this form](https://aka.ms/oaiapply). If your access request to Azure OpenAI service doesn't match the [acceptance criteria](https://learn.microsoft.com/legal/cognitive-services/openai/limited-access?context=%2Fazure%2Fcognitive-services%2Fopenai%2Fcontext%2Fcontext), you can use [OpenAI public API](https://platform.openai.com/docs/api-reference/introduction) instead. Learn [how to switch to an OpenAI instance](docs/deploy_existing.md#openaicom-openai).
+- **Azure account permissions**:
+  - Your Azure account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [Role Based Access Control Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview), [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator), or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner). If you don't have subscription-level permissions, you must be granted [RBAC](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview) for an existing resource group and [deploy to that existing group](docs/deploy_existing.md#resource-group).
+  - Your Azure account also needs `Microsoft.Resources/deployments/write` permissions on the subscription level.
 
 ## Azure deployment
 
@@ -108,14 +105,14 @@ A related option is VS Code Dev Containers, which will open the project in your
 
 1. Install the required tools:
 
-    * [Azure Developer CLI](https://aka.ms/azure-dev/install)
-    * [Python 3.9, 3.10, or 3.11](https://www.python.org/downloads/)
-      * **Important**: Python and the pip package manager must be in the path in Windows for the setup scripts to work.
-      * **Important**: Ensure you can run `python --version` from console. On Ubuntu, you might need to run `sudo apt install python-is-python3` to link `python` to `python3`.
-    * [Node.js 14+](https://nodejs.org/en/download/)
-    * [Git](https://git-scm.com/downloads)
-    * [Powershell 7+ (pwsh)](https://github.com/powershell/powershell) - For Windows users only.
-      * **Important**: Ensure you can run `pwsh.exe` from a PowerShell terminal. If this fails, you likely need to upgrade PowerShell.
+    - [Azure Developer CLI](https://aka.ms/azure-dev/install)
+    - [Python 3.9, 3.10, or 3.11](https://www.python.org/downloads/)
+      - **Important**: Python and the pip package manager must be in the path in Windows for the setup scripts to work.
+      - **Important**: Ensure you can run `python --version` from console. On Ubuntu, you might need to run `sudo apt install python-is-python3` to link `python` to `python3`.
+    - [Node.js 14+](https://nodejs.org/en/download/)
+    - [Git](https://git-scm.com/downloads)
+    - [Powershell 7+ (pwsh)](https://github.com/powershell/powershell) - For Windows users only.
+      - **Important**: Ensure you can run `pwsh.exe` from a PowerShell terminal. If this fails, you likely need to upgrade PowerShell.
 
 2. Create a new folder and switch to it in the terminal.
 3. Run this command to download the project code:
@@ -146,8 +143,8 @@ Follow these steps to provision Azure resources and deploy the application code:
     This will create a new folder in the `.azure` folder, and set it as the active environment for any calls to `azd` going forward.
 1. (Optional) This is the point where you can customize the deployment by setting environment variables, in order to [use existing resources](docs/deploy_existing.md), [enable optional features (such as auth or vision)](docs/deploy_features.md), or [deploy to free tiers](docs/deploy_lowcost.md).
 1. Run `azd up` - This will provision Azure resources and deploy this sample to those resources, including building the search index based on the files found in the `./data` folder.
-    * **Important**: Beware that the resources created by this command will incur immediate costs, primarily from the AI Search resource. These resources may accrue costs even if you interrupt the command before it is fully executed. You can run `azd down` or delete the resources manually to avoid unnecessary spending.
-    * You will be prompted to select two locations, one for the majority of resources and one for the OpenAI resource, which is currently a short list. That location list is based on the [OpenAI model availability table](https://learn.microsoft.com/azure/cognitive-services/openai/concepts/models#model-summary-table-and-region-availability) and may become outdated as availability changes.
+    - **Important**: Beware that the resources created by this command will incur immediate costs, primarily from the AI Search resource. These resources may accrue costs even if you interrupt the command before it is fully executed. You can run `azd down` or delete the resources manually to avoid unnecessary spending.
+    - You will be prompted to select two locations, one for the majority of resources and one for the OpenAI resource, which is currently a short list. That location list is based on the [OpenAI model availability table](https://learn.microsoft.com/azure/cognitive-services/openai/concepts/models#model-summary-table-and-region-availability) and may become outdated as availability changes.
 1. After the application has been successfully deployed you will see a URL printed to the console.  Click that URL to interact with the application in your browser.
 It will look like the following:
 
@@ -165,7 +162,6 @@ If you've changed the infrastructure files (`infra` folder or `azure.yaml`), the
 
 ```azd up```
 
-
 ## Sharing environments
 
 To give someone else access to a completely deployed and existing environment,
@@ -190,14 +186,14 @@ See more tips in [the local development guide](docs/localdev.md).
 
 ## Using the app
 
-* In Azure: navigate to the Azure WebApp deployed by azd. The URL is printed out when azd completes (as "Endpoint"), or you can find it in the Azure portal.
-* Running locally: navigate to 127.0.0.1:50505
+- In Azure: navigate to the Azure WebApp deployed by azd. The URL is printed out when azd completes (as "Endpoint"), or you can find it in the Azure portal.
+- Running locally: navigate to 127.0.0.1:50505
 
 Once in the web app:
 
-* Try different topics in chat or Q&A context. For chat, try follow up questions, clarifications, ask to simplify or elaborate on answer, etc.
-* Explore citations and sources
-* Click on "settings" to try different options, tweak prompts, etc.
+- Try different topics in chat or Q&A context. For chat, try follow up questions, clarifications, ask to simplify or elaborate on answer, etc.
+- Explore citations and sources
+- Click on "settings" to try different options, tweak prompts, etc.
 
 ## Monitoring with Application Insights
 
@@ -254,15 +250,14 @@ Here are the most common failure scenarios and solutions:
 
 ## Resources
 
-* [Additional documentation for this app](docs/README.md)
-* [📖 Revolutionize your Enterprise Data with ChatGPT: Next-gen Apps w/ Azure OpenAI and AI Search](https://aka.ms/entgptsearchblog)
-* [📖 Azure AI Search](https://learn.microsoft.com/azure/search/search-what-is-azure-search)
-* [📖 Azure OpenAI Service](https://learn.microsoft.com/azure/cognitive-services/openai/overview)
-* [📖 Comparing Azure OpenAI and OpenAI](https://learn.microsoft.com/azure/cognitive-services/openai/overview#comparing-azure-openai-and-openai/)
-* [📖 Access Control in Generative AI applications with Azure Cognitive Search](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/access-control-in-generative-ai-applications-with-azure/ba-p/3956408)
-* [📺 Quickly build and deploy OpenAI apps on Azure, infused with your own data](https://www.youtube.com/watch?v=j8i-OM5kwiY)
-* [📺 AI Chat App Hack series](https://www.youtube.com/playlist?list=PL5lwDBUC0ag6_dGZst5m3G72ewfwXLcXV)
-
+- [Additional documentation for this app](docs/README.md)
+- [📖 Revolutionize your Enterprise Data with ChatGPT: Next-gen Apps w/ Azure OpenAI and AI Search](https://aka.ms/entgptsearchblog)
+- [📖 Azure AI Search](https://learn.microsoft.com/azure/search/search-what-is-azure-search)
+- [📖 Azure OpenAI Service](https://learn.microsoft.com/azure/cognitive-services/openai/overview)
+- [📖 Comparing Azure OpenAI and OpenAI](https://learn.microsoft.com/azure/cognitive-services/openai/overview#comparing-azure-openai-and-openai/)
+- [📖 Access Control in Generative AI applications with Azure Cognitive Search](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/access-control-in-generative-ai-applications-with-azure/ba-p/3956408)
+- [📺 Quickly build and deploy OpenAI apps on Azure, infused with your own data](https://www.youtube.com/watch?v=j8i-OM5kwiY)
+- [📺 AI Chat App Hack series](https://www.youtube.com/playlist?list=PL5lwDBUC0ag6_dGZst5m3G72ewfwXLcXV)
 
 ### Getting help
 

LICENSE.md

@@ -125,7 +125,7 @@ export function Component(): JSX.Element {
                         gpt4v_input: gpt4vInput
                     }
                 },
-                // ChatAppProtocol: Client must pass on any session state received from the server
+                // AI Chat Protocol: Client must pass on any session state received from the server
                 session_state: answer ? answer.session_state : null
             };
             const result = await askApi(request, token);

README.md

@@ -174,7 +174,7 @@ const Chat = () => {
                         gpt4v_input: gpt4vInput
                     }
                 },
-                // ChatAppProtocol: Client must pass on any session state received from the server
+                // AI Chat Protocol: Client must pass on any session state received from the server
                 session_state: answers.length ? answers[answers.length - 1][1].session_state : null
             };
 

app/frontend/src/pages/ask/Ask.tsx

@@ -4,12 +4,12 @@ Consult the main [README](../README.md) for general information about the projec
 These are advanced topics that are not necessary for a basic deployment.
 
 * [Deploying with the Azure Developer CLI](azd.md)
-    * [Deploying with existing Azure resources](deploy_existing.md)
-    * [Deploying from a free account](deploy_lowcost.md)
-    * [Enabling optional features](deploy_features.md)
-        * [Login and access control](login_and_acl.md)
-        * [GPT-4 Turbo with Vision](gpt4v.md)
-        * [Private endpoints](deploy_private.md)
+  * [Deploying with existing Azure resources](deploy_existing.md)
+  * [Deploying from a free account](deploy_lowcost.md)
+  * [Enabling optional features](deploy_features.md)
+    * [Login and access control](login_and_acl.md)
+    * [GPT-4 Turbo with Vision](gpt4v.md)
+    * [Private endpoints](deploy_private.md)
 * [Debugging the app on App Service](appservice.md)
 * [Local development](localdev.md)
 * [App customization](customization.md)

app/frontend/src/pages/chat/Chat.tsx

@@ -20,7 +20,7 @@ We recommend always waiting 10 minutes, to give the server time to properly star
 
 If you still see a 500 error after 10 minutes:
 
-1. [Check the deployment logs](#checking-the-deployment-logs)
+1. [Check the deployment logs](#checking-the-deployment-logs-for-errors)
 2. [Look for errors in the app logs](#checking-the-app-logs-for-errors)
 3. [Look for errors in Azure Monitor](#checking-azure-monitor-for-errors)
 
@@ -536,9 +536,9 @@ Done in 522 sec(s).
 
 Look for these important steps in the Oryx build:
 
-* _Detected following platforms: python: 3.11.7_
+- _Detected following platforms: python: 3.11.7_
     That should match your runtime in the App Service configuration.
-* _Running pip install..._
+- _Running pip install..._
     That should install all the requirements in your requirements.txt - if it didn't find your requirements.txt, then you won't see the packages installed.
 
 If you see all those steps in the Oryx build, then that's a good sign that the build went well, and you can move on to checking the App Service logs.
@@ -610,11 +610,11 @@ Open that file to see the full logs, with the most recent logs at the bottom.
 
 A few notable logs:
 
-* `2024-02-08T19:30:33.441385332Z Site's appCommandLine: python3 -m gunicorn main:app`
+- `2024-02-08T19:30:33.441385332Z Site's appCommandLine: python3 -m gunicorn main:app`
     This log indicates that App Service was correctly configured with a custom startup command to run the app.
-* `[2024-02-08 19:31:11 +0000] [75] [INFO] Starting gunicorn 20.1.0`
+- `[2024-02-08 19:31:11 +0000] [75] [INFO] Starting gunicorn 20.1.0`
     That's the start of the gunicorn server serving the app.
-* `2024-02-08T19:32:20.726942614Z [2024-02-08 19:32:20 +0000] [77] [INFO] Application startup complete.`
+- `2024-02-08T19:32:20.726942614Z [2024-02-08 19:32:20 +0000] [77] [INFO] Application startup complete.`
     At this point, the app has started successfully.
 
 If you do not see any errors in those logs, then the app should be running successfully. If you do see errors, then try looking in Azure Monitor.