279: Generate sidebar nav items from the scanned md files

docs/.vitepress/config.mts

@@ -1,13 +1,13 @@
 import { URL, fileURLToPath } from 'node:url'
 import { resolve } from 'path'
 import { defineConfig } from 'vitepress'
+import { getSidebarItemsFromMdFiles } from './utils.mts'
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   appearance: 'force-dark',
   srcDir: 'src',
   title: 'KitOps',
-  titleTemplate: 'KitOps',
   description: 'Documentation for KitOps',
 
   head: [
@@ -51,7 +51,6 @@ export default defineConfig({
         text: 'Getting started',
         items: [
           { text: 'Overview', link: '/docs/overview' },
-          { text: 'Installation', link: '/docs/cli/installation' },
           { text: 'Use Cases', link: '/docs/use-cases' },
           { text: 'Why KitOps?', link: '/docs/why-kitops' },
         ]
@@ -72,10 +71,13 @@ export default defineConfig({
       },
       {
         text: 'CLI',
-        items: [
-          { text: 'Download & Install', link: '/docs/cli/installation' },
-          { text: 'Command Reference', link: '/docs/cli/kit' },
-        ]
+        items: getSidebarItemsFromMdFiles('docs/cli', {
+            replacements: {
+              'cli-reference': 'Command Reference' ,
+              'installation': 'Download & Install'
+            },
+            textFormat: (text) => text.replaceAll('cli-', '')
+          })
       },
       {
         text: 'MLOps with Kitfile',

docs/.vitepress/theme/components/Home.vue

@@ -8,7 +8,7 @@ import { VueMarqueeSlider } from 'vue3-marquee-slider'
   <p class="h4 !font-normal !text-off-white">Share and run your models anywhere</p>
   <h1 class="mt-4">Bridge the gap between ML and Application teams</h1>
 
-  <a href="/docs/installation" class="kit-button mt-10 md:mt-14 xl:mt-22">Install</a>
+  <a href="/docs/cli/installation" class="kit-button mt-10 md:mt-14 xl:mt-22">Install</a>
 </div>
 
 <div class="mt-32 md:mt-40 xl:mt-60 px-6 text-center max-w-[1152px] mx-auto">
@@ -83,23 +83,23 @@ import { VueMarqueeSlider } from 'vue3-marquee-slider'
       <div class="h4 font-bold !text-cornflower">1</div>
       <div class="mt-8 flex flex-col flex-1 justify-between">
         <p class="p2">Download and install Kit CLI.</p>
-        <a href="/docs/installation" class="kit-button kit-button-salmon md:w-fit mt-6">Install the CLI</a>
+        <a href="/docs/cli/installation" class="kit-button kit-button-salmon md:w-fit mt-6">Install the CLI</a>
       </div>
     </div>
 
     <div class="kit-card flex flex-col">
       <div class="h4 font-bold !text-cornflower">2</div>
       <div class="mt-8 flex flex-col flex-1 justify-between">
         <p class="p2">Create a simple manifest file called a Kitfile with your model, dataset and code. Then build and push the ModelKit to a registry for sharing.</p>
-        <a href="/docs/installation" class="kit-button kit-button-cornflower md:w-fit mt-6">LEARN MORE</a>
+        <a href="/docs/kitfile/kf-overview.html" class="kit-button kit-button-cornflower md:w-fit mt-6">LEARN MORE</a>
       </div>
     </div>
 
     <div class="kit-card flex flex-col">
       <div class="h4 font-bold !text-cornflower">3</div>
       <div class="mt-8 flex flex-col flex-1 justify-between">
         <p class="p2">Pull the ModelKit into your pipeline, or use kit dev to start working with the model.</p>
-        <a href="/docs/installation" class="kit-button md:w-fit mt-6">USE CASES</a>
+        <a href="/docs/use-cases.html" class="kit-button md:w-fit mt-6">USE CASES</a>
       </div>
     </div>
   </div>

docs/.vitepress/utils.mts

@@ -0,0 +1,106 @@
+// Adapted from https://github.com/vuejs/vitepress/issues/1737#issuecomment-1372010207
+import * as fs from 'fs'
+import { resolve } from 'path'
+
+type ScanOptions = {
+  capitalize?: boolean,
+  replacements?: Record<string, string>,
+  textFormat: (text: string) => string
+}
+
+// Path where our docs are living.
+const BASE_PATH = resolve(__dirname, '../src/')
+
+/**
+ * Capitalize a given text.
+ * @param {string} text - text to capitalize
+ * @returns {string}
+ */
+function capitalize(text: string) {
+  return text[0].toUpperCase() + text.slice(1)
+}
+
+/**
+ * Given a folder path and an optional set of options, deep scan the folder for *.md files and return an array of items.
+ * @param pathName The path to the folder with the *.md files to scan
+ * @param options The options
+ * @returns {Array}
+ */
+export function getSidebarItemsFromMdFiles(pathName: string, options: Partial<ScanOptions>) {
+  const defaults: ScanOptions = {
+    capitalize: true,
+    textFormat: (text) => text.replace(/[-_]/g, ' ')
+  }
+
+	const path = resolve(BASE_PATH, `../src/${pathName}`)
+
+	return getItems(path, {
+    ...defaults,
+    ...options
+  })
+}
+
+// Read the folder and return the `{ text, items }` array.
+function getItems(path: string, options: Partial<ScanOptions>) {
+	let content = fs.readdirSync(path).filter(item => !item.startsWith('.'))
+
+	if (!content) {
+    return;
+  }
+
+  const getFormattedText = (text: string) => {
+    let formattedText = options.textFormat(text)
+
+    // If a custom label was provided, use that as-is and don't capitalize it to respect custom values.
+    if (options.replacements && options.replacements[text]) {
+      formattedText = options.replacements[text]
+    } else
+    // Otherwise, just check the `capitalize` flag.
+    if (options.capitalize) {
+      formattedText = capitalize(formattedText)
+    }
+
+    return formattedText;
+  }
+
+  let arr = content.map((item) => {
+    const text = getFormattedText(item.split('.')[0])
+
+    // If is content, just resolve it.
+    if (item.endsWith('.md')) {
+      return {
+        text,
+        link: resolve(path.replace(BASE_PATH, ''), item),
+      }
+    } else {
+      const newPath = resolve(path, item)
+      const isFolder = fs.lstatSync(newPath).isDirectory()
+
+      if (!isFolder) {
+        return
+      }
+
+      // If is a folder, recursively handle it.
+      return {
+        text,
+        items: getItems(newPath, options),
+        collapsible: true,
+      }
+    }
+  })
+
+  arr = arr.flatMap((item) => {
+    if (item?.link) {
+      item.link = normalizeLink(item.link)
+    }
+
+    return item
+  })
+
+  return arr
+}
+
+// Normalize a given path and return the `link` value in a standard, normalized format.
+function normalizeLink(path) {
+	return path.replace(/\\/g, '/').split('.')[0]
+}

docs/src/docs/cli/cli-reference.md

@@ -340,7 +340,7 @@ Create a tag that refers to a modelkit
 
 ### Synopsis
 
-Create or update a tag <target-modelkit> that refers to <source-modelkit>
+Create or update a tag {target-modelkit} that refers to {source-modelkit}
 
 This command assigns a new tag to an existing modelkit (source-modelkit) or
 updates an existing tag, effectively renaming or categorizing modelkits for

docs/src/docs/cli/usage.md

@@ -48,7 +48,7 @@ Then you can push it to your registry:
 $ ./kit push localhost:5050/example-repo:example-tag --http
 ```
 
-After you finish calling all your friends and telling them about Kit, they will want to fetch your ModelKit and run it. The `fetch` command is used to bring everything in the ModelKit to your local machine - the model, dataset(s), code, and the [Kitfile](../kitfile/overview.md) manifest.
+After you finish calling all your friends and telling them about Kit, they will want to fetch your ModelKit and run it. The `fetch` command is used to bring everything in the ModelKit to your local machine - the model, dataset(s), code, and the [Kitfile](../kitfile/kf-overview.md) manifest.
 
 ```sh
 $ ./kit fetch localhost:5050/test-repo:test-tag --http
@@ -74,4 +74,4 @@ The `dev` command will automatically generate a RESTful API for the model and th
 $ ./kit dev
 ```
 
-So with a few easy commands you've been able to package up a model, share it with others, and run it locally...and you never needed to learn Dockerfile syntax or how to deal with a Helm chart or other proprietary packaging method.
+So with a few easy commands you've been able to package up a model, share it with others, and run it locally...and you never needed to learn Dockerfile syntax or how to deal with a Helm chart or other proprietary packaging method.

pkg/cmd/tag/cmd.go

@@ -13,7 +13,7 @@ import (
 
 const (
 	shortDesc = "Create a tag that refers to a modelkit"
-	longDesc  = `Create or update a tag <target-modelkit> that refers to <source-modelkit>
+	longDesc  = `Create or update a tag {target-modelkit} that refers to {source-modelkit}
 
 This command assigns a new tag to an existing modelkit (source-modelkit) or
 updates an existing tag, effectively renaming or categorizing modelkits for