refactor: make introduction the index page

CalvinAllen · CalvinAllen · commit 3534fb60d8bb · 2026-01-29T15:30:32.000-05:00
- Index now renders introduction content directly (no redirect)
- Sidebar links to / for introduction
- Fixed all internal links to use flat URL structure
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
@@ -2,7 +2,13 @@
   "permissions": {
     "allow": [
       "Bash(npm run build:*)",
-      "Bash(npm run dev:*)"
+      "Bash(npm run dev:*)",
+      "Bash(gh label:*)",
+      "Bash(gh label create:*)",
+      "Bash(gh issue create:*)",
+      "Bash(gh issue list:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
     ]
   }
 }
diff --git a/src/content/docs/advanced-overview.mdx b/src/content/docs/advanced-overview.mdx
@@ -13,21 +13,21 @@ This section covers advanced extension development topics for developers who wan
 
 | Topic | Description |
 |-------|-------------|
-| [MEF Components](/docs/advanced/mef-components) | Editor extensions using Managed Extensibility Framework |
-| [Language Services](/docs/advanced/language-services) | IntelliSense, syntax highlighting, and code navigation |
-| [Debugger Integration](/docs/advanced/debugger-integration) | Custom debug engines and visualizers |
-| [Source Control](/docs/advanced/source-control) | Version control provider integration |
-| [Project Types](/docs/advanced/project-types) | Custom project systems |
-| [Performance](/docs/advanced/performance) | Optimization techniques and best practices |
+| [MEF Components](mef-components) | Editor extensions using Managed Extensibility Framework |
+| [Language Services](language-services) | IntelliSense, syntax highlighting, and code navigation |
+| [Debugger Integration](debugger-integration) | Custom debug engines and visualizers |
+| [Source Control](source-control) | Version control provider integration |
+| [Project Types](project-types) | Custom project systems |
+| [Performance](performance) | Optimization techniques and best practices |
 
 ## Prerequisites
 
 Before diving into advanced topics, ensure you're comfortable with:
 
-- [Service Provider](/docs/fundamentals/service-provider) patterns
-- [Packages](/docs/fundamentals/packages) and registration
-- [Commands](/docs/fundamentals/commands) and UI
-- [Async Services](/docs/fundamentals/async-services) and threading
+- [Service Provider](service-provider) patterns
+- [Packages](packages) and registration
+- [Commands](commands) and UI
+- [Async Services](async-services) and threading
 
 ## Advanced Architecture
 
@@ -207,4 +207,4 @@ For advanced scenarios:
 
 ## Next Steps
 
-Start with [MEF Components](/docs/advanced/mef-components) to learn about editor extensibility through composition.
+Start with [MEF Components](mef-components) to learn about editor extensibility through composition.
diff --git a/src/content/docs/async-services.mdx b/src/content/docs/async-services.mdx
@@ -380,4 +380,4 @@ public sealed class MyPackage : AsyncPackage
 
 ## Next Steps
 
-You've completed the Fundamentals section! Continue to [Advanced Topics](/docs/advanced/overview) to learn about MEF components, language services, and more.
+You've completed the Fundamentals section! Continue to [Advanced Topics](/advanced-overview) to learn about MEF components, language services, and more.
diff --git a/src/content/docs/commands.mdx b/src/content/docs/commands.mdx
@@ -357,4 +357,4 @@ internal sealed class FormatDocumentCommand : BaseCommand<FormatDocumentCommand>
 
 ## Next Steps
 
-Learn about [Tool Windows](/docs/fundamentals/tool-windows) to create dockable UI panels.
+Learn about [Tool Windows](tool-windows) to create dockable UI panels.
diff --git a/src/content/docs/debugger-integration.mdx b/src/content/docs/debugger-integration.mdx
@@ -316,4 +316,4 @@ dte.ExecuteCommand("Debug.Restart");
 
 ## Next Steps
 
-Learn about [Source Control](/docs/advanced/source-control) integration for version control providers.
+Learn about [Source Control](source-control) integration for version control providers.
diff --git a/src/content/docs/debugging.mdx b/src/content/docs/debugging.mdx
@@ -159,4 +159,4 @@ The `/rootsuffix Exp` argument launches the Experimental Instance.
 
 ## Next Steps
 
-Once your extension is working, learn about [Packaging and Publishing](/docs/getting-started/packaging) to share it with others.
+Once your extension is working, learn about [Packaging and Publishing](packaging) to share it with others.
diff --git a/src/content/docs/editors.mdx b/src/content/docs/editors.mdx
@@ -289,7 +289,7 @@ internal sealed class MyClassifier : IClassifier
 ```
 
 <Callout type="note">
-For syntax highlighting of specific file types, see [Language Services](/docs/advanced/language-services).
+For syntax highlighting of specific file types, see [Language Services](language-services).
 </Callout>
 
 ## Quick Actions (Light Bulbs)
@@ -396,4 +396,4 @@ internal sealed class EditorEventListener : IWpfTextViewCreationListener
 
 ## Next Steps
 
-Learn about [Options Pages](/docs/fundamentals/options-pages) to add settings to Tools > Options.
+Learn about [Options Pages](options-pages) to add settings to Tools > Options.
diff --git a/src/content/docs/first-extension.mdx b/src/content/docs/first-extension.mdx
@@ -162,4 +162,4 @@ This version displays the current file name instead of a static message.
 
 ## Next Steps
 
-Now that you have a working extension, learn about the [Project Structure](/docs/getting-started/project-structure) to understand all the files in your VSIX project.
+Now that you have a working extension, learn about the [Project Structure](project-structure) to understand all the files in your VSIX project.
diff --git a/src/content/docs/introduction.mdx b/src/content/docs/introduction.mdx
@@ -59,4 +59,4 @@ For new extensions, we recommend starting with the Community Toolkit. You can al
 
 ## Next Steps
 
-Ready to start building? Continue to [Prerequisites](/docs/getting-started/prerequisites) to set up your development environment.
+Ready to start building? Continue to [Prerequisites](/prerequisites) to set up your development environment.
diff --git a/src/content/docs/language-services.mdx b/src/content/docs/language-services.mdx
@@ -454,4 +454,4 @@ internal sealed class BraceMatchingTagger : ITagger<TextMarkerTag>
 
 ## Next Steps
 
-Learn about [Debugger Integration](/docs/advanced/debugger-integration) to extend VS debugging capabilities.
+Learn about [Debugger Integration](debugger-integration) to extend VS debugging capabilities.
diff --git a/src/content/docs/mef-components.mdx b/src/content/docs/mef-components.mdx
@@ -445,4 +445,4 @@ internal sealed class MyComponent : IDisposable
 
 ## Next Steps
 
-Learn about [Language Services](/docs/advanced/language-services) for complete language support including IntelliSense and navigation.
+Learn about [Language Services](language-services) for complete language support including IntelliSense and navigation.
diff --git a/src/content/docs/options-pages.mdx b/src/content/docs/options-pages.mdx
@@ -352,4 +352,4 @@ internal sealed class MyCommand : BaseCommand<MyCommand>
 
 ## Next Steps
 
-Learn about [Async Services](/docs/fundamentals/async-services) for background loading patterns.
+Learn about [Async Services](async-services) for background loading patterns.
diff --git a/src/content/docs/packages.mdx b/src/content/docs/packages.mdx
@@ -280,4 +280,4 @@ public sealed class MyPackage : ToolkitPackage
 
 ## Next Steps
 
-Learn how to add [Commands](/docs/fundamentals/commands) to your extension.
+Learn how to add [Commands](commands) to your extension.
diff --git a/src/content/docs/packaging.mdx b/src/content/docs/packaging.mdx
@@ -169,4 +169,4 @@ Host a private Atom feed:
 
 ## Next Steps
 
-Congratulations! You've completed the Getting Started section. Continue to [Fundamentals](/docs/fundamentals/overview) to learn about VS architecture and services.
+Congratulations! You've completed the Getting Started section. Continue to [Fundamentals](/fundamentals-overview) to learn about VS architecture and services.
diff --git a/src/content/docs/performance.mdx b/src/content/docs/performance.mdx
@@ -436,4 +436,4 @@ Before releasing your extension:
 
 ## Next Steps
 
-You've completed the Advanced section! Check out the [Reference](/docs/reference/services) documentation for detailed API information.
+You've completed the Advanced section! Check out the [Reference](services) documentation for detailed API information.
diff --git a/src/content/docs/prerequisites.mdx b/src/content/docs/prerequisites.mdx
@@ -79,4 +79,4 @@ If you see the templates, you're ready to create your first extension!
 
 ## Next Steps
 
-Continue to [Your First Extension](/docs/getting-started/first-extension) to create a simple "Hello World" command.
+Continue to [Your First Extension](first-extension) to create a simple "Hello World" command.
diff --git a/src/content/docs/project-structure.mdx b/src/content/docs/project-structure.mdx
@@ -194,4 +194,4 @@ When you build, these files are generated:
 
 ## Next Steps
 
-Learn how to [Debug Your Extension](/docs/getting-started/debugging) using the Experimental Instance.
+Learn how to [Debug Your Extension](debugging) using the Experimental Instance.
diff --git a/src/content/docs/project-types.mdx b/src/content/docs/project-types.mdx
@@ -355,4 +355,4 @@ public class MyBuildManager
 
 ## Next Steps
 
-Learn about [Performance](/docs/advanced/performance) best practices for VS extensions.
+Learn about [Performance](performance) best practices for VS extensions.
diff --git a/src/content/docs/service-provider.mdx b/src/content/docs/service-provider.mdx
@@ -241,4 +241,4 @@ public sealed class MyPackage : AsyncPackage
 
 ## Next Steps
 
-Learn about [Packages](/docs/fundamentals/packages) to understand how to structure your extension's entry point.
+Learn about [Packages](packages) to understand how to structure your extension's entry point.
diff --git a/src/content/docs/source-control.mdx b/src/content/docs/source-control.mdx
@@ -295,4 +295,4 @@ Modern Git integration in VS is sophisticated. Consider extending existing Git f
 
 ## Next Steps
 
-Learn about [Custom Project Types](/docs/advanced/project-types) to create new project systems.
+Learn about [Custom Project Types](project-types) to create new project systems.
diff --git a/src/content/docs/tool-windows.mdx b/src/content/docs/tool-windows.mdx
@@ -333,4 +333,4 @@ public partial class SolutionExplorerControl : UserControl
 
 ## Next Steps
 
-Learn about extending the [Code Editor](/docs/fundamentals/editors) with custom features.
+Learn about extending the [Code Editor](editors) with custom features.
diff --git a/src/layouts/DocLayout.astro b/src/layouts/DocLayout.astro
@@ -42,8 +42,8 @@ const currentPath = Astro.url.pathname.replace(/\/$/, '');
                 <>
                   <div class="sidebar-category">{category.label}</div>
                   {category.docs.map((doc) => {
-                    const href = `/${doc.id}`;
-                    const isActive = currentPath === href;
+                    const href = doc.id === 'introduction' ? '/' : `/${doc.id}`;
+                    const isActive = currentPath === href || (doc.id === 'introduction' && currentPath === '');
                     return (
                       <a
                         href={href}
@@ -72,8 +72,8 @@ const currentPath = Astro.url.pathname.replace(/\/$/, '');
                 <>
                   <div class="sidebar-category">{category.label}</div>
                   {category.docs.map((doc) => {
-                    const href = `/${doc.id}`;
-                    const isActive = currentPath === href;
+                    const href = doc.id === 'introduction' ? '/' : `/${doc.id}`;
+                    const isActive = currentPath === href || (doc.id === 'introduction' && currentPath === '');
                     return (
                       <a
                         href={href}
diff --git a/src/pages/index.astro b/src/pages/index.astro
@@ -1,3 +1,11 @@
 ---
-return Astro.redirect('/introduction');
+import { getEntry, render } from 'astro:content';
+import DocLayout from '@layouts/DocLayout.astro';
+
+const doc = await getEntry('docs', 'introduction');
+const { Content } = await render(doc);
 ---
+
+<DocLayout title={doc.data.title} description={doc.data.description}>
+  <Content />
+</DocLayout>

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,13 @@`
`2`	`2`	`"permissions": {`
`3`	`3`	`"allow": [`
`4`	`4`	`"Bash(npm run build:*)",`
`5`		`- "Bash(npm run dev:*)"`
	`5`	`+ "Bash(npm run dev:*)",`
	`6`	`+ "Bash(gh label:*)",`
	`7`	`+ "Bash(gh label create:*)",`
	`8`	`+ "Bash(gh issue create:*)",`
	`9`	`+ "Bash(gh issue list:*)",`
	`10`	`+ "Bash(git add:*)",`
	`11`	`+ "Bash(git commit:*)"`
`6`	`12`	`]`
`7`	`13`	`}`
`8`	`14`	`}`
Original file line number	Diff line number	Diff line change
`@@ -380,4 +380,4 @@ public sealed class MyPackage : AsyncPackage`
`380`	`380`
`381`	`381`	`## Next Steps`
`382`	`382`
`383`		`-You've completed the Fundamentals section! Continue to [Advanced Topics](/docs/advanced/overview) to learn about MEF components, language services, and more.`
	`383`	`+You've completed the Fundamentals section! Continue to [Advanced Topics](/advanced-overview) to learn about MEF components, language services, and more.`
Original file line number	Diff line number	Diff line change
`@@ -357,4 +357,4 @@ internal sealed class FormatDocumentCommand : BaseCommand<FormatDocumentCommand>`
`357`	`357`
`358`	`358`	`## Next Steps`
`359`	`359`
`360`		`-Learn about [Tool Windows](/docs/fundamentals/tool-windows) to create dockable UI panels.`
	`360`	`+Learn about [Tool Windows](tool-windows) to create dockable UI panels.`
Original file line number	Diff line number	Diff line change
`@@ -316,4 +316,4 @@ dte.ExecuteCommand("Debug.Restart");`
`316`	`316`
`317`	`317`	`## Next Steps`
`318`	`318`
`319`		`-Learn about [Source Control](/docs/advanced/source-control) integration for version control providers.`
	`319`	`+Learn about [Source Control](source-control) integration for version control providers.`
Original file line number	Diff line number	Diff line change
@@ -159,4 +159,4 @@ The `/rootsuffix Exp` argument launches the Experimental Instance.
`159`	`159`
`160`	`160`	`## Next Steps`
`161`	`161`
`162`		`-Once your extension is working, learn about [Packaging and Publishing](/docs/getting-started/packaging) to share it with others.`
	`162`	`+Once your extension is working, learn about [Packaging and Publishing](packaging) to share it with others.`
Original file line number	Diff line number	Diff line change
`@@ -162,4 +162,4 @@ This version displays the current file name instead of a static message.`
`162`	`162`
`163`	`163`	`## Next Steps`
`164`	`164`
`165`		`-Now that you have a working extension, learn about the [Project Structure](/docs/getting-started/project-structure) to understand all the files in your VSIX project.`
	`165`	`+Now that you have a working extension, learn about the [Project Structure](project-structure) to understand all the files in your VSIX project.`
Original file line number	Diff line number	Diff line change
`@@ -59,4 +59,4 @@ For new extensions, we recommend starting with the Community Toolkit. You can al`
`59`	`59`
`60`	`60`	`## Next Steps`
`61`	`61`
`62`		`-Ready to start building? Continue to [Prerequisites](/docs/getting-started/prerequisites) to set up your development environment.`
	`62`	`+Ready to start building? Continue to [Prerequisites](/prerequisites) to set up your development environment.`
Original file line number	Diff line number	Diff line change
`@@ -454,4 +454,4 @@ internal sealed class BraceMatchingTagger : ITagger<TextMarkerTag>`
`454`	`454`
`455`	`455`	`## Next Steps`
`456`	`456`
`457`		`-Learn about [Debugger Integration](/docs/advanced/debugger-integration) to extend VS debugging capabilities.`
	`457`	`+Learn about [Debugger Integration](debugger-integration) to extend VS debugging capabilities.`