kitfly 0.1.2 → 0.2.1

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 (209) hide show
  1. package/CHANGELOG.md +46 -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/slides-authoring-guidelines.md +129 -0
  25. package/dist/_raw/content/reference/structure.md +166 -0
  26. package/dist/_raw/content/reference.md +20 -0
  27. package/dist/_raw/content/templates/crucible.md +192 -0
  28. package/dist/_raw/content/templates/handbook.md +83 -0
  29. package/dist/_raw/content/templates/minimal.md +138 -0
  30. package/dist/_raw/content/templates/overview.md +187 -0
  31. package/dist/_raw/content/templates/pipeline.md +151 -0
  32. package/dist/_raw/content/templates/productbook.md +187 -0
  33. package/dist/_raw/content/templates/runbook.md +193 -0
  34. package/dist/_raw/content/templates/servicebook.md +163 -0
  35. package/dist/_raw/docs/decisions/ADR-0001-minimalist-site-code.md +118 -0
  36. package/dist/_raw/docs/decisions/ADR-0002-ai-accessibility.md +153 -0
  37. package/dist/_raw/docs/decisions/ADR-0003-single-file-bundle.md +93 -0
  38. package/dist/_raw/docs/decisions/ADR-0004-bun-runtime.md +98 -0
  39. package/dist/_raw/docs/decisions/ADR-0005-plugin-contract-and-distribution.md +110 -0
  40. package/dist/_raw/docs/decisions/DDR-0001-viewport-locked-layout.md +111 -0
  41. package/dist/_raw/docs/decisions/DDR-0002-theme-system.md +131 -0
  42. package/dist/_raw/docs/decisions/DDR-0003-bounded-logo-slot.md +106 -0
  43. package/dist/_raw/docs/decisions/DDR-0004-slides-rendering-model.md +113 -0
  44. package/dist/_raw/docs/decisions/DDR-0005-deterministic-layout-boundary.md +107 -0
  45. package/dist/_raw/docs/userguide/cli/build.md +85 -0
  46. package/dist/_raw/docs/userguide/cli/bundle.md +81 -0
  47. package/dist/_raw/docs/userguide/cli/dev.md +92 -0
  48. package/dist/_raw/docs/userguide/cli/init.md +116 -0
  49. package/dist/_raw/docs/userguide/cli/servers.md +69 -0
  50. package/dist/_raw/docs/userguide/cli/stop.md +76 -0
  51. package/dist/_raw/docs/userguide/cli/update.md +78 -0
  52. package/dist/_raw/docs/userguide/cli/version.md +65 -0
  53. package/dist/_raw/docs/userguide/cli.md +34 -0
  54. package/dist/_raw/docs/userguide/sharing.md +94 -0
  55. package/dist/_raw/schemas/plugin-schemas-notes.md +71 -0
  56. package/dist/_raw/schemas.md +42 -0
  57. package/dist/assets/brand/kitfly-favicon-32.png +0 -0
  58. package/dist/assets/brand/kitfly-icon-64.png +0 -0
  59. package/dist/assets/brand/kitfly-logo-128.png +0 -0
  60. package/dist/assets/brand/kitfly-logo-512.png +0 -0
  61. package/dist/assets/brand/kitfly-logo.svg +12132 -0
  62. package/dist/assets/brand/kitfly-neon-128.png +0 -0
  63. package/dist/assets/brand/kitfly-neon-192.png +0 -0
  64. package/dist/assets/brand/kitfly-neon-256.png +0 -0
  65. package/dist/assets/brand/kitfly-neon.png +0 -0
  66. package/dist/assets/brand/palette.md +75 -0
  67. package/dist/content/deployment/index.html +11 -0
  68. package/dist/content/deployment/preflight.html +418 -0
  69. package/dist/content/deployment/recipes/aws-s3.html +421 -0
  70. package/dist/content/deployment/recipes/cloudflare-pages.html +372 -0
  71. package/dist/content/deployment/recipes/cloudflare-r2.html +443 -0
  72. package/dist/content/deployment/recipes/fly-io.html +356 -0
  73. package/dist/content/deployment/recipes/github-pages.html +414 -0
  74. package/dist/content/deployment/recipes/index.html +11 -0
  75. package/dist/content/deployment/recipes/netlify.html +394 -0
  76. package/dist/content/deployment/recipes/vercel.html +382 -0
  77. package/dist/content/deployment/secrets-and-env-vars.html +380 -0
  78. package/dist/content/deployment.html +426 -0
  79. package/dist/content/guide/approaches.html +501 -0
  80. package/dist/content/guide/features.html +436 -0
  81. package/dist/content/guide/getting-started.html +403 -0
  82. package/dist/content/guide/index.html +11 -0
  83. package/dist/content/guide/kitfly-overview.html +544 -0
  84. package/dist/content/index.html +11 -0
  85. package/dist/content/reference/configuration.html +580 -0
  86. package/dist/content/reference/design-catalog.html +449 -0
  87. package/dist/content/reference/environment-variables.html +367 -0
  88. package/dist/content/reference/glossary.html +368 -0
  89. package/dist/content/reference/index.html +11 -0
  90. package/dist/content/reference/key-concepts.html +399 -0
  91. package/dist/content/reference/plugins.html +491 -0
  92. package/dist/content/reference/slides-authoring-guidelines.html +418 -0
  93. package/dist/content/reference/structure.html +463 -0
  94. package/dist/content/reference.html +335 -0
  95. package/dist/content/templates/crucible.html +546 -0
  96. package/dist/content/templates/handbook.html +405 -0
  97. package/dist/content/templates/index.html +11 -0
  98. package/dist/content/templates/minimal.html +447 -0
  99. package/dist/content/templates/overview.html +558 -0
  100. package/dist/content/templates/pipeline.html +494 -0
  101. package/dist/content/templates/productbook.html +540 -0
  102. package/dist/content/templates/runbook.html +543 -0
  103. package/dist/content/templates/servicebook.html +523 -0
  104. package/dist/content-index.json +549 -0
  105. package/dist/docs/decisions/ADR-0001-minimalist-site-code.html +491 -0
  106. package/dist/docs/decisions/ADR-0002-ai-accessibility.html +434 -0
  107. package/dist/docs/decisions/ADR-0003-single-file-bundle.html +412 -0
  108. package/dist/docs/decisions/ADR-0004-bun-runtime.html +409 -0
  109. package/dist/docs/decisions/ADR-0005-plugin-contract-and-distribution.html +402 -0
  110. package/dist/docs/decisions/DDR-0001-viewport-locked-layout.html +459 -0
  111. package/dist/docs/decisions/DDR-0002-theme-system.html +452 -0
  112. package/dist/docs/decisions/DDR-0003-bounded-logo-slot.html +423 -0
  113. package/dist/docs/decisions/DDR-0004-slides-rendering-model.html +399 -0
  114. package/dist/docs/decisions/DDR-0005-deterministic-layout-boundary.html +422 -0
  115. package/dist/docs/decisions/index.html +11 -0
  116. package/dist/docs/userguide/cli/build.html +408 -0
  117. package/dist/docs/userguide/cli/bundle.html +419 -0
  118. package/dist/docs/userguide/cli/dev.html +428 -0
  119. package/dist/docs/userguide/cli/index.html +11 -0
  120. package/dist/docs/userguide/cli/init.html +436 -0
  121. package/dist/docs/userguide/cli/servers.html +393 -0
  122. package/dist/docs/userguide/cli/stop.html +408 -0
  123. package/dist/docs/userguide/cli/update.html +406 -0
  124. package/dist/docs/userguide/cli/version.html +406 -0
  125. package/dist/docs/userguide/cli.html +386 -0
  126. package/dist/docs/userguide/index.html +11 -0
  127. package/dist/docs/userguide/sharing.html +465 -0
  128. package/dist/index.html +387 -0
  129. package/dist/llms.txt +18 -0
  130. package/dist/provenance.json +7 -0
  131. package/dist/schemas/index.html +11 -0
  132. package/dist/schemas/plugin-registry.schema.html +327 -0
  133. package/dist/schemas/plugin-schemas-notes.html +364 -0
  134. package/dist/schemas/plugin.schema.html +327 -0
  135. package/dist/schemas/plugins.schema.html +327 -0
  136. package/dist/schemas/v0/common.schema.html +386 -0
  137. package/dist/schemas/v0/index.html +11 -0
  138. package/dist/schemas/v0/plugin-registry.schema.html +547 -0
  139. package/dist/schemas/v0/plugin.schema.html +497 -0
  140. package/dist/schemas/v0/plugins.schema.html +406 -0
  141. package/dist/schemas/v0/site.schema.html +541 -0
  142. package/dist/schemas/v0/theme.schema.html +615 -0
  143. package/dist/schemas.html +351 -0
  144. package/dist/styles.css +1262 -0
  145. package/package.json +4 -2
  146. package/plugins-dist/callouts.css +32 -0
  147. package/plugins-dist/callouts.js +46 -0
  148. package/plugins-dist/slides-visuals.css +390 -0
  149. package/plugins-dist/slides-visuals.js +689 -0
  150. package/registry/plugins.yaml +35 -0
  151. package/schemas/README.md +10 -0
  152. package/schemas/plugin-registry.schema.json +5 -0
  153. package/schemas/plugin-schemas-notes.md +71 -0
  154. package/schemas/plugin.schema.json +5 -0
  155. package/schemas/plugins.schema.json +5 -0
  156. package/schemas/v0/common.schema.json +64 -0
  157. package/schemas/v0/plugin-registry.schema.json +225 -0
  158. package/schemas/v0/plugin.schema.json +175 -0
  159. package/schemas/v0/plugins.schema.json +84 -0
  160. package/schemas/v0/site.schema.json +56 -9
  161. package/schemas/v0/theme.schema.json +105 -22
  162. package/scripts/build.ts +158 -3
  163. package/scripts/bundle.ts +261 -95
  164. package/scripts/dev.ts +301 -11
  165. package/src/__tests__/build.test.ts +220 -1
  166. package/src/__tests__/bundle.test.ts +31 -0
  167. package/src/__tests__/cli.test.ts +14 -3
  168. package/src/__tests__/dev-plugin-errors.test.ts +20 -0
  169. package/src/__tests__/fixtures/fences/slides-visuals/invalid/bad-list-indent.md +5 -0
  170. package/src/__tests__/fixtures/fences/slides-visuals/invalid/blank-line.md +5 -0
  171. package/src/__tests__/fixtures/fences/slides-visuals/invalid/compare-object-items.md +9 -0
  172. package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-branching-no-source.md +5 -0
  173. package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-converging-no-target.md +6 -0
  174. package/src/__tests__/fixtures/fences/slides-visuals/invalid/indented-fence.md +4 -0
  175. package/src/__tests__/fixtures/fences/slides-visuals/invalid/staircase-empty-steps.md +3 -0
  176. package/src/__tests__/fixtures/fences/slides-visuals/invalid/stat-grid-missing-fields.md +5 -0
  177. package/src/__tests__/fixtures/fences/slides-visuals/invalid/timeline-horizontal-no-events.md +2 -0
  178. package/src/__tests__/fixtures/fences/slides-visuals/invalid/unknown-type.md +3 -0
  179. package/src/__tests__/fixtures/fences/slides-visuals/valid/compare.md +10 -0
  180. package/src/__tests__/fixtures/fences/slides-visuals/valid/comparison-table.md +14 -0
  181. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching-no-split.md +7 -0
  182. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching.md +8 -0
  183. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging-no-merge.md +7 -0
  184. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging.md +8 -0
  185. package/src/__tests__/fixtures/fences/slides-visuals/valid/funnel.md +7 -0
  186. package/src/__tests__/fixtures/fences/slides-visuals/valid/kpi.md +5 -0
  187. package/src/__tests__/fixtures/fences/slides-visuals/valid/layer-cake.md +6 -0
  188. package/src/__tests__/fixtures/fences/slides-visuals/valid/pyramid.md +6 -0
  189. package/src/__tests__/fixtures/fences/slides-visuals/valid/quadrant-grid.md +8 -0
  190. package/src/__tests__/fixtures/fences/slides-visuals/valid/scorecard.md +13 -0
  191. package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase-down.md +7 -0
  192. package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase.md +8 -0
  193. package/src/__tests__/fixtures/fences/slides-visuals/valid/stat-grid.md +8 -0
  194. package/src/__tests__/fixtures/fences/slides-visuals/valid/timeline-horizontal.md +9 -0
  195. package/src/__tests__/fixtures/fences/slides-visuals/valid/timeline-vertical.md +10 -0
  196. package/src/__tests__/init.test.ts +35 -0
  197. package/src/__tests__/plugin-loader.test.ts +221 -0
  198. package/src/__tests__/shared.test.ts +451 -0
  199. package/src/__tests__/slides-visuals-fence-contract.test.ts +28 -0
  200. package/src/__tests__/slides-visuals-runtime-regressions.bun.test.ts +147 -0
  201. package/src/__tests__/styles.test.ts +35 -0
  202. package/src/cli.ts +9 -4
  203. package/src/plugin-loader.ts +245 -0
  204. package/src/shared.ts +650 -7
  205. package/src/site/styles.css +331 -0
  206. package/src/site/template.html +66 -5
  207. package/src/templates/deck.ts +186 -0
  208. package/src/templates/driver.ts +11 -1
  209. package/src/templates/minimal.ts +1 -0
package/dist/content/reference/structure.html ADDED
@@ -0,0 +1,463 @@
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>Folder Structure - 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.1</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">key-concepts</a></li><li><a href="../../content/reference/plugins.html">plugins</a></li><li><a href="../../content/reference/slides-authoring-guidelines.html">slides-authoring-guidelines</a></li><li><a href="../../content/reference/structure.html" class="active">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>structure</span></nav>
139
+ <div class="page-meta">Last updated: 2026-02-03</div>
140
+ <h1 id="folder-structure">Folder Structure</h1>
141
+ <p>Understanding what&#39;s in the template and what ends up in your built site.</p>
142
+ <h2 id="template-repository">Template Repository</h2>
143
+ <p>When you clone kitfly, you get:</p>
144
+ <pre><code>kitfly/
145
+ ├── content/ # YOUR DOCS
146
+ │ ├── index.md # Home page
147
+ │ ├── guide/ # Guide section
148
+ │ └── reference/ # Reference section
149
+ │
150
+ ├── src/ # RENDERING MACHINERY
151
+ │ ├── cli.ts # CLI entry point
152
+ │ ├── commands/ # CLI commands
153
+ │ └── site/ # HTML template + CSS
154
+ │
155
+ ├── scripts/ # BUILD SCRIPTS
156
+ │ ├── dev.ts # Dev server
157
+ │ └── build.ts # Static build
158
+ │
159
+ ├── assets/ # BRAND ASSETS
160
+ │ └── brand/ # Logo, favicon
161
+ │
162
+ ├── dist/ # BUILD OUTPUT (gitignored)
163
+ │
164
+ ├── .plans/ # PLANNING (gitignored)
165
+ │
166
+ ├── site.yaml # CONFIGURATION
167
+ ├── package.json # Dependencies
168
+ ├── VERSION # Version number
169
+ ├── README.md # GitHub readme
170
+ ├── AGENTS.md # AI agent guide
171
+ └── LICENSE # MIT license
172
+ </code></pre>
173
+ <h2 id="what-gets-built">What Gets Built</h2>
174
+ <p>When you run <code>bun run build</code>, <strong>only content from <code>docroot</code> goes into <code>dist/</code></strong>:</p>
175
+ <pre><code>dist/
176
+ ├── index.html # From content/index.md
177
+ ├── guide/
178
+ │ ├── index.html # Redirect to first file
179
+ │ ├── approaches.html # From content/guide/approaches.md
180
+ │ ├── getting-started.html
181
+ │ └── features.html
182
+ ├── reference/
183
+ │ ├── index.html # Redirect to first file
184
+ │ ├── configuration.html
185
+ │ └── structure.html
186
+ ├── styles.css # From src/site/styles.css
187
+ ├── provenance.json # Build metadata
188
+ └── assets/ # Copied from assets/
189
+ └── brand/
190
+ </code></pre>
191
+ <p><strong>Not in dist/:</strong></p>
192
+ <ul>
193
+ <li><code>src/</code> - rendering code</li>
194
+ <li><code>scripts/</code> - build scripts</li>
195
+ <li><code>README.md</code> - GitHub readme</li>
196
+ <li><code>AGENTS.md</code> - AI guide</li>
197
+ <li><code>package.json</code> - dependencies</li>
198
+ <li><code>.plans/</code> - planning files</li>
199
+ <li>Any other repo files</li>
200
+ </ul>
201
+ <p>This separation is intentional. Your built site is just documentation - no tooling artifacts.</p>
202
+ <h2 id="the-docroot-setting">The docroot Setting</h2>
203
+ <p>In <code>site.yaml</code>:</p>
204
+ <pre><code class="language-yaml">docroot: &quot;content&quot;
205
+ </code></pre>
206
+ <p>This tells kitfly where to look for markdown files. Options:</p>
207
+ <table>
208
+ <thead>
209
+ <tr>
210
+ <th>Setting</th>
211
+ <th>Effect</th>
212
+ </tr>
213
+ </thead>
214
+ <tbody><tr>
215
+ <td><code>&quot;content&quot;</code></td>
216
+ <td>Render from <code>content/</code> (recommended)</td>
217
+ </tr>
218
+ <tr>
219
+ <td><code>&quot;docs&quot;</code></td>
220
+ <td>Render from <code>docs/</code> (common in code repos)</td>
221
+ </tr>
222
+ <tr>
223
+ <td><code>&quot;.&quot;</code></td>
224
+ <td>Render from repo root (use with care)</td>
225
+ </tr>
226
+ </tbody></table>
227
+ <h3 id="why-this-matters">Why This Matters</h3>
228
+ <p>With <code>docroot: &quot;content&quot;</code>:</p>
229
+ <ul>
230
+ <li>Your <code>README.md</code> stays on GitHub, not in the docs</li>
231
+ <li>Your <code>package.json</code> isn&#39;t exposed</li>
232
+ <li>You can have code, tests, and docs in the same repo</li>
233
+ </ul>
234
+ <p>With <code>docroot: &quot;.&quot;</code>:</p>
235
+ <ul>
236
+ <li>Everything in the repo root becomes documentation</li>
237
+ <li>Useful for pure documentation repos</li>
238
+ <li>You&#39;ll want to configure <code>sections</code> explicitly</li>
239
+ </ul>
240
+ <h2 id="customizing-the-template">Customizing the Template</h2>
241
+ <h3 id="the-machinery">The Machinery</h3>
242
+ <p>If you want to modify how kitfly renders:</p>
243
+ <ul>
244
+ <li><strong>HTML template:</strong> <code>src/site/template.html</code></li>
245
+ <li><strong>Styles:</strong> <code>src/site/styles.css</code></li>
246
+ <li><strong>Dev server:</strong> <code>scripts/dev.ts</code></li>
247
+ <li><strong>Build script:</strong> <code>scripts/build.ts</code></li>
248
+ </ul>
249
+ <p>These are ~500 lines total. Read them, understand them, modify if needed.</p>
250
+ <h3 id="brand-assets">Brand Assets</h3>
251
+ <p>Replace files in <code>assets/brand/</code>:</p>
252
+ <ul>
253
+ <li><code>kitfly-logo.svg</code> - Vector logo (ensure tight viewBox)</li>
254
+ <li><code>kitfly-logo-512.png</code> - Used in README</li>
255
+ <li><code>kitfly-logo-128.png</code> - Sidebar header fallback</li>
256
+ <li><code>kitfly-favicon-32.png</code> - Browser favicon</li>
257
+ </ul>
258
+ <p>These are copied to <code>dist/assets/</code> during build.</p>
259
+ <h2 id="for-different-use-cases">For Different Use Cases</h2>
260
+ <h3 id="documentation-alongside-code">Documentation alongside code</h3>
261
+ <pre><code>my-project/
262
+ ├── src/ # Your code
263
+ ├── tests/ # Your tests
264
+ ├── docs/ # Your documentation
265
+ │ ├── index.md
266
+ │ └── api/
267
+ └── site.yaml # docroot: &quot;docs&quot;
268
+ </code></pre>
269
+ <h3 id="pure-documentation-repo">Pure documentation repo</h3>
270
+ <pre><code>my-docs/
271
+ ├── index.md
272
+ ├── guides/
273
+ ├── reference/
274
+ └── site.yaml # docroot: &quot;.&quot;
275
+ </code></pre>
276
+ <h3 id="existing-markdown">Existing markdown</h3>
277
+ <p>Point kitfly at any folder:</p>
278
+ <pre><code class="language-bash">kitfly dev ./path/to/markdown
279
+ </code></pre>
280
+ <p>No need to restructure anything.</p>
281
+
282
+ </article>
283
+ <aside class="toc"><span class="toc-title">On this page</span><ul><li><a href="#template-repository">Template Repository</a></li><li><a href="#what-gets-built">What Gets Built</a></li><li><a href="#the-docroot-setting">The docroot Setting</a></li><li class="toc-h3"><a href="#why-this-matters">Why This Matters</a></li><li><a href="#customizing-the-template">Customizing the Template</a></li><li class="toc-h3"><a href="#the-machinery">The Machinery</a></li><li class="toc-h3"><a href="#brand-assets">Brand Assets</a></li><li><a href="#for-different-use-cases">For Different Use Cases</a></li><li class="toc-h3"><a href="#documentation-alongside-code">Documentation alongside code</a></li><li class="toc-h3"><a href="#pure-documentation-repo">Pure documentation repo</a></li><li class="toc-h3"><a href="#existing-markdown">Existing markdown</a></li></ul></aside>
284
+ </main>
285
+ </div>
286
+
287
+ <footer class="site-footer">
288
+ <div class="footer-content">
289
+ <div class="footer-left">
290
+ <span class="footer-version">v0.2.1</span>
291
+ <span class="footer-separator">·</span>
292
+ <span class="footer-commit" title="Commit: 30dfc01">Published 2026-02-15</span>
293
+ </div>
294
+ <div class="footer-center">
295
+ <span class="footer-copyright"><a href="https://3leaps.net" class="footer-link">© 2026 3 Leaps, LLC</a></span>
296
+ <span class="footer-separator">·</span><a href="/" class="footer-link">Kitfly</a>
297
+ </div>
298
+ <div class="footer-right">
299
+ <a href="https://kitfly.dev" class="footer-link">Built with Kitfly</a>
300
+ </div>
301
+ </div>
302
+ </footer>
303
+ <!-- Syntax highlighting - Prism.js -->
304
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js"></script>
305
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/plugins/autoloader/prism-autoloader.min.js"></script>
306
+ <!-- Mermaid diagram support -->
307
+ <script type="module">
308
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
309
+
310
+ function getMermaidTheme() {
311
+ const theme = document.documentElement.getAttribute('data-theme');
312
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
313
+ const isDark = theme === 'dark' || (!theme && prefersDark);
314
+ return isDark ? 'dark' : 'neutral';
315
+ }
316
+
317
+ mermaid.initialize({
318
+ startOnLoad: true,
319
+ theme: getMermaidTheme()
320
+ });
321
+
322
+ // Re-render mermaid diagrams when theme changes
323
+ window.reinitMermaid = async function() {
324
+ mermaid.initialize({ startOnLoad: false, theme: getMermaidTheme() });
325
+ const diagrams = document.querySelectorAll('.mermaid');
326
+ for (const el of diagrams) {
327
+ const code = el.getAttribute('data-mermaid-source');
328
+ if (code) {
329
+ el.innerHTML = code;
330
+ el.removeAttribute('data-processed');
331
+ }
332
+ }
333
+ await mermaid.run({ nodes: diagrams });
334
+ };
335
+ </script>
336
+
337
+ <script>
338
+ function toggleTheme() {
339
+ const html = document.documentElement;
340
+ const current = html.getAttribute('data-theme');
341
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
342
+
343
+ let next;
344
+ if (current === 'dark') {
345
+ next = 'light';
346
+ } else if (current === 'light') {
347
+ next = 'dark';
348
+ } else {
349
+ // No explicit theme set, toggle from system preference
350
+ next = prefersDark ? 'light' : 'dark';
351
+ }
352
+
353
+ html.setAttribute('data-theme', next);
354
+ localStorage.setItem('theme', next);
355
+
356
+ // Switch Prism theme
357
+ const prismLight = document.getElementById('prism-light');
358
+ const prismDark = document.getElementById('prism-dark');
359
+ if (next === 'dark') {
360
+ prismLight?.setAttribute('disabled', '');
361
+ prismDark?.removeAttribute('disabled');
362
+ } else {
363
+ prismLight?.removeAttribute('disabled');
364
+ prismDark?.setAttribute('disabled', '');
365
+ }
366
+
367
+ // Re-render mermaid diagrams with new theme
368
+ if (window.reinitMermaid) {
369
+ window.reinitMermaid();
370
+ }
371
+ }
372
+
373
+ // Slides mode hash routing
374
+ (function initSlidesMode() {
375
+ const shell = document.querySelector('.slides-shell');
376
+ if (!shell) return;
377
+
378
+ const slides = Array.from(document.querySelectorAll('.slide'));
379
+ if (!slides.length) return;
380
+
381
+ const prevBtn = document.querySelector('.slide-prev');
382
+ const nextBtn = document.querySelector('.slide-next');
383
+ const counter = document.querySelector('.slide-counter');
384
+ const progressBar = document.querySelector('.slide-progress-bar');
385
+ const navLinks = Array.from(document.querySelectorAll('.sidebar-nav a[href^="#slide-"]'));
386
+ let current = 0;
387
+
388
+ function setActive(n) {
389
+ current = Math.max(0, Math.min(n, slides.length - 1));
390
+ slides.forEach((slide, idx) => slide.classList.toggle('active', idx === current));
391
+ navLinks.forEach((link) => {
392
+ const active = link.getAttribute('href') === '#' + slides[current].id;
393
+ link.classList.toggle('active', active);
394
+ });
395
+ if (counter) counter.textContent = (current + 1) + ' / ' + slides.length;
396
+ if (progressBar) progressBar.style.width = (((current + 1) / slides.length) * 100) + '%';
397
+ if (prevBtn) prevBtn.disabled = current === 0;
398
+ if (nextBtn) nextBtn.disabled = current === slides.length - 1;
399
+ history.replaceState(null, '', '#' + slides[current].id);
400
+ }
401
+
402
+ function setFromHash() {
403
+ const hash = window.location.hash || '';
404
+ const idx = slides.findIndex((s) => '#' + s.id === hash);
405
+ if (idx >= 0) setActive(idx);
406
+ else setActive(0);
407
+ }
408
+
409
+ prevBtn?.addEventListener('click', () => setActive(current - 1));
410
+ nextBtn?.addEventListener('click', () => setActive(current + 1));
411
+
412
+ document.addEventListener('keydown', (e) => {
413
+ if (e.key === 'ArrowRight' || e.key === ' ') {
414
+ e.preventDefault();
415
+ setActive(current + 1);
416
+ } else if (e.key === 'ArrowLeft') {
417
+ e.preventDefault();
418
+ setActive(current - 1);
419
+ } else if (e.key === 'Home') {
420
+ e.preventDefault();
421
+ setActive(0);
422
+ } else if (e.key === 'End') {
423
+ e.preventDefault();
424
+ setActive(slides.length - 1);
425
+ }
426
+ });
427
+
428
+ window.addEventListener('hashchange', setFromHash);
429
+ setFromHash();
430
+ })();
431
+
432
+ // Copy code button
433
+ document.querySelectorAll('.prose pre code').forEach(block => {
434
+ const button = document.createElement('button');
435
+ button.className = 'copy-button';
436
+ button.textContent = 'Copy';
437
+ button.onclick = async () => {
438
+ await navigator.clipboard.writeText(block.textContent);
439
+ button.textContent = 'Copied!';
440
+ setTimeout(() => button.textContent = 'Copy', 2000);
441
+ };
442
+ block.parentElement.appendChild(button);
443
+ });
444
+
445
+ // Mobile nav toggle
446
+ function toggleNav() {
447
+ document.querySelector('.sidebar').classList.toggle('open');
448
+ }
449
+
450
+ // Close nav when clicking outside on mobile
451
+ document.addEventListener('click', (e) => {
452
+ const sidebar = document.querySelector('.sidebar');
453
+ const toggle = document.querySelector('.nav-toggle');
454
+ if (sidebar.classList.contains('open') &&
455
+ !sidebar.contains(e.target) &&
456
+ !toggle.contains(e.target)) {
457
+ sidebar.classList.remove('open');
458
+ }
459
+ });
460
+ </script>
461
+
462
+ </body>
463
+ </html>