refactor: use path-based vale rules instead of inline comments

btiernay · claude · btiernay · commit de1dae48016a · 2025-11-17T11:57:10.000-05:00
- Update .vale.ini with improved MDX parsing and path-based rules - Add scopes (IgnoredScopes/SkippedScopes) to skip code blocks and links - Configure TokenIgnores/BlockIgnores for import/export and JS expressions - Add path-specific rules for snippets, sample-apps, and components - Remove all 53 inline HTML vale comment lines across 27 files Benefits: - Cleaner, more maintainable documentation - Less noisy diffs going forward - Vale rules configured by content type, not per-block - Still passes with 0 errors, 0 warnings, 0 suggestions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/auth4genai/how-tos/list-github-repositories.mdx b/auth4genai/how-tos/list-github-repositories.mdx
@@ -4,7 +4,6 @@ description: "Use OpenAI, NextJS, and the Auth0-AI SDKs to list your GitHub repo
 mode: "wide"
 ---
 
-<!-- vale off -->
 import AISDKSample from "/snippets/how-tos/github/ai-sdk.mdx";
 import CloudflareAgents from "/snippets/how-tos/github/cloudflare-agents.mdx";
 import LangGraphJSSample from "/snippets/how-tos/github/langgraph.mdx";
@@ -13,7 +12,6 @@ import LlamaIndexSample from "/snippets/how-tos/github/llamaindex-python.mdx";
 import NextJSAuth0Sample from "/snippets/how-tos/github/nextjs-auth0.mdx";
 import GenKitSample from "/snippets/how-tos/github/genkit.mdx";
 import LlamaIndexJSSample from "/snippets/how-tos/github/llamaindex.mdx";
-<!-- vale on -->
 import AccountLinking from "/snippets/how-tos/account-linking.mdx";
 import CreateCustomApiClient from "/snippets/common/create-custom-api-client.mdx";
 
diff --git a/auth4genai/integrations/github.mdx b/auth4genai/integrations/github.mdx
@@ -24,13 +24,9 @@ GitHub apps [use fine grained permissions](https://docs.github.com/en/enterprise
 <Steps>
   <Step title="Set up app in GitHub">
     <ol>
-      <!-- vale off --> <li>
         Sign up for a [GitHub Developer account](https://github.com/signup)
-      </li> <!-- vale on -->
-      <!-- vale off --> <li>
         Set up a new GitHub app via [GitHub Developer Settings > GitHub
         Apps](https://github.com/settings/apps/new)
-      </li> <!-- vale on -->
       <li>
         Use the following settings when configuring your GitHub app:
         <ul>
diff --git a/auth4genai/mcp/sample-apps.mdx b/auth4genai/mcp/sample-apps.mdx
@@ -5,15 +5,12 @@ description: Explore sample MCP apps built using Auth for MCP.
 mode: "wide"
 ---
 
-<!-- vale off -->
 <Note>
   We value your feedback! To ask questions, report issues, or request new
   frameworks and providers, connect with us on
   [GitHub](https://github.com/auth0/auth-for-genai).
 </Note>
-<!-- vale on -->
 
-<!-- vale off -->
 <Columns cols={2}>
   <Card
     title="Task Vantage"
@@ -43,4 +40,3 @@ mode: "wide"
     Go further and explore our repository of standalone sample applications that showcase Auth0's authentication and authorization capabilities in MCP servers. Each sample demonstrates how to implement Auth for MCP in your MCP servers with different frameworks and different features that Auth0 offers.
   </Card>
 </Columns>
-<!-- vale on -->
diff --git a/auth4genai/sample-apps.mdx b/auth4genai/sample-apps.mdx
@@ -5,15 +5,12 @@ sidebarTitle: AI Agent Sample Apps
 mode: "wide"
 ---
 
-<!-- vale off -->
 <Note>
   We value your feedback! To ask questions, report issues, or request new
   frameworks and providers, connect with us on
   [GitHub](https://github.com/auth0/auth-for-genai).
 </Note>
-<!-- vale on -->
 
-<!-- vale off -->
 <Columns cols={2}>
   <Card
     title="Assistant0"
@@ -41,7 +38,6 @@ mode: "wide"
         [LlamaIndex + Next.js
         version](https://github.com/auth0-samples/auth0-assistant0/tree/main/ts-llamaindex)
       </li>
-      <!-- vale on -->
     </ul>
   </Card>
   <Card
@@ -80,4 +76,3 @@ mode: "wide"
     demonstrate recommended implementation patterns for the SDKs.
   </Card>
 </Columns>
-<!-- vale on -->
diff --git a/auth4genai/sdks/javascript-sdk.mdx b/auth4genai/sdks/javascript-sdk.mdx
@@ -92,7 +92,6 @@ Checkout our sample applications for JavaScript/TypeScript built with frameworks
     (Gmail, Google Calendar, etc) securely using Token Vault, Human-in-the-loop
     interactions using Asynchronous Authorization, and using Auth0 FGA for
     securing RAG tools.
-    <!-- vale off -->
     <ul className="list-disc list-inside pl-4">
       <li>
         [LangGraph
@@ -106,7 +105,6 @@ Checkout our sample applications for JavaScript/TypeScript built with frameworks
         [LlamaIndex
         version](https://github.com/auth0-samples/auth0-assistant0/tree/main/ts-llamaindex)
       </li>
-      <!-- vale on -->
     </ul>
   </Card>
   <Card
diff --git a/auth4genai/snippets/get-started/langchain-next-js/async-auth.mdx b/auth4genai/snippets/get-started/langchain-next-js/async-auth.mdx
@@ -152,11 +152,9 @@ export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
 ```
 
 ### Add Custom Authentication
-<!-- vale off -->
 <Info>
 For more information on how to add custom authentication for your LangGraph Platform application, read the [Custom Auth](https://langchain-ai.github.io/langgraphjs/how-tos/auth/custom_auth/) guide.
 </Info>
-<!-- vale on -->
 In your `langgraph.json`, add the path to your auth file:
 ```typescript langgraph.json wrap lines highlight={8}
 {
diff --git a/auth4genai/snippets/get-started/langchain-next-js/auth-for-rag.mdx b/auth4genai/snippets/get-started/langchain-next-js/auth-for-rag.mdx
@@ -180,11 +180,9 @@ export const getUser = async () => {
 ```
 
 ### Add Custom Authentication
-<!-- vale off -->
 <Info>
 For more information on how to add custom authentication for your LangGraph Platform application, read the [Custom Auth](https://langchain-ai.github.io/langgraphjs/how-tos/auth/custom_auth/) guide.
 </Info>
-<!-- vale on -->
 In your `langgraph.json`, add the path to your auth file:
 ```typescript langgraph.json wrap lines highlight={8}
 {
diff --git a/auth4genai/snippets/get-started/langchain-next-js/call-others-api.mdx b/auth4genai/snippets/get-started/langchain-next-js/call-others-api.mdx
@@ -216,11 +216,9 @@ export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
 ```
 
 ### Add Custom Authentication
-<!-- vale off -->
 <Info>
 For more information on how to add custom authentication for your LangGraph Platform application, read the [Custom Auth](https://langchain-ai.github.io/langgraphjs/how-tos/auth/custom_auth/) guide.
 </Info>
-<!-- vale on -->
 In your `langgraph.json`, add the path to your auth file:
 ```typescript langgraph.json wrap lines highlight={8}
 {
diff --git a/auth4genai/snippets/get-started/langchain-next-js/call-your-api.mdx b/auth4genai/snippets/get-started/langchain-next-js/call-your-api.mdx
@@ -74,11 +74,9 @@ export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
 ```
 
 ### Add Custom Authentication
-<!-- vale off -->
 <Info>
 For more information on how to add custom authentication for your LangGraph Platform application, read the [Custom Auth](https://langchain-ai.github.io/langgraphjs/how-tos/auth/custom_auth/) guide.
 </Info>
-<!-- vale on -->
 In your `langgraph.json`, add the path to your auth file:
 ```typescript langgraph.json wrap lines highlight={8}
 {
diff --git a/auth4genai/snippets/how-tos/github/ai-sdk.mdx b/auth4genai/snippets/how-tos/github/ai-sdk.mdx
@@ -26,12 +26,10 @@ export const withGitHub = auth0AI.withTokenVault({
 });
 ```
 
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 2. Integrate your tool with GitHub
 
diff --git a/auth4genai/snippets/how-tos/github/cloudflare-agents.mdx b/auth4genai/snippets/how-tos/github/cloudflare-agents.mdx
@@ -1,10 +1,8 @@
 ### 1. Configure Auth0 AI
 
-<!-- vale off -->
 <Note>
   If you started from the [Auth0 Cloudflare Agents starter kit](https://github.com/auth0-lab/cloudflare-agents-starter), you can skip this step as the Auth0 AI SDK is already configured.
 </Note>
-<!-- vale on -->
 
 First, you must configure your Cloudflare Agent to use Auth0 and both in the Worker and in the Chat Agent itself. We recommend the following two sdks:
 - [Auth0 Hono Web SDK](https://github.com/auth0-lab/auth0-hono): for the Worker.
diff --git a/auth4genai/snippets/how-tos/github/genkit.mdx b/auth4genai/snippets/how-tos/github/genkit.mdx
@@ -30,12 +30,10 @@ export const withGitHub = auth0AI.withTokenVault({
 });
 
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 2. Integrate your tool with GitHub
 
diff --git a/auth4genai/snippets/how-tos/github/langgraph-python.mdx b/auth4genai/snippets/how-tos/github/langgraph-python.mdx
@@ -160,12 +160,10 @@ export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
     },
   });
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 #### Client Side
 
diff --git a/auth4genai/snippets/how-tos/github/langgraph.mdx b/auth4genai/snippets/how-tos/github/langgraph.mdx
@@ -184,7 +184,6 @@ export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
 
 
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
@@ -194,7 +193,6 @@ You can check different authentication options for Next.js with Auth0 at the [of
 <Info>
 For more information on how to add custom authentication for your LangGraph Platform application, see the [Custom Auth](https://langchain-ai.github.io/langgraphjs/how-tos/auth/custom_auth/) guide.
 </Info>
-<!-- vale on -->
 In your langgraph.json, add the path to your auth file:
 ```typescript langgraph.json wrap lines highlight={8}
 {
diff --git a/auth4genai/snippets/how-tos/github/llamaindex.mdx b/auth4genai/snippets/how-tos/github/llamaindex.mdx
@@ -25,12 +25,10 @@ export const withGitHub = auth0AI.withTokenVault({
 });
 
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 2. Integrate your tool with GitHub
 
diff --git a/auth4genai/snippets/how-tos/github/nextjs-auth0.mdx b/auth4genai/snippets/how-tos/github/nextjs-auth0.mdx
@@ -39,12 +39,10 @@ export const listRepos = tool({
   }
 });
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 3. Set up the API route for the chat
 
diff --git a/auth4genai/snippets/how-tos/google-calendar/ai-sdk.mdx b/auth4genai/snippets/how-tos/google-calendar/ai-sdk.mdx
@@ -27,12 +27,10 @@ export const withGoogleCalendar = auth0AI.withTokenVault({
 });
 ```
 
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 2. Integrate your tool with Google Calendar
 
diff --git a/auth4genai/snippets/how-tos/google-calendar/genkit.mdx b/auth4genai/snippets/how-tos/google-calendar/genkit.mdx
@@ -29,12 +29,10 @@ export const withGoogleCalendar = auth0AI.withTokenVault({
   },
 });
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 2. Integrate your tool with Google Calendar
 
diff --git a/auth4genai/snippets/how-tos/google-calendar/langgraph-python.mdx b/auth4genai/snippets/how-tos/google-calendar/langgraph-python.mdx
@@ -173,12 +173,10 @@ export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
     },
   });
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 #### Client Side
 
diff --git a/auth4genai/snippets/how-tos/google-calendar/langgraph.mdx b/auth4genai/snippets/how-tos/google-calendar/langgraph.mdx
@@ -205,10 +205,8 @@ You can check different authentication options for Next.js with Auth0 at the [of
 :::
 
 ### Add Custom Authentication
-<!-- vale off -->
 <Info>
 For more information on how to add custom authentication for your LangGraph Platform application, see the [Custom Auth](https://langchain-ai.github.io/langgraphjs/how-tos/auth/custom_auth/) guide.
-</Info><!-- vale on -->
 In your langgraph.json, add the path to your auth file:
 ```typescript langgraph.json wrap lines highlight={8}
 {
diff --git a/auth4genai/snippets/how-tos/google-calendar/llamaindex.mdx b/auth4genai/snippets/how-tos/google-calendar/llamaindex.mdx
@@ -25,12 +25,10 @@ export const withGoogleCalendar = auth0AI.withTokenVault({
   },
 });
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 2. Integrate your tool with GitHub
 
diff --git a/auth4genai/snippets/how-tos/google-calendar/nextjs-auth0.mdx b/auth4genai/snippets/how-tos/google-calendar/nextjs-auth0.mdx
@@ -44,12 +44,10 @@ export const checkUsersCalendar = tool({
   }
 });
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 3. Set up the API route for the chat
 
diff --git a/auth4genai/snippets/how-tos/slack/ai-sdk.mdx b/auth4genai/snippets/how-tos/slack/ai-sdk.mdx
@@ -25,12 +25,10 @@ export const withSlack = auth0AI.withTokenVault({
   },
 });
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 2. Integrate your tool with Slack
 
diff --git a/auth4genai/snippets/how-tos/slack/genkit.mdx b/auth4genai/snippets/how-tos/slack/genkit.mdx
@@ -29,12 +29,10 @@ export const withSlack = auth0AI.withTokenVault({
   },
 });
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 2. Integrate your tool with Slack
 
diff --git a/auth4genai/snippets/how-tos/slack/langgraph-python.mdx b/auth4genai/snippets/how-tos/slack/langgraph-python.mdx
@@ -167,12 +167,10 @@ export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
     },
   });
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 #### Client Side
 
diff --git a/auth4genai/snippets/how-tos/slack/langgraph.mdx b/auth4genai/snippets/how-tos/slack/langgraph.mdx
@@ -186,7 +186,6 @@ export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
 
 
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
@@ -196,7 +195,6 @@ You can check different authentication options for Next.js with Auth0 at the [of
 <Info>
 For more information on how to add custom authentication for your LangGraph Platform application, see the [Custom Auth](https://langchain-ai.github.io/langgraphjs/how-tos/auth/custom_auth/) guide.
 </Info>
-<!-- vale on -->
 In your langgraph.json, add the path to your auth file:
 ```typescript langgraph.json wrap lines highlight={8}
 {
diff --git a/auth4genai/snippets/how-tos/slack/llamaindex.mdx b/auth4genai/snippets/how-tos/slack/llamaindex.mdx
@@ -25,12 +25,10 @@ export const withSlack = auth0AI.withTokenVault({
 });
 
 ```
-<!-- vale off -->
 <Info>
 Here, the property `auth0` is an instance of `@auth0/nextjs-auth0` to handle the application auth flows. <br/>
 You can check different authentication options for Next.js with Auth0 at the [official documentation.](https://github.com/auth0/nextjs-auth0?tab=readme-ov-file#3-create-the-auth0-sdk-client)
 </Info>
-<!-- vale on -->
 
 ### 2. Integrate your tool with GitHub
 
