diff --git a/scripts/generate-markdown.ts b/scripts/generate-markdown.ts
index 53ae04c8..b1f41736 100644
--- a/scripts/generate-markdown.ts
+++ b/scripts/generate-markdown.ts
@@ -1,4 +1,4 @@
-import { writeFileSync } from 'fs';
+import { readFileSync, writeFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { ApiModel } from '@microsoft/api-extractor-model';
 import { CustomMarkdownDocumenter } from './libs/CustomMarkdownDocumenter';
@@ -19,14 +19,12 @@ function build(): void {
 
   markdown.generateFiles();
 
-  const categoryForApiFolder = {
-    label: 'Introduction',
-    position: -1,
-  };
+  const filename = join(outputFolder, 'Introduction.md');
+  const introductionMarkdownContent = readFileSync(filename);
 
-  const filename = join(outputFolder, 'Introduction', '_category_.json');
+  const introductionContent = `---\ntitle: Introduction\nsidebar_position: -1\n---${introductionMarkdownContent}`;
 
-  writeFileSync(filename, JSON.stringify(categoryForApiFolder, null, 2));
+  writeFileSync(filename, introductionContent);
 }
 
 build();
diff --git a/scripts/libs/CustomMarkdownDocumenter.ts b/scripts/libs/CustomMarkdownDocumenter.ts
index dd96c9a5..c20143f6 100644
--- a/scripts/libs/CustomMarkdownDocumenter.ts
+++ b/scripts/libs/CustomMarkdownDocumenter.ts
@@ -320,7 +320,7 @@ export class CustomMarkdownDocumenter {
 
     const filename: string = path.join(
       this._outputFolder,
-      this._getFilenameForApiItem(apiItem),
+      this._getFilenameForApiItem(apiItem, true),
     );
     const stringBuilder: StringBuilder = new StringBuilder();
 
@@ -1155,7 +1155,10 @@ export class CustomMarkdownDocumenter {
     }
   }
 
-  private _getFilenameForApiItem(apiItem: ApiItem): string {
+  private _getFilenameForApiItem(
+    apiItem: ApiItem,
+    nestedWhenSameName: boolean = false,
+  ): string {
     if (apiItem.kind === ApiItemKind.Model) {
       // this file will be ignored, we don't like the old index file.
       return 'ignored.md';
@@ -1184,7 +1187,16 @@ export class CustomMarkdownDocumenter {
         const safeName = CustomUtilities.getSafeFilenameForNameWithCase(
           apiItem.displayName,
         );
-        const filename = safeName + '.md';
+
+        if (breadcrumbs.length === 0) return safeName + '.md';
+
+        const filename =
+          !nestedWhenSameName &&
+          breadcrumbs[breadcrumbs.length - 1] === safeName
+            ? ''
+            : safeName + '.md';
+
+        if (!filename) return breadcrumbs.join('/') + '.md';
 
         return [...breadcrumbs, filename].join('/');
       }
@@ -1219,13 +1231,18 @@ export class CustomMarkdownDocumenter {
     }
 
     // when we don't have name, usually is the package documentation
-    if (!baseName) return 'Introduction/Introduction.md';
+    if (!baseName) return 'Introduction.md';
 
     return baseName + '.md';
   }
 
   private _getLinkFilenameForApiItem(apiItem: ApiItem): string {
-    return '/docs/api/' + this._getFilenameForApiItem(apiItem);
+    return (
+      '/docs/api/' +
+      this._getFilenameForApiItem(apiItem)
+        .replace(/\.md/g, '')
+        .replace(/ /g, '%20')
+    );
   }
 
   private _deleteOldOutputFiles(): void {