feat: tutorials for kvm and lima, description in overviews, overview page rework

docs/.vitepress/sidebar.ts

@@ -19,31 +19,59 @@ export function generateDocumentationSidebar(): any {
     prefixSeparator: '/',
   });
 
-  // Post-process sidebar to fix folder titles for single-file directories
-  // When a folder only has index.md, vitepress-sidebar may not apply the frontmatter title correctly
+  // Post-process sidebar to fix folder titles and extract descriptions from frontmatter
   const fixFolderTitles = (items: any[]): any[] => {
     return items.map(item => {
+      let frontmatter: Record<string, any> | undefined;
+
       if (item.link && item.link.endsWith('/')) {
-        // This is a folder link - try to read title from its index.md
+        // This is a folder link - read frontmatter from its index.md
         const indexPath = path.join('docs', item.link, 'index.md');
         if (fs.existsSync(indexPath)) {
           try {
             const content = fs.readFileSync(indexPath, 'utf-8');
-            const { data } = matter(content);
-            if (data.title) {
-              item.text = data.title;
+            frontmatter = matter(content).data;
+            if (frontmatter?.title) {
+              item.text = frontmatter.title;
             }
           } catch (err) {
             // Ignore errors, keep the original text
           }
         }
+      } else if (item.link && item.link.endsWith('.md')) {
+        // This is a file link - read frontmatter from the page
+        const pagePath = path.join('docs', item.link);
+        if (fs.existsSync(pagePath)) {
+          try {
+            const content = fs.readFileSync(pagePath, 'utf-8');
+            frontmatter = matter(content).data;
+          } catch (err) {
+            // Ignore errors
+          }
+        }
+      } else if (item.link && !item.link.includes('.')) {
+        // Link has no extension (vitepress-sidebar strips .md for leaf pages)
+        // Try appending .md to find the source file
+        const pagePath = path.join('docs', item.link + '.md');
+        if (fs.existsSync(pagePath)) {
+          try {
+            const content = fs.readFileSync(pagePath, 'utf-8');
+            frontmatter = matter(content).data;
+          } catch (err) {
+            // Ignore errors
+          }
+        }
+      }
+
+      if (frontmatter?.description) {
+        item.description = frontmatter.description;
       }
-      
+
       // Recursively fix nested items
       if (item.items && Array.isArray(item.items)) {
         item.items = fixFolderTitles(item.items);
       }
-      
+
       return item;
     });
   };

docs/.vitepress/theme/components/SectionIndex.vue

@@ -2,21 +2,25 @@
 import { useData } from "vitepress";
 import { computed } from "vue";
 
-const { page, theme } = useData();
+const { page, theme, frontmatter } = useData();
 
 interface SidebarItem {
   text: string;
+  description?: string;
   link?: string;
   items?: SidebarItem[];
 }
 
 interface TreeNode {
   text: string;
+  description?: string;
   link?: string;
   depth: number;
   children?: TreeNode[];
 }
 
+const showDescriptions = computed(() => frontmatter.value.overviewDescriptions !== false);
+
 // Get the current directory path from the current page
 // e.g., 'how-to/' for how-to/index.md or 'how-to/platform-specific/' for how-to/platform-specific/index.md
 const currentDirectory = computed(() => {
@@ -103,6 +107,7 @@ const sectionItems = computed(() => {
           }
           flattened.push({
             text: item.text,
+            description: item.description,
             link: formattedLink,
             depth: 2, // Treat as depth 2 (child of sub-group)
           });
@@ -139,6 +144,7 @@ const sectionItems = computed(() => {
           }
           nodes.push({
             text: item.text,
+            description: item.description,
             link: formattedLink,
             depth,
             children,
@@ -154,6 +160,7 @@ const sectionItems = computed(() => {
         }
         nodes.push({
           text: item.text,
+          description: item.description,
           link: formattedLink,
           depth,
         });
@@ -187,15 +194,21 @@ const sectionName = computed(() => {
           class="section-item"
           :class="`depth-${node.depth}`">
           <a :href="node.link">{{ node.text }}</a>
+          <span
+            v-if="showDescriptions && node.description"
+            class="section-item-description">{{ node.description }}</span>
         </div>
 
         <!-- Group node (has children) -->
         <div v-else class="section-group" :class="`depth-${node.depth}`">
           <!-- Group header -->
           <div class="section-group-header">
-            <a v-if="node.link" :href="node.link" class="group-link">{{
-              node.text
-            }}</a>
+            <template v-if="node.link">
+              <a :href="node.link" class="group-link">{{ node.text }}</a>
+              <span
+                v-if="showDescriptions && node.description"
+                class="section-item-description">{{ node.description }}</span>
+            </template>
             <span v-else class="group-title">{{ node.text }}</span>
           </div>
 
@@ -210,14 +223,20 @@ const sectionName = computed(() => {
                 class="section-item"
                 :class="`depth-${child.depth}`">
                 <a :href="child.link">{{ child.text }}</a>
+                <span
+                  v-if="showDescriptions && child.description"
+                  class="section-item-description">{{ child.description }}</span>
               </div>
 
               <!-- Child group node (level 3) -->
               <div v-else class="section-group" :class="`depth-${child.depth}`">
                 <div class="section-group-header">
-                  <a v-if="child.link" :href="child.link" class="group-link">{{
-                    child.text
-                  }}</a>
+                  <template v-if="child.link">
+                    <a :href="child.link" class="group-link">{{ child.text }}</a>
+                    <span
+                      v-if="showDescriptions && child.description"
+                      class="section-item-description">{{ child.description }}</span>
+                  </template>
                   <span v-else class="group-title">{{ child.text }}</span>
                 </div>
 
@@ -229,6 +248,9 @@ const sectionName = computed(() => {
                     class="section-item"
                     :class="`depth-${grandchild.depth}`">
                     <a :href="grandchild.link">{{ grandchild.text }}</a>
+                    <span
+                      v-if="showDescriptions && grandchild.description"
+                      class="section-item-description">{{ grandchild.description }}</span>
                   </div>
                 </div>
               </div>
@@ -368,6 +390,19 @@ const sectionName = computed(() => {
   transform: translateX(2px);
 }
 
+.section-item-description {
+  display: block;
+  font-size: 0.85rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.5;
+  padding: 0 0.75rem;
+  margin-top: 0.25rem;
+}
+
+.section-group-header .section-item-description {
+  padding: 0;
+}
+
 /* Depth-specific styling for items */
 .section-item.depth-1 a {
   font-size: 0.95rem;

docs/explanation/documentation/aggregation-architecture.md

@@ -279,7 +279,6 @@ Temp Directory                 Docs Output
 
 ## See Also
 
-- [Getting Started Tutorial](../../tutorials/documentation/index.md) — Step-by-step guide to contributing documentation
 - [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repositories to the aggregation
 - [Technical Reference](../../reference/documentation/technical.md) — Source code and API documentation
 - [Configuration Reference](../../reference/documentation/configuration.md) — Complete configuration options

docs/how-to/documentation/adding-repos.md

@@ -248,7 +248,6 @@ Here's a complete configuration:
 
 ## See Also
 
-- [Getting Started Tutorial](../../tutorials/documentation/index.md) — Step-by-step guide to contributing documentation
 - [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repositories to the aggregation
 - [Technical Reference](../../reference/documentation/technical.md) — Source code and API documentation
 - [Configuration Reference](../../reference/documentation/configuration.md) — Complete configuration options