kitfly 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +63 -16
  3. package/VERSION +1 -1
  4. package/dist/_raw/content/deployment/preflight.md +134 -0
  5. package/dist/_raw/content/deployment/recipes/aws-s3.md +128 -0
  6. package/dist/_raw/content/deployment/recipes/cloudflare-pages.md +73 -0
  7. package/dist/_raw/content/deployment/recipes/cloudflare-r2.md +156 -0
  8. package/dist/_raw/content/deployment/recipes/fly-io.md +57 -0
  9. package/dist/_raw/content/deployment/recipes/github-pages.md +112 -0
  10. package/dist/_raw/content/deployment/recipes/netlify.md +99 -0
  11. package/dist/_raw/content/deployment/recipes/vercel.md +88 -0
  12. package/dist/_raw/content/deployment/secrets-and-env-vars.md +75 -0
  13. package/dist/_raw/content/deployment.md +128 -0
  14. package/dist/_raw/content/guide/approaches.md +182 -0
  15. package/dist/_raw/content/guide/features.md +121 -0
  16. package/dist/_raw/content/guide/getting-started.md +112 -0
  17. package/dist/_raw/content/guide/kitfly-overview.md +209 -0
  18. package/dist/_raw/content/reference/configuration.md +259 -0
  19. package/dist/_raw/content/reference/design-catalog.md +167 -0
  20. package/dist/_raw/content/reference/environment-variables.md +66 -0
  21. package/dist/_raw/content/reference/glossary.md +92 -0
  22. package/dist/_raw/content/reference/key-concepts.md +118 -0
  23. package/dist/_raw/content/reference/plugins.md +220 -0
  24. package/dist/_raw/content/reference/structure.md +166 -0
  25. package/dist/_raw/content/reference.md +19 -0
  26. package/dist/_raw/content/templates/crucible.md +192 -0
  27. package/dist/_raw/content/templates/handbook.md +83 -0
  28. package/dist/_raw/content/templates/minimal.md +138 -0
  29. package/dist/_raw/content/templates/overview.md +187 -0
  30. package/dist/_raw/content/templates/pipeline.md +151 -0
  31. package/dist/_raw/content/templates/productbook.md +187 -0
  32. package/dist/_raw/content/templates/runbook.md +193 -0
  33. package/dist/_raw/content/templates/servicebook.md +163 -0
  34. package/dist/_raw/docs/decisions/ADR-0001-minimalist-site-code.md +118 -0
  35. package/dist/_raw/docs/decisions/ADR-0002-ai-accessibility.md +153 -0
  36. package/dist/_raw/docs/decisions/ADR-0003-single-file-bundle.md +93 -0
  37. package/dist/_raw/docs/decisions/ADR-0004-bun-runtime.md +98 -0
  38. package/dist/_raw/docs/decisions/ADR-0005-plugin-contract-and-distribution.md +110 -0
  39. package/dist/_raw/docs/decisions/DDR-0001-viewport-locked-layout.md +111 -0
  40. package/dist/_raw/docs/decisions/DDR-0002-theme-system.md +131 -0
  41. package/dist/_raw/docs/decisions/DDR-0003-bounded-logo-slot.md +106 -0
  42. package/dist/_raw/docs/decisions/DDR-0004-slides-rendering-model.md +113 -0
  43. package/dist/_raw/docs/decisions/DDR-0005-deterministic-layout-boundary.md +107 -0
  44. package/dist/_raw/docs/userguide/cli/build.md +85 -0
  45. package/dist/_raw/docs/userguide/cli/bundle.md +81 -0
  46. package/dist/_raw/docs/userguide/cli/dev.md +92 -0
  47. package/dist/_raw/docs/userguide/cli/init.md +116 -0
  48. package/dist/_raw/docs/userguide/cli/servers.md +69 -0
  49. package/dist/_raw/docs/userguide/cli/stop.md +76 -0
  50. package/dist/_raw/docs/userguide/cli/update.md +78 -0
  51. package/dist/_raw/docs/userguide/cli/version.md +65 -0
  52. package/dist/_raw/docs/userguide/cli.md +34 -0
  53. package/dist/_raw/docs/userguide/sharing.md +94 -0
  54. package/dist/_raw/schemas/plugin-schemas-notes.md +71 -0
  55. package/dist/_raw/schemas.md +42 -0
  56. package/dist/assets/brand/kitfly-favicon-32.png +0 -0
  57. package/dist/assets/brand/kitfly-icon-64.png +0 -0
  58. package/dist/assets/brand/kitfly-logo-128.png +0 -0
  59. package/dist/assets/brand/kitfly-logo-512.png +0 -0
  60. package/dist/assets/brand/kitfly-logo.svg +12132 -0
  61. package/dist/assets/brand/kitfly-neon-128.png +0 -0
  62. package/dist/assets/brand/kitfly-neon-192.png +0 -0
  63. package/dist/assets/brand/kitfly-neon-256.png +0 -0
  64. package/dist/assets/brand/kitfly-neon.png +0 -0
  65. package/dist/assets/brand/palette.md +75 -0
  66. package/dist/content/deployment/index.html +11 -0
  67. package/dist/content/deployment/preflight.html +418 -0
  68. package/dist/content/deployment/recipes/aws-s3.html +421 -0
  69. package/dist/content/deployment/recipes/cloudflare-pages.html +372 -0
  70. package/dist/content/deployment/recipes/cloudflare-r2.html +443 -0
  71. package/dist/content/deployment/recipes/fly-io.html +356 -0
  72. package/dist/content/deployment/recipes/github-pages.html +414 -0
  73. package/dist/content/deployment/recipes/index.html +11 -0
  74. package/dist/content/deployment/recipes/netlify.html +394 -0
  75. package/dist/content/deployment/recipes/vercel.html +382 -0
  76. package/dist/content/deployment/secrets-and-env-vars.html +380 -0
  77. package/dist/content/deployment.html +426 -0
  78. package/dist/content/guide/approaches.html +501 -0
  79. package/dist/content/guide/features.html +436 -0
  80. package/dist/content/guide/getting-started.html +403 -0
  81. package/dist/content/guide/index.html +11 -0
  82. package/dist/content/guide/kitfly-overview.html +544 -0
  83. package/dist/content/index.html +11 -0
  84. package/dist/content/reference/configuration.html +580 -0
  85. package/dist/content/reference/design-catalog.html +449 -0
  86. package/dist/content/reference/environment-variables.html +367 -0
  87. package/dist/content/reference/glossary.html +368 -0
  88. package/dist/content/reference/index.html +11 -0
  89. package/dist/content/reference/key-concepts.html +399 -0
  90. package/dist/content/reference/plugins.html +491 -0
  91. package/dist/content/reference/structure.html +463 -0
  92. package/dist/content/reference.html +334 -0
  93. package/dist/content/templates/crucible.html +546 -0
  94. package/dist/content/templates/handbook.html +405 -0
  95. package/dist/content/templates/index.html +11 -0
  96. package/dist/content/templates/minimal.html +447 -0
  97. package/dist/content/templates/overview.html +558 -0
  98. package/dist/content/templates/pipeline.html +494 -0
  99. package/dist/content/templates/productbook.html +540 -0
  100. package/dist/content/templates/runbook.html +543 -0
  101. package/dist/content/templates/servicebook.html +523 -0
  102. package/dist/content-index.json +540 -0
  103. package/dist/docs/decisions/ADR-0001-minimalist-site-code.html +491 -0
  104. package/dist/docs/decisions/ADR-0002-ai-accessibility.html +434 -0
  105. package/dist/docs/decisions/ADR-0003-single-file-bundle.html +412 -0
  106. package/dist/docs/decisions/ADR-0004-bun-runtime.html +409 -0
  107. package/dist/docs/decisions/ADR-0005-plugin-contract-and-distribution.html +402 -0
  108. package/dist/docs/decisions/DDR-0001-viewport-locked-layout.html +459 -0
  109. package/dist/docs/decisions/DDR-0002-theme-system.html +452 -0
  110. package/dist/docs/decisions/DDR-0003-bounded-logo-slot.html +423 -0
  111. package/dist/docs/decisions/DDR-0004-slides-rendering-model.html +399 -0
  112. package/dist/docs/decisions/DDR-0005-deterministic-layout-boundary.html +422 -0
  113. package/dist/docs/decisions/index.html +11 -0
  114. package/dist/docs/userguide/cli/build.html +408 -0
  115. package/dist/docs/userguide/cli/bundle.html +419 -0
  116. package/dist/docs/userguide/cli/dev.html +428 -0
  117. package/dist/docs/userguide/cli/index.html +11 -0
  118. package/dist/docs/userguide/cli/init.html +436 -0
  119. package/dist/docs/userguide/cli/servers.html +393 -0
  120. package/dist/docs/userguide/cli/stop.html +408 -0
  121. package/dist/docs/userguide/cli/update.html +406 -0
  122. package/dist/docs/userguide/cli/version.html +406 -0
  123. package/dist/docs/userguide/cli.html +386 -0
  124. package/dist/docs/userguide/index.html +11 -0
  125. package/dist/docs/userguide/sharing.html +465 -0
  126. package/dist/index.html +387 -0
  127. package/dist/llms.txt +18 -0
  128. package/dist/provenance.json +7 -0
  129. package/dist/schemas/index.html +11 -0
  130. package/dist/schemas/plugin-registry.schema.html +327 -0
  131. package/dist/schemas/plugin-schemas-notes.html +364 -0
  132. package/dist/schemas/plugin.schema.html +327 -0
  133. package/dist/schemas/plugins.schema.html +327 -0
  134. package/dist/schemas/v0/common.schema.html +386 -0
  135. package/dist/schemas/v0/index.html +11 -0
  136. package/dist/schemas/v0/plugin-registry.schema.html +547 -0
  137. package/dist/schemas/v0/plugin.schema.html +497 -0
  138. package/dist/schemas/v0/plugins.schema.html +406 -0
  139. package/dist/schemas/v0/site.schema.html +541 -0
  140. package/dist/schemas/v0/theme.schema.html +615 -0
  141. package/dist/schemas.html +351 -0
  142. package/dist/styles.css +1262 -0
  143. package/package.json +4 -2
  144. package/plugins-dist/callouts.css +32 -0
  145. package/plugins-dist/callouts.js +46 -0
  146. package/plugins-dist/slides-visuals.css +224 -0
  147. package/plugins-dist/slides-visuals.js +598 -0
  148. package/registry/plugins.yaml +35 -0
  149. package/schemas/README.md +10 -0
  150. package/schemas/plugin-registry.schema.json +5 -0
  151. package/schemas/plugin-schemas-notes.md +71 -0
  152. package/schemas/plugin.schema.json +5 -0
  153. package/schemas/plugins.schema.json +5 -0
  154. package/schemas/v0/common.schema.json +64 -0
  155. package/schemas/v0/plugin-registry.schema.json +225 -0
  156. package/schemas/v0/plugin.schema.json +175 -0
  157. package/schemas/v0/plugins.schema.json +84 -0
  158. package/schemas/v0/site.schema.json +56 -9
  159. package/schemas/v0/theme.schema.json +105 -22
  160. package/scripts/build.ts +155 -3
  161. package/scripts/bundle.ts +258 -95
  162. package/scripts/dev.ts +203 -1
  163. package/src/__tests__/build.test.ts +158 -1
  164. package/src/__tests__/bundle.test.ts +31 -0
  165. package/src/__tests__/cli.test.ts +14 -3
  166. package/src/__tests__/fixtures/fences/slides-visuals/invalid/bad-list-indent.md +5 -0
  167. package/src/__tests__/fixtures/fences/slides-visuals/invalid/blank-line.md +5 -0
  168. package/src/__tests__/fixtures/fences/slides-visuals/invalid/compare-object-items.md +9 -0
  169. package/src/__tests__/fixtures/fences/slides-visuals/invalid/indented-fence.md +4 -0
  170. package/src/__tests__/fixtures/fences/slides-visuals/invalid/stat-grid-missing-fields.md +5 -0
  171. package/src/__tests__/fixtures/fences/slides-visuals/invalid/unknown-type.md +3 -0
  172. package/src/__tests__/fixtures/fences/slides-visuals/valid/compare.md +10 -0
  173. package/src/__tests__/fixtures/fences/slides-visuals/valid/comparison-table.md +14 -0
  174. package/src/__tests__/fixtures/fences/slides-visuals/valid/funnel.md +7 -0
  175. package/src/__tests__/fixtures/fences/slides-visuals/valid/kpi.md +5 -0
  176. package/src/__tests__/fixtures/fences/slides-visuals/valid/layer-cake.md +6 -0
  177. package/src/__tests__/fixtures/fences/slides-visuals/valid/pyramid.md +6 -0
  178. package/src/__tests__/fixtures/fences/slides-visuals/valid/quadrant-grid.md +8 -0
  179. package/src/__tests__/fixtures/fences/slides-visuals/valid/scorecard.md +13 -0
  180. package/src/__tests__/fixtures/fences/slides-visuals/valid/stat-grid.md +8 -0
  181. package/src/__tests__/init.test.ts +35 -0
  182. package/src/__tests__/plugin-loader.test.ts +221 -0
  183. package/src/__tests__/shared.test.ts +428 -0
  184. package/src/__tests__/slides-visuals-fence-contract.test.ts +28 -0
  185. package/src/__tests__/slides-visuals-runtime-regressions.bun.test.ts +114 -0
  186. package/src/__tests__/styles.test.ts +35 -0
  187. package/src/cli.ts +9 -4
  188. package/src/plugin-loader.ts +245 -0
  189. package/src/shared.ts +614 -7
  190. package/src/site/styles.css +331 -0
  191. package/src/site/template.html +66 -5
  192. package/src/templates/deck.ts +186 -0
  193. package/src/templates/driver.ts +11 -1
  194. package/src/templates/minimal.ts +1 -0
package/dist/content/guide/kitfly-overview.html ADDED
@@ -0,0 +1,544 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Kitfly Overview - Kitfly Docs</title>
7
+ <link rel="icon" type="image/png" sizes="32x32" href="../../assets/brand/kitfly-favicon-32.png">
8
+ <link rel="icon" type="image/png" sizes="64x64" href="../../assets/brand/kitfly-neon-256.png">
9
+ <link rel="stylesheet" href="../../styles.css">
10
+ <style id="kitfly-theme">
11
+ :root { --color-bg: #ffffff;
12
+ --color-bg-sidebar: #f5f7f8;
13
+ --color-text: #374151;
14
+ --color-text-muted: #6b7280;
15
+ --color-border: #e5e7eb;
16
+ --color-link: #007182;
17
+ --color-link-hover: #0a6172;
18
+ --color-accent: #152F46;
19
+ --color-code-bg: #f5f7f8;
20
+ --color-logo: #152F46;
21
+ --sidebar-width: 280px;
22
+ --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
23
+ --font-headings: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
24
+ --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace; }
25
+ html { font-size: 16px; }
26
+ @media (prefers-color-scheme: dark) {
27
+ :root:not([data-theme="light"]) { --color-bg: #0d1117;
28
+ --color-bg-sidebar: #152F46;
29
+ --color-text: #e5e7eb;
30
+ --color-text-muted: #9ca3af;
31
+ --color-border: #374151;
32
+ --color-link: #709EA6;
33
+ --color-link-hover: #8fb5bc;
34
+ --color-accent: #f9fafb;
35
+ --color-code-bg: #152F46;
36
+ --color-logo: #f9fafb; }
37
+ }
38
+ [data-theme="dark"] { --color-bg: #0d1117;
39
+ --color-bg-sidebar: #152F46;
40
+ --color-text: #e5e7eb;
41
+ --color-text-muted: #9ca3af;
42
+ --color-border: #374151;
43
+ --color-link: #709EA6;
44
+ --color-link-hover: #8fb5bc;
45
+ --color-accent: #f9fafb;
46
+ --color-code-bg: #152F46;
47
+ --color-logo: #f9fafb; }
48
+ [data-theme="light"] { --color-bg: #ffffff;
49
+ --color-bg-sidebar: #f5f7f8;
50
+ --color-text: #374151;
51
+ --color-text-muted: #6b7280;
52
+ --color-border: #e5e7eb;
53
+ --color-link: #007182;
54
+ --color-link-hover: #0a6172;
55
+ --color-accent: #152F46;
56
+ --color-code-bg: #f5f7f8;
57
+ --color-logo: #152F46;
58
+ --sidebar-width: 280px;
59
+ --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
60
+ --font-headings: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
61
+ --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace; }
62
+ </style>
63
+ <!-- Syntax highlighting - Prism.js -->
64
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1/themes/prism.min.css" id="prism-light">
65
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1/themes/prism-okaidia.min.css" id="prism-dark" disabled>
66
+
67
+ <script>
68
+ // Apply saved theme immediately to prevent flash
69
+ (function() {
70
+ const saved = localStorage.getItem('theme');
71
+ if (saved) {
72
+ document.documentElement.setAttribute('data-theme', saved);
73
+ }
74
+ // Set Prism theme based on saved or system preference
75
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
76
+ const isDark = saved === 'dark' || (!saved && prefersDark);
77
+ if (isDark) {
78
+ document.getElementById('prism-light')?.setAttribute('disabled', '');
79
+ document.getElementById('prism-dark')?.removeAttribute('disabled');
80
+ }
81
+ })();
82
+ </script>
83
+ </head>
84
+ <body class="mode-docs">
85
+ <div class="mobile-header">
86
+ <button class="nav-toggle" onclick="toggleNav()" aria-label="Toggle navigation">
87
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
88
+ <path d="M3 12h18M3 6h18M3 18h18"/>
89
+ </svg>
90
+ </button>
91
+ <a href="../../" class="mobile-logo" title="Home" data-initial="K">
92
+ <img src="../../assets/brand/kitfly-neon-256.png" alt="Kitfly" class="logo-img logo-icon" onerror="this.onerror=null;this.style.display='none';this.parentElement.classList.add('logo-fallback')"/>
93
+ </a>
94
+ <button class="mobile-theme-toggle" onclick="toggleTheme()" title="Toggle theme" aria-label="Toggle theme">
95
+ <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
96
+ <circle cx="12" cy="12" r="5"/>
97
+ <path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/>
98
+ </svg>
99
+ <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
100
+ <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
101
+ </svg>
102
+ </button>
103
+ </div>
104
+ <div class="layout">
105
+ <nav class="sidebar">
106
+ <div class="sidebar-header">
107
+ <div class="logo logo-icon">
108
+ <a href="/" class="logo-icon" data-initial="K">
109
+ <img src="../../assets/brand/kitfly-neon-256.png" alt="Kitfly" class="logo-img" onerror="this.onerror=null;this.style.display='none';this.parentElement.classList.add('logo-fallback')"/>
110
+ </a>
111
+ <span class="logo-text">
112
+ <a href="/" class="brand">Kitfly</a>
113
+ <a href="../../" class="product">Kitfly Docs</a>
114
+ </span>
115
+ </div>
116
+ <div class="header-tools">
117
+ <button class="theme-toggle" onclick="toggleTheme()" title="Toggle theme" aria-label="Toggle theme">
118
+ <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
119
+ <circle cx="12" cy="12" r="5"/>
120
+ <path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/>
121
+ </svg>
122
+ <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
123
+ <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
124
+ </svg>
125
+ </button>
126
+ <div class="sidebar-meta">
127
+ <span class="meta-version">v0.2.0</span>
128
+ <span class="meta-branch">HEAD</span>
129
+ </div>
130
+ </div>
131
+ </div>
132
+ <div class="sidebar-nav">
133
+ <ul><li><a href="../../index.html" class="nav-home">Home</a></li><li><span class="nav-section">Guide</span><ul><li><a href="../../content/guide/approaches.html">approaches</a></li><li><a href="../../content/guide/features.html">features</a></li><li><a href="../../content/guide/getting-started.html">getting-started</a></li><li><a href="../../content/guide/kitfly-overview.html" class="active">kitfly-overview</a></li></ul></li><li><span class="nav-section">Templates</span><ul><li><a href="../../content/templates/crucible.html">crucible</a></li><li><a href="../../content/templates/handbook.html">handbook</a></li><li><a href="../../content/templates/minimal.html">minimal</a></li><li><a href="../../content/templates/overview.html">overview</a></li><li><a href="../../content/templates/pipeline.html">pipeline</a></li><li><a href="../../content/templates/productbook.html">productbook</a></li><li><a href="../../content/templates/runbook.html">runbook</a></li><li><a href="../../content/templates/servicebook.html">servicebook</a></li></ul></li><li><a href="../../content/reference.html" class="nav-section">Reference</a><ul><li><a href="../../content/reference/configuration.html">configuration</a></li><li><a href="../../content/reference/design-catalog.html">design-catalog</a></li><li><a href="../../content/reference/environment-variables.html">environment-variables</a></li><li><a href="../../content/reference/glossary.html">glossary</a></li><li><a href="../../content/reference/key-concepts.html">key-concepts</a></li><li><a href="../../content/reference/plugins.html">plugins</a></li><li><a href="../../content/reference/structure.html">structure</a></li></ul></li><li><a href="../../content/deployment.html" class="nav-section">Deployment</a><ul><li><a href="../../content/deployment/preflight.html">preflight</a></li><li><details><summary class="nav-group">recipes</summary><ul><li><a href="../../content/deployment/recipes/aws-s3.html">aws-s3</a></li><li><a href="../../content/deployment/recipes/cloudflare-pages.html">cloudflare-pages</a></li><li><a href="../../content/deployment/recipes/cloudflare-r2.html">cloudflare-r2</a></li><li><a href="../../content/deployment/recipes/fly-io.html">fly-io</a></li><li><a href="../../content/deployment/recipes/github-pages.html">github-pages</a></li><li><a href="../../content/deployment/recipes/netlify.html">netlify</a></li><li><a href="../../content/deployment/recipes/vercel.html">vercel</a></li></ul></details></li><li><a href="../../content/deployment/secrets-and-env-vars.html">secrets-and-env-vars</a></li></ul></li><li><span class="nav-section">User Guide</span><ul><li><details><summary class="nav-group"><a href="../../docs/userguide/cli.html">cli</a></summary><ul><li><a href="../../docs/userguide/cli/build.html">build</a></li><li><a href="../../docs/userguide/cli/bundle.html">bundle</a></li><li><a href="../../docs/userguide/cli/dev.html">dev</a></li><li><a href="../../docs/userguide/cli/init.html">init</a></li><li><a href="../../docs/userguide/cli/servers.html">servers</a></li><li><a href="../../docs/userguide/cli/stop.html">stop</a></li><li><a href="../../docs/userguide/cli/update.html">update</a></li><li><a href="../../docs/userguide/cli/version.html">version</a></li></ul></details></li><li><a href="../../docs/userguide/sharing.html">sharing</a></li></ul></li><li><span class="nav-section">Decisions</span><ul><li><a href="../../docs/decisions/ADR-0001-minimalist-site-code.html">ADR-0001-minimalist-site-code</a></li><li><a href="../../docs/decisions/ADR-0002-ai-accessibility.html">ADR-0002-ai-accessibility</a></li><li><a href="../../docs/decisions/ADR-0003-single-file-bundle.html">ADR-0003-single-file-bundle</a></li><li><a href="../../docs/decisions/ADR-0004-bun-runtime.html">ADR-0004-bun-runtime</a></li><li><a href="../../docs/decisions/ADR-0005-plugin-contract-and-distribution.html">ADR-0005-plugin-contract-and-distribution</a></li><li><a href="../../docs/decisions/DDR-0001-viewport-locked-layout.html">DDR-0001-viewport-locked-layout</a></li><li><a href="../../docs/decisions/DDR-0002-theme-system.html">DDR-0002-theme-system</a></li><li><a href="../../docs/decisions/DDR-0003-bounded-logo-slot.html">DDR-0003-bounded-logo-slot</a></li><li><a href="../../docs/decisions/DDR-0004-slides-rendering-model.html">DDR-0004-slides-rendering-model</a></li><li><a href="../../docs/decisions/DDR-0005-deterministic-layout-boundary.html">DDR-0005-deterministic-layout-boundary</a></li></ul></li><li><a href="../../schemas.html" class="nav-section">Schemas</a><ul><li><a href="../../schemas/plugin-registry.schema.html">plugin-registry.schema</a></li><li><a href="../../schemas/plugin-schemas-notes.html">plugin-schemas-notes</a></li><li><a href="../../schemas/plugin.schema.html">plugin.schema</a></li><li><a href="../../schemas/plugins.schema.html">plugins.schema</a></li><li><details><summary class="nav-group">v0</summary><ul><li><a href="../../schemas/v0/common.schema.html">common.schema</a></li><li><a href="../../schemas/v0/plugin-registry.schema.html">plugin-registry.schema</a></li><li><a href="../../schemas/v0/plugin.schema.html">plugin.schema</a></li><li><a href="../../schemas/v0/plugins.schema.html">plugins.schema</a></li><li><a href="../../schemas/v0/site.schema.html">site.schema</a></li><li><a href="../../schemas/v0/theme.schema.html">theme.schema</a></li></ul></details></li></ul></li></ul>
134
+ </div>
135
+ </nav>
136
+ <main class="content">
137
+ <article class="prose">
138
+ <nav class="breadcrumbs"><a href="../../content/guide/approaches.html">Content</a><span class="separator">›</span><a href="../../content/guide/approaches.html">Guide</a><span class="separator">›</span><span>kitfly-overview</span></nav>
139
+ <div class="page-meta">Last updated: 2026-02-04</div>
140
+ <h1 id="kitfly-overview">Kitfly Overview</h1>
141
+ <p>Kitfly helps people who aren&#39;t web developers turn a folder of writing into something shareable:</p>
142
+ <ul>
143
+ <li>A <strong>single-file HTML bundle</strong> you can email or post in Slack</li>
144
+ <li>A <strong>static site folder</strong> you can zip and host anywhere</li>
145
+ </ul>
146
+ <p>It is intentionally small: one dependency (<code>marked</code>) and a codebase you can understand in an afternoon.</p>
147
+ <h2 id="mission">Mission</h2>
148
+ <p>Many people have documentation that needs to be shared: runbooks, handbooks, project docs, technical guides. The options are often:</p>
149
+ <ul>
150
+ <li><strong>Too heavy</strong>: Docusaurus, Hugo, Astro require learning build tooling</li>
151
+ <li><strong>Too locked</strong>: Notion, Confluence, GitBook require accounts and subscriptions</li>
152
+ <li><strong>Too ugly</strong>: Raw markdown or PDFs don&#39;t look professional</li>
153
+ </ul>
154
+ <p>Kitfly sits in the gap: professional output, minimal complexity, no lock-in.</p>
155
+ <h2 id="what-kitfly-is">What Kitfly Is</h2>
156
+ <ul>
157
+ <li>A renderer for markdown folders with a clean, professional default layout</li>
158
+ <li>A fast way to preview docs locally (<code>kitfly dev</code>)</li>
159
+ <li>A way to ship docs as artifacts (<code>kitfly bundle</code>, <code>kitfly build</code>)</li>
160
+ <li>A tool that gives you <strong>your own copy</strong> of the rendering code</li>
161
+ </ul>
162
+ <h2 id="what-kitfly-is-not">What Kitfly Is Not</h2>
163
+ <p>Kitfly is not trying to replace full static site generators or app frameworks. These are excellent — use them when you need their power:</p>
164
+ <table>
165
+ <thead>
166
+ <tr>
167
+ <th>Tool</th>
168
+ <th>Strength</th>
169
+ <th>Use When</th>
170
+ </tr>
171
+ </thead>
172
+ <tbody><tr>
173
+ <td><strong>Obsidian</strong></td>
174
+ <td>Personal knowledge, journaling</td>
175
+ <td>You need a second brain</td>
176
+ </tr>
177
+ <tr>
178
+ <td><strong>Docusaurus</strong></td>
179
+ <td>React ecosystem, versioned docs</td>
180
+ <td>You have a dev team</td>
181
+ </tr>
182
+ <tr>
183
+ <td><strong>Hugo</strong></td>
184
+ <td>Speed, themes, flexibility</td>
185
+ <td>You want a powerful SSG</td>
186
+ </tr>
187
+ <tr>
188
+ <td><strong>Astro/Starlight</strong></td>
189
+ <td>Modern, component-driven</td>
190
+ <td>You need interactivity</td>
191
+ </tr>
192
+ <tr>
193
+ <td><strong>VitePress</strong></td>
194
+ <td>Vue ecosystem, great DX</td>
195
+ <td>You&#39;re in the Vue world</td>
196
+ </tr>
197
+ </tbody></table>
198
+ <p>Use Kitfly when you don&#39;t need those. Your content is just markdown — migration is straightforward when you outgrow it.</p>
199
+ <h2 id="three-ways-to-use-kitfly">Three Ways to Use Kitfly</h2>
200
+ <h3 id="1-create-a-standalone-site-primary-path">1. Create a Standalone Site (Primary Path)</h3>
201
+ <pre><code class="language-bash">kitfly init my-docs
202
+ cd my-docs
203
+ bun install
204
+ bun run dev
205
+ </code></pre>
206
+ <p>This creates a <strong>complete, self-contained site</strong> with:</p>
207
+ <pre><code>my-docs/
208
+ ├── .kitfly/ # Provenance metadata
209
+ │ └── manifest.json
210
+ ├── content/ # Your docs go here
211
+ ├── scripts/ # Rendering code (yours now)
212
+ │ ├── dev.ts
213
+ │ ├── build.ts
214
+ │ └── bundle.ts
215
+ ├── src/
216
+ │ ├── engine.ts
217
+ │ ├── theme.ts
218
+ │ └── site/
219
+ │ ├── template.html
220
+ │ └── styles.css
221
+ ├── schemas/
222
+ ├── site.yaml
223
+ ├── package.json # { &quot;dependencies&quot;: { &quot;marked&quot;: &quot;^15&quot; } }
224
+ └── VERSION # Provenance: created from kitfly 0.1.0
225
+ </code></pre>
226
+ <p><strong>The site is detached from kitfly.</strong> You own the code. You can:</p>
227
+ <ul>
228
+ <li>Modify the template, styles, rendering logic</li>
229
+ <li>Version control the whole thing (<code>git init</code>)</li>
230
+ <li>Never touch kitfly CLI again if you don&#39;t want to</li>
231
+ </ul>
232
+ <p><strong>Best for:</strong> New documentation projects, teams who want ownership.</p>
233
+ <h3 id="2-point-at-existing-docs-quick-preview">2. Point at Existing Docs (Quick Preview)</h3>
234
+ <pre><code class="language-bash">kitfly dev ./my-existing-docs
235
+ kitfly build ./my-existing-docs --out ./dist
236
+ kitfly bundle ./my-existing-docs --name docs.html
237
+ </code></pre>
238
+ <p>Renders any folder of markdown without copying anything into it.</p>
239
+ <p><strong>Best for:</strong> Previewing docs that live in another repo, quick experiments.</p>
240
+ <h3 id="3-clone-the-kitfly-repo-contributors">3. Clone the Kitfly Repo (Contributors)</h3>
241
+ <pre><code class="language-bash">git clone https://github.com/3leaps/kitfly
242
+ cd kitfly
243
+ bun install
244
+ bun run dev
245
+ </code></pre>
246
+ <p>This is the kitfly engine repo. The <code>content/</code> folder <strong>is</strong> the kitfly documentation — you&#39;re reading it now.</p>
247
+ <p><strong>Best for:</strong> Contributing to kitfly, modifying the CLI, deep customization.</p>
248
+ <h2 id="the-fly-how-docs-travel">The &quot;Fly&quot; — How Docs Travel</h2>
249
+ <p>Kitfly makes docs &quot;fly&quot; by producing artifacts that travel well:</p>
250
+ <table>
251
+ <thead>
252
+ <tr>
253
+ <th>Command</th>
254
+ <th>Output</th>
255
+ <th>Use Case</th>
256
+ </tr>
257
+ </thead>
258
+ <tbody><tr>
259
+ <td><code>kitfly dev</code></td>
260
+ <td>Live preview</td>
261
+ <td>Writing and editing</td>
262
+ </tr>
263
+ <tr>
264
+ <td><code>kitfly build</code></td>
265
+ <td><code>dist/</code> folder</td>
266
+ <td>Deploy to any static host</td>
267
+ </tr>
268
+ <tr>
269
+ <td><code>kitfly bundle</code></td>
270
+ <td>Single HTML file</td>
271
+ <td>Email, Slack, shared drive</td>
272
+ </tr>
273
+ </tbody></table>
274
+ <p>The bundle is typically 1-2MB and works offline — open it in any browser.</p>
275
+ <h2 id="philosophy-minimalist-site-code">Philosophy: Minimalist Site Code</h2>
276
+ <p>The code that <code>kitfly init</code> copies to your project follows strict constraints:</p>
277
+ <table>
278
+ <thead>
279
+ <tr>
280
+ <th>Metric</th>
281
+ <th>Target</th>
282
+ <th>Rationale</th>
283
+ </tr>
284
+ </thead>
285
+ <tbody><tr>
286
+ <td>Total lines</td>
287
+ <td>~500</td>
288
+ <td>Understandable in an afternoon</td>
289
+ </tr>
290
+ <tr>
291
+ <td>Dependencies</td>
292
+ <td>1</td>
293
+ <td>No supply chain risk</td>
294
+ </tr>
295
+ <tr>
296
+ <td>Files</td>
297
+ <td>~10</td>
298
+ <td>Nothing hidden</td>
299
+ </tr>
300
+ </tbody></table>
301
+ <blockquote>
302
+ <p><strong>Rule of thumb</strong>: If it can be done with CSS, vanilla JS under 50 lines, or a marked plugin, it belongs. Otherwise, it doesn&#39;t.</p>
303
+ </blockquote>
304
+ <p>This is codified in <a href="../../docs/decisions/ADR-0001-minimalist-site-code.md">ADR-0001: Minimalist Site Code</a>.</p>
305
+ <p>Users can modify the code — that&#39;s expected. But the starting point should be small enough that modification feels safe, not scary.</p>
306
+ <h2 id="provenance-and-updates">Provenance and Updates</h2>
307
+ <p>When you run <code>kitfly init</code>, the site is stamped with provenance:</p>
308
+ <pre><code class="language-json">// .kitfly/manifest.json
309
+ {
310
+ &quot;version&quot;: &quot;0.1.0&quot;,
311
+ &quot;createdAt&quot;: &quot;2026-02-04T12:00:00Z&quot;,
312
+ &quot;files&quot;: {
313
+ &quot;scripts/dev.ts&quot;: { &quot;hash&quot;: &quot;a1b2c3&quot;, &quot;managed&quot;: true },
314
+ ...
315
+ }
316
+ }
317
+ </code></pre>
318
+ <p>This enables future updates:</p>
319
+ <pre><code class="language-bash">kitfly update # Upgrade to latest
320
+ kitfly update 0.2.0 # Upgrade to specific version
321
+ </code></pre>
322
+ <p>The update logic:</p>
323
+ <ol>
324
+ <li>Read manifest → know current version</li>
325
+ <li>For each managed file: check if user modified it (hash comparison)</li>
326
+ <li>Safe to replace → update file</li>
327
+ <li>User modified → warn, offer merge/skip/force</li>
328
+ <li>Update manifest with new version</li>
329
+ </ol>
330
+ <h2 id="this-repo-is-the-kitfly-docs">This Repo Is the Kitfly Docs</h2>
331
+ <p>The <code>content/</code> folder in this repository is the actual kitfly documentation. When you run <code>kitfly dev .</code> here, you&#39;re seeing our docs rendered by our tool.</p>
332
+ <p>This means:</p>
333
+ <ul>
334
+ <li><strong>No fake showcase pages</strong> — everything you see is real</li>
335
+ <li><strong>Features are demonstrated by use</strong> — Mermaid diagrams, code fences, theming</li>
336
+ <li><strong>The docs are always current</strong> — we eat our own cooking</li>
337
+ </ul>
338
+ <h2 id="architecture-summary">Architecture Summary</h2>
339
+ <pre><code>kitfly/ # The tool
340
+ ├── src/cli.ts # CLI entry (not copied to users)
341
+ ├── src/commands/ # init, update (not copied)
342
+ ├── content/ # Kitfly&#39;s own docs (not copied)
343
+ │
344
+ ├── scripts/ # ← Copied to user sites
345
+ │ ├── dev.ts
346
+ │ ├── build.ts
347
+ │ └── bundle.ts
348
+ ├── src/site/ # ← Copied to user sites
349
+ │ ├── template.html
350
+ │ └── styles.css
351
+ ├── src/engine.ts # ← Copied
352
+ ├── src/theme.ts # ← Copied
353
+ └── schemas/ # ← Copied
354
+ </code></pre>
355
+ <p><strong>Kitfly the tool</strong> can grow thoughtfully (more CLI commands, smarter updates). <strong>Site code</strong> stays minimal.</p>
356
+ <h2 id="next-steps">Next Steps</h2>
357
+ <ul>
358
+ <li><a href="getting-started.md">Getting Started</a> — Set up your first site</li>
359
+ <li><a href="features.md">Features</a> — See code highlighting, Mermaid diagrams, theming</li>
360
+ <li><a href="../reference/configuration.md">Configuration</a> — Customize <code>site.yaml</code> and <code>theme.yaml</code></li>
361
+ </ul>
362
+
363
+ </article>
364
+ <aside class="toc"><span class="toc-title">On this page</span><ul><li><a href="#mission">Mission</a></li><li><a href="#what-kitfly-is">What Kitfly Is</a></li><li><a href="#what-kitfly-is-not">What Kitfly Is Not</a></li><li><a href="#three-ways-to-use-kitfly">Three Ways to Use Kitfly</a></li><li class="toc-h3"><a href="#1-create-a-standalone-site-primary-path">1. Create a Standalone Site (Primary Path)</a></li><li class="toc-h3"><a href="#2-point-at-existing-docs-quick-preview">2. Point at Existing Docs (Quick Preview)</a></li><li class="toc-h3"><a href="#3-clone-the-kitfly-repo-contributors">3. Clone the Kitfly Repo (Contributors)</a></li><li><a href="#the-fly-how-docs-travel">The &quot;Fly&quot; — How Docs Travel</a></li><li><a href="#philosophy-minimalist-site-code">Philosophy: Minimalist Site Code</a></li><li><a href="#provenance-and-updates">Provenance and Updates</a></li><li><a href="#this-repo-is-the-kitfly-docs">This Repo Is the Kitfly Docs</a></li><li><a href="#architecture-summary">Architecture Summary</a></li><li><a href="#next-steps">Next Steps</a></li></ul></aside>
365
+ </main>
366
+ </div>
367
+
368
+ <footer class="site-footer">
369
+ <div class="footer-content">
370
+ <div class="footer-left">
371
+ <span class="footer-version">v0.2.0</span>
372
+ <span class="footer-separator">·</span>
373
+ <span class="footer-commit" title="Commit: 33ccd68">Published 2026-02-15</span>
374
+ </div>
375
+ <div class="footer-center">
376
+ <span class="footer-copyright"><a href="https://3leaps.net" class="footer-link">© 2026 3 Leaps, LLC</a></span>
377
+ <span class="footer-separator">·</span><a href="/" class="footer-link">Kitfly</a>
378
+ </div>
379
+ <div class="footer-right">
380
+ <a href="https://kitfly.dev" class="footer-link">Built with Kitfly</a>
381
+ </div>
382
+ </div>
383
+ </footer>
384
+ <!-- Syntax highlighting - Prism.js -->
385
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js"></script>
386
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/plugins/autoloader/prism-autoloader.min.js"></script>
387
+ <!-- Mermaid diagram support -->
388
+ <script type="module">
389
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
390
+
391
+ function getMermaidTheme() {
392
+ const theme = document.documentElement.getAttribute('data-theme');
393
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
394
+ const isDark = theme === 'dark' || (!theme && prefersDark);
395
+ return isDark ? 'dark' : 'neutral';
396
+ }
397
+
398
+ mermaid.initialize({
399
+ startOnLoad: true,
400
+ theme: getMermaidTheme()
401
+ });
402
+
403
+ // Re-render mermaid diagrams when theme changes
404
+ window.reinitMermaid = async function() {
405
+ mermaid.initialize({ startOnLoad: false, theme: getMermaidTheme() });
406
+ const diagrams = document.querySelectorAll('.mermaid');
407
+ for (const el of diagrams) {
408
+ const code = el.getAttribute('data-mermaid-source');
409
+ if (code) {
410
+ el.innerHTML = code;
411
+ el.removeAttribute('data-processed');
412
+ }
413
+ }
414
+ await mermaid.run({ nodes: diagrams });
415
+ };
416
+ </script>
417
+
418
+ <script>
419
+ function toggleTheme() {
420
+ const html = document.documentElement;
421
+ const current = html.getAttribute('data-theme');
422
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
423
+
424
+ let next;
425
+ if (current === 'dark') {
426
+ next = 'light';
427
+ } else if (current === 'light') {
428
+ next = 'dark';
429
+ } else {
430
+ // No explicit theme set, toggle from system preference
431
+ next = prefersDark ? 'light' : 'dark';
432
+ }
433
+
434
+ html.setAttribute('data-theme', next);
435
+ localStorage.setItem('theme', next);
436
+
437
+ // Switch Prism theme
438
+ const prismLight = document.getElementById('prism-light');
439
+ const prismDark = document.getElementById('prism-dark');
440
+ if (next === 'dark') {
441
+ prismLight?.setAttribute('disabled', '');
442
+ prismDark?.removeAttribute('disabled');
443
+ } else {
444
+ prismLight?.removeAttribute('disabled');
445
+ prismDark?.setAttribute('disabled', '');
446
+ }
447
+
448
+ // Re-render mermaid diagrams with new theme
449
+ if (window.reinitMermaid) {
450
+ window.reinitMermaid();
451
+ }
452
+ }
453
+
454
+ // Slides mode hash routing
455
+ (function initSlidesMode() {
456
+ const shell = document.querySelector('.slides-shell');
457
+ if (!shell) return;
458
+
459
+ const slides = Array.from(document.querySelectorAll('.slide'));
460
+ if (!slides.length) return;
461
+
462
+ const prevBtn = document.querySelector('.slide-prev');
463
+ const nextBtn = document.querySelector('.slide-next');
464
+ const counter = document.querySelector('.slide-counter');
465
+ const progressBar = document.querySelector('.slide-progress-bar');
466
+ const navLinks = Array.from(document.querySelectorAll('.sidebar-nav a[href^="#slide-"]'));
467
+ let current = 0;
468
+
469
+ function setActive(n) {
470
+ current = Math.max(0, Math.min(n, slides.length - 1));
471
+ slides.forEach((slide, idx) => slide.classList.toggle('active', idx === current));
472
+ navLinks.forEach((link) => {
473
+ const active = link.getAttribute('href') === '#' + slides[current].id;
474
+ link.classList.toggle('active', active);
475
+ });
476
+ if (counter) counter.textContent = (current + 1) + ' / ' + slides.length;
477
+ if (progressBar) progressBar.style.width = (((current + 1) / slides.length) * 100) + '%';
478
+ if (prevBtn) prevBtn.disabled = current === 0;
479
+ if (nextBtn) nextBtn.disabled = current === slides.length - 1;
480
+ history.replaceState(null, '', '#' + slides[current].id);
481
+ }
482
+
483
+ function setFromHash() {
484
+ const hash = window.location.hash || '';
485
+ const idx = slides.findIndex((s) => '#' + s.id === hash);
486
+ if (idx >= 0) setActive(idx);
487
+ else setActive(0);
488
+ }
489
+
490
+ prevBtn?.addEventListener('click', () => setActive(current - 1));
491
+ nextBtn?.addEventListener('click', () => setActive(current + 1));
492
+
493
+ document.addEventListener('keydown', (e) => {
494
+ if (e.key === 'ArrowRight' || e.key === ' ') {
495
+ e.preventDefault();
496
+ setActive(current + 1);
497
+ } else if (e.key === 'ArrowLeft') {
498
+ e.preventDefault();
499
+ setActive(current - 1);
500
+ } else if (e.key === 'Home') {
501
+ e.preventDefault();
502
+ setActive(0);
503
+ } else if (e.key === 'End') {
504
+ e.preventDefault();
505
+ setActive(slides.length - 1);
506
+ }
507
+ });
508
+
509
+ window.addEventListener('hashchange', setFromHash);
510
+ setFromHash();
511
+ })();
512
+
513
+ // Copy code button
514
+ document.querySelectorAll('.prose pre code').forEach(block => {
515
+ const button = document.createElement('button');
516
+ button.className = 'copy-button';
517
+ button.textContent = 'Copy';
518
+ button.onclick = async () => {
519
+ await navigator.clipboard.writeText(block.textContent);
520
+ button.textContent = 'Copied!';
521
+ setTimeout(() => button.textContent = 'Copy', 2000);
522
+ };
523
+ block.parentElement.appendChild(button);
524
+ });
525
+
526
+ // Mobile nav toggle
527
+ function toggleNav() {
528
+ document.querySelector('.sidebar').classList.toggle('open');
529
+ }
530
+
531
+ // Close nav when clicking outside on mobile
532
+ document.addEventListener('click', (e) => {
533
+ const sidebar = document.querySelector('.sidebar');
534
+ const toggle = document.querySelector('.nav-toggle');
535
+ if (sidebar.classList.contains('open') &&
536
+ !sidebar.contains(e.target) &&
537
+ !toggle.contains(e.target)) {
538
+ sidebar.classList.remove('open');
539
+ }
540
+ });
541
+ </script>
542
+
543
+ </body>
544
+ </html>
package/dist/content/index.html ADDED
@@ -0,0 +1,11 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta http-equiv="refresh" content="0; url=./deployment.html">
6
+ <title>Redirecting...</title>
7
+ </head>
8
+ <body>
9
+ <p>Redirecting to <a href="./deployment.html">deployment</a>...</p>
10
+ </body>
11
+ </html>