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/reference/key-concepts.html ADDED
@@ -0,0 +1,399 @@
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>Key Concepts - 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">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" class="active">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/reference/configuration.html">Reference</a><span class="separator">›</span><span>key-concepts</span></nav>
139
+ <div class="page-meta">Last updated: 2026-02-12</div>
140
+ <h1 id="key-concepts">Key Concepts</h1>
141
+ <p>Kitfly is intentionally small. If you understand these concepts, you understand the whole tool.</p>
142
+ <h2 id="site-root">Site root</h2>
143
+ <p>Your “site root” is the folder you run commands from. It usually contains:</p>
144
+ <ul>
145
+ <li><code>site.yaml</code></li>
146
+ <li><code>content/</code> (your docs)</li>
147
+ </ul>
148
+ <p>When you run <code>kitfly dev</code>, <code>kitfly build</code>, or <code>kitfly bundle</code>, you usually run them from your site root.</p>
149
+ <h2 id="docroot"><code>docroot</code></h2>
150
+ <p><code>docroot</code> is the folder Kitfly renders into a site.</p>
151
+ <p>In most projects:</p>
152
+ <ul>
153
+ <li><code>docroot: &quot;content&quot;</code></li>
154
+ </ul>
155
+ <p>Think of <code>docroot</code> as “the folder I’m publishing”.</p>
156
+ <h2 id="sections">Sections</h2>
157
+ <p>Sections are what you see in the left navigation. Each section maps to a folder.</p>
158
+ <p>In <code>site.yaml</code>, it looks like:</p>
159
+ <pre><code class="language-yaml">sections:
160
+ - name: &quot;Guide&quot;
161
+ path: &quot;guide&quot;
162
+ </code></pre>
163
+ <p>If you point <code>kitfly</code> at a folder without a <code>site.yaml</code>, Kitfly can auto-discover sections from subfolders (handy for quick previews).</p>
164
+ <h2 id="dist-build-output"><code>dist/</code> (build output)</h2>
165
+ <p><code>kitfly build</code> produces a static site folder, commonly:</p>
166
+ <ul>
167
+ <li><code>dist/</code></li>
168
+ </ul>
169
+ <p>You deploy by uploading/syncing <code>dist/</code> to a static host.</p>
170
+ <h2 id="build-vs-bundle-vs-dev">Build vs Bundle vs Dev</h2>
171
+ <ul>
172
+ <li><strong>Dev</strong> (<code>kitfly dev</code>) is for writing: it runs a local server and reloads when files change.</li>
173
+ <li><strong>Build</strong> (<code>kitfly build</code>) is for hosting: it creates a <code>dist/</code> folder you can upload.</li>
174
+ <li><strong>Bundle</strong> (<code>kitfly bundle</code>) is for sending: it creates a single HTML file you can email or drop in Slack.</li>
175
+ </ul>
176
+ <h2 id="build-vs-bundle">Build vs Bundle</h2>
177
+ <ul>
178
+ <li><strong>Build</strong>: outputs a folder (<code>dist/</code>) with multiple files (HTML + assets).</li>
179
+ <li><strong>Bundle</strong>: outputs a single HTML file you can email or upload (offline-friendly).</li>
180
+ </ul>
181
+ <h2 id="markdown-frontmatter">Markdown + frontmatter</h2>
182
+ <p>Kitfly renders Markdown files (<code>.md</code>). You can optionally add YAML frontmatter at the top of a file:</p>
183
+ <pre><code class="language-yaml">---
184
+ title: &quot;My Page&quot;
185
+ description: &quot;What this page is about&quot;
186
+ ---
187
+ </code></pre>
188
+ <p>Frontmatter is the easiest way to control titles and add metadata without changing your headings.</p>
189
+ <h2 id="theme-themeyaml">Theme (<code>theme.yaml</code>)</h2>
190
+ <p>Kitfly themes control the look of your site (colors, typography, layout details). The defaults are meant to be clean and readable.</p>
191
+ <p>If you don’t want to think about design: don’t touch it.</p>
192
+ <p>If you do: <code>theme.yaml</code> is your main “make it mine” knob.</p>
193
+ <h2 id="modes-docs-vs-slides-v020">Modes: docs vs slides (v0.2.0+)</h2>
194
+ <p>Kitfly can render the same Markdown content in two layouts:</p>
195
+ <ul>
196
+ <li><strong>docs</strong> (default): scrolling pages optimized for reading</li>
197
+ <li><strong>slides</strong>: fixed-aspect “one page at a time” slides with keyboard navigation</li>
198
+ </ul>
199
+ <p>Slides mode is configured in <code>site.yaml</code>:</p>
200
+ <pre><code class="language-yaml">mode: slides
201
+ aspect: &quot;16/9&quot;
202
+ </code></pre>
203
+ <h2 id="assets">Assets</h2>
204
+ <p>Kitfly will serve and bundle common “content-adjacent” assets referenced from Markdown, like images and PDFs.</p>
205
+ <p>Rule of thumb: if it lives next to your docs, Kitfly tries to do the right thing.</p>
206
+ <h2 id="provenance">Provenance</h2>
207
+ <p>Kitfly can emit provenance information (version/build date/git info) so you can answer “what did we ship?”.</p>
208
+ <p>If you see “unversioned”, it usually means your site didn’t set a <code>version</code> in <code>site.yaml</code> and the current git commit isn’t exactly tagged.</p>
209
+ <h2 id="static-site-plain-language">“Static site” (plain language)</h2>
210
+ <p>A static site is just files. No server-side database, no login, no runtime code required.</p>
211
+ <p>That’s why Kitfly sites are easy to:</p>
212
+ <ul>
213
+ <li>host almost anywhere</li>
214
+ <li>email as an attachment (bundle)</li>
215
+ <li>keep offline</li>
216
+ </ul>
217
+
218
+ </article>
219
+ <aside class="toc"><span class="toc-title">On this page</span><ul><li><a href="#site-root">Site root</a></li><li><a href="#sections">Sections</a></li><li><a href="#build-vs-bundle-vs-dev">Build vs Bundle vs Dev</a></li><li><a href="#build-vs-bundle">Build vs Bundle</a></li><li><a href="#markdown-frontmatter">Markdown + frontmatter</a></li><li><a href="#modes-docs-vs-slides-v020">Modes: docs vs slides (v0.2.0+)</a></li><li><a href="#assets">Assets</a></li><li><a href="#provenance">Provenance</a></li><li><a href="#static-site-plain-language">“Static site” (plain language)</a></li></ul></aside>
220
+ </main>
221
+ </div>
222
+
223
+ <footer class="site-footer">
224
+ <div class="footer-content">
225
+ <div class="footer-left">
226
+ <span class="footer-version">v0.2.0</span>
227
+ <span class="footer-separator">·</span>
228
+ <span class="footer-commit" title="Commit: 33ccd68">Published 2026-02-15</span>
229
+ </div>
230
+ <div class="footer-center">
231
+ <span class="footer-copyright"><a href="https://3leaps.net" class="footer-link">© 2026 3 Leaps, LLC</a></span>
232
+ <span class="footer-separator">·</span><a href="/" class="footer-link">Kitfly</a>
233
+ </div>
234
+ <div class="footer-right">
235
+ <a href="https://kitfly.dev" class="footer-link">Built with Kitfly</a>
236
+ </div>
237
+ </div>
238
+ </footer>
239
+ <!-- Syntax highlighting - Prism.js -->
240
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js"></script>
241
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/plugins/autoloader/prism-autoloader.min.js"></script>
242
+ <!-- Mermaid diagram support -->
243
+ <script type="module">
244
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
245
+
246
+ function getMermaidTheme() {
247
+ const theme = document.documentElement.getAttribute('data-theme');
248
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
249
+ const isDark = theme === 'dark' || (!theme && prefersDark);
250
+ return isDark ? 'dark' : 'neutral';
251
+ }
252
+
253
+ mermaid.initialize({
254
+ startOnLoad: true,
255
+ theme: getMermaidTheme()
256
+ });
257
+
258
+ // Re-render mermaid diagrams when theme changes
259
+ window.reinitMermaid = async function() {
260
+ mermaid.initialize({ startOnLoad: false, theme: getMermaidTheme() });
261
+ const diagrams = document.querySelectorAll('.mermaid');
262
+ for (const el of diagrams) {
263
+ const code = el.getAttribute('data-mermaid-source');
264
+ if (code) {
265
+ el.innerHTML = code;
266
+ el.removeAttribute('data-processed');
267
+ }
268
+ }
269
+ await mermaid.run({ nodes: diagrams });
270
+ };
271
+ </script>
272
+
273
+ <script>
274
+ function toggleTheme() {
275
+ const html = document.documentElement;
276
+ const current = html.getAttribute('data-theme');
277
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
278
+
279
+ let next;
280
+ if (current === 'dark') {
281
+ next = 'light';
282
+ } else if (current === 'light') {
283
+ next = 'dark';
284
+ } else {
285
+ // No explicit theme set, toggle from system preference
286
+ next = prefersDark ? 'light' : 'dark';
287
+ }
288
+
289
+ html.setAttribute('data-theme', next);
290
+ localStorage.setItem('theme', next);
291
+
292
+ // Switch Prism theme
293
+ const prismLight = document.getElementById('prism-light');
294
+ const prismDark = document.getElementById('prism-dark');
295
+ if (next === 'dark') {
296
+ prismLight?.setAttribute('disabled', '');
297
+ prismDark?.removeAttribute('disabled');
298
+ } else {
299
+ prismLight?.removeAttribute('disabled');
300
+ prismDark?.setAttribute('disabled', '');
301
+ }
302
+
303
+ // Re-render mermaid diagrams with new theme
304
+ if (window.reinitMermaid) {
305
+ window.reinitMermaid();
306
+ }
307
+ }
308
+
309
+ // Slides mode hash routing
310
+ (function initSlidesMode() {
311
+ const shell = document.querySelector('.slides-shell');
312
+ if (!shell) return;
313
+
314
+ const slides = Array.from(document.querySelectorAll('.slide'));
315
+ if (!slides.length) return;
316
+
317
+ const prevBtn = document.querySelector('.slide-prev');
318
+ const nextBtn = document.querySelector('.slide-next');
319
+ const counter = document.querySelector('.slide-counter');
320
+ const progressBar = document.querySelector('.slide-progress-bar');
321
+ const navLinks = Array.from(document.querySelectorAll('.sidebar-nav a[href^="#slide-"]'));
322
+ let current = 0;
323
+
324
+ function setActive(n) {
325
+ current = Math.max(0, Math.min(n, slides.length - 1));
326
+ slides.forEach((slide, idx) => slide.classList.toggle('active', idx === current));
327
+ navLinks.forEach((link) => {
328
+ const active = link.getAttribute('href') === '#' + slides[current].id;
329
+ link.classList.toggle('active', active);
330
+ });
331
+ if (counter) counter.textContent = (current + 1) + ' / ' + slides.length;
332
+ if (progressBar) progressBar.style.width = (((current + 1) / slides.length) * 100) + '%';
333
+ if (prevBtn) prevBtn.disabled = current === 0;
334
+ if (nextBtn) nextBtn.disabled = current === slides.length - 1;
335
+ history.replaceState(null, '', '#' + slides[current].id);
336
+ }
337
+
338
+ function setFromHash() {
339
+ const hash = window.location.hash || '';
340
+ const idx = slides.findIndex((s) => '#' + s.id === hash);
341
+ if (idx >= 0) setActive(idx);
342
+ else setActive(0);
343
+ }
344
+
345
+ prevBtn?.addEventListener('click', () => setActive(current - 1));
346
+ nextBtn?.addEventListener('click', () => setActive(current + 1));
347
+
348
+ document.addEventListener('keydown', (e) => {
349
+ if (e.key === 'ArrowRight' || e.key === ' ') {
350
+ e.preventDefault();
351
+ setActive(current + 1);
352
+ } else if (e.key === 'ArrowLeft') {
353
+ e.preventDefault();
354
+ setActive(current - 1);
355
+ } else if (e.key === 'Home') {
356
+ e.preventDefault();
357
+ setActive(0);
358
+ } else if (e.key === 'End') {
359
+ e.preventDefault();
360
+ setActive(slides.length - 1);
361
+ }
362
+ });
363
+
364
+ window.addEventListener('hashchange', setFromHash);
365
+ setFromHash();
366
+ })();
367
+
368
+ // Copy code button
369
+ document.querySelectorAll('.prose pre code').forEach(block => {
370
+ const button = document.createElement('button');
371
+ button.className = 'copy-button';
372
+ button.textContent = 'Copy';
373
+ button.onclick = async () => {
374
+ await navigator.clipboard.writeText(block.textContent);
375
+ button.textContent = 'Copied!';
376
+ setTimeout(() => button.textContent = 'Copy', 2000);
377
+ };
378
+ block.parentElement.appendChild(button);
379
+ });
380
+
381
+ // Mobile nav toggle
382
+ function toggleNav() {
383
+ document.querySelector('.sidebar').classList.toggle('open');
384
+ }
385
+
386
+ // Close nav when clicking outside on mobile
387
+ document.addEventListener('click', (e) => {
388
+ const sidebar = document.querySelector('.sidebar');
389
+ const toggle = document.querySelector('.nav-toggle');
390
+ if (sidebar.classList.contains('open') &&
391
+ !sidebar.contains(e.target) &&
392
+ !toggle.contains(e.target)) {
393
+ sidebar.classList.remove('open');
394
+ }
395
+ });
396
+ </script>
397
+
398
+ </body>
399
+ </html>