✨ Render the command reference with version badges

.vitepress/theme/index.ts

@@ -1,7 +1,6 @@
 import { h, Fragment } from 'vue'
 import type { Theme } from 'vitepress'
 import DefaultTheme   from 'vitepress/theme-without-fonts'
-import CommandSection from './components/CommandSection.vue'
 import DockerIcon     from './components/DockerIcon.vue'
 import EnvVar         from './components/EnvVar.vue'
 import EnvVarSection  from './components/EnvVarSection.vue'
@@ -32,7 +31,6 @@ export default {
     })
   },
   enhanceApp({ app, router, siteData }) {
-    app.component('CommandSection', CommandSection)
     app.component('EnvVar', EnvVar)
     app.component('EnvVarSection', EnvVarSection)
   }

scripts/generate-commands.mjs

@@ -6,10 +6,72 @@ const root = load(
   fs.readFileSync(resolve('.vitepress/data/commands.yaml'), 'utf8')
 )
 
+const escape = value =>
+  (value ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+
+const cell = value => escape(value).replaceAll('|', '\\|')
+
+const flag = ({ name, shorthand }) =>
+  shorthand ? `--${name}, -${shorthand}` : `--${name}`
+
+const blockquote = description =>
+  escape(description)
+    .split('\n')
+    .map(line => (line === '' ? '>' : `> ${line}`))
+    .join('\n')
+
+const optionsTable = options => {
+  const rows = ['| Flag | Description | Default |', '| --- | --- | --- |']
+
+  for (const option of options) {
+    const value = option.default ? `\`${option.default}\`` : ''
+
+    rows.push(`| \`${flag(option)}\` | ${cell(option.usage)} | ${value} |`)
+  }
+
+  return rows.join('\n')
+}
+
+const section = command => {
+  const badges = []
+
+  if (command.aliases?.length) {
+    badges.push(`<Badge type="info" text="alias: ${command.aliases.join(', ')}" />`)
+  }
+
+  if (command.since) {
+    badges.push(`<Badge type="tip" text="v${command.since}" />`)
+  }
+
+  if (command.deprecated) {
+    badges.push(`<Badge type="warning" text="deprecated v${command.deprecated}" />`)
+  }
+
+  const title = [`\`${command.name}\``, ...badges].join(' ')
+  const lines = [`### ${title}`, '']
+
+  if (command.description) {
+    lines.push(blockquote(command.description), '')
+  }
+
+  if (command.usage) {
+    lines.push(`\`${command.usage}\``, '')
+  }
+
+  if (command.options?.length) {
+    lines.push(optionsTable(command.options), '')
+  }
+
+  return lines.join('\n').trimEnd()
+}
+
 const sections = []
 
 const walk = command => {
-  sections.push(`<CommandSection path="${command.name}" />`, '---', '')
+  sections.push(section(command), '', '---', '')
 
   for (const child of command.commands ?? []) {
     walk(child)