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/deployment/recipes/github-pages.html ADDED
@@ -0,0 +1,414 @@
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>Recipe: GitHub Pages - 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">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 open><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" class="active">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/deployment/preflight.html">Deployment</a><span class="separator">›</span><a href="../../../content/deployment/recipes/aws-s3.html">Recipes</a><span class="separator">›</span><span>github-pages</span></nav>
139
+ <div class="page-meta">Last updated: 2026-02-12</div>
140
+ <h1 id="recipe-github-pages">Recipe: GitHub Pages</h1>
141
+ <p>GitHub Pages is a good choice when your docs already live in GitHub.</p>
142
+ <p>There are many ways to do Pages. This recipe focuses on a beginner-friendly approach first, then a more automated path.</p>
143
+ <p>If you&#39;re new to deployment: start with Option A. It&#39;s not &quot;perfect&quot;, but it is simple and reliable.</p>
144
+ <h2 id="prerequisites">Prerequisites</h2>
145
+ <ul>
146
+ <li>A GitHub repository</li>
147
+ </ul>
148
+ <h2 id="important-subdirectory-paths">Important: subdirectory paths</h2>
149
+ <p>GitHub Pages project sites serve at <code>https://&lt;user&gt;.github.io/&lt;repo-name&gt;/</code> by default. Kitfly currently assumes root-level hosting, so links may break in subdirectory deployments.</p>
150
+ <p><strong>Recommended fix:</strong> Configure a <strong>custom domain</strong> (e.g., <code>docs.example.com</code>) so the site is served at root. Or use a GitHub Pages &quot;user/org&quot; site (<code>&lt;org&gt;.github.io</code>) which serves from <code>/</code>.</p>
151
+ <h2 id="build">Build</h2>
152
+ <pre><code class="language-bash">make build
153
+ </code></pre>
154
+ <h2 id="option-a-simplest-commit-the-built-site">Option A (simplest): commit the built site</h2>
155
+ <ol>
156
+ <li>Copy <code>dist/</code> into a folder GitHub Pages can serve, commonly <code>docs/</code></li>
157
+ <li>Commit and push</li>
158
+ <li>In GitHub repo settings → Pages:<ul>
159
+ <li>Source: &quot;Deploy from a branch&quot;</li>
160
+ <li>Folder: <code>docs/</code> (or whatever you chose)</li>
161
+ </ul>
162
+ </li>
163
+ </ol>
164
+ <p>Notes:</p>
165
+ <ul>
166
+ <li>This is easy, but it means build artifacts live in git.</li>
167
+ </ul>
168
+ <h2 id="option-b-recommended-build-via-github-actions">Option B (recommended): build via GitHub Actions</h2>
169
+ <p>This workflow builds on every push to <code>main</code> and publishes <code>dist/</code> as the Pages artifact.</p>
170
+ <pre><code class="language-yaml"># .github/workflows/deploy-pages.yml
171
+ name: Deploy to GitHub Pages
172
+
173
+ on:
174
+ push:
175
+ branches: [main]
176
+
177
+ permissions:
178
+ contents: read
179
+ pages: write
180
+ id-token: write
181
+
182
+ concurrency:
183
+ group: pages
184
+ cancel-in-progress: true
185
+
186
+ jobs:
187
+ build:
188
+ runs-on: ubuntu-latest
189
+ steps:
190
+ - uses: actions/checkout@v4
191
+
192
+ - uses: oven-sh/setup-bun@v2
193
+ with:
194
+ bun-version: latest
195
+
196
+ - run: bun install
197
+
198
+ - run: make build
199
+
200
+ - uses: actions/upload-pages-artifact@v3
201
+ with:
202
+ path: dist
203
+
204
+ deploy:
205
+ needs: build
206
+ runs-on: ubuntu-latest
207
+ environment:
208
+ name: github-pages
209
+ url: ${{ steps.deployment.outputs.page_url }}
210
+ steps:
211
+ - id: deployment
212
+ uses: actions/deploy-pages@v4
213
+ </code></pre>
214
+ <p>To use this workflow:</p>
215
+ <ol>
216
+ <li>Go to your repo → Settings → Pages → Source: <strong>GitHub Actions</strong></li>
217
+ <li>Commit the workflow file above</li>
218
+ <li>Push to <code>main</code></li>
219
+ </ol>
220
+ <h2 id="custom-domain-dns-basics">Custom domain (DNS basics)</h2>
221
+ <p>Typical pattern:</p>
222
+ <ul>
223
+ <li><code>docs.example.com</code> → <strong>CNAME</strong> to your <code>*.github.io</code> Pages domain</li>
224
+ </ul>
225
+ <p>After configuring DNS, add a <code>CNAME</code> file inside your <code>dist/</code> output (or in a <code>public/</code> folder that your build copies to <code>dist/</code>) containing your custom domain.</p>
226
+ <h2 id="verify-rollback">Verify + Rollback</h2>
227
+ <ul>
228
+ <li>Verify: load the site, click a few pages, hard refresh</li>
229
+ <li>Rollback: redeploy a prior commit (Option A) or re-run a prior workflow (Option B)</li>
230
+ </ul>
231
+ <p>See: <a href="../preflight.html">Preflight and Rollback</a></p>
232
+
233
+ </article>
234
+ <aside class="toc"><span class="toc-title">On this page</span><ul><li><a href="#prerequisites">Prerequisites</a></li><li><a href="#important-subdirectory-paths">Important: subdirectory paths</a></li><li><a href="#build">Build</a></li><li><a href="#option-a-simplest-commit-the-built-site">Option A (simplest): commit the built site</a></li><li><a href="#option-b-recommended-build-via-github-actions">Option B (recommended): build via GitHub Actions</a></li><li><a href="#custom-domain-dns-basics">Custom domain (DNS basics)</a></li><li><a href="#verify-rollback">Verify + Rollback</a></li></ul></aside>
235
+ </main>
236
+ </div>
237
+
238
+ <footer class="site-footer">
239
+ <div class="footer-content">
240
+ <div class="footer-left">
241
+ <span class="footer-version">v0.2.0</span>
242
+ <span class="footer-separator">·</span>
243
+ <span class="footer-commit" title="Commit: 33ccd68">Published 2026-02-15</span>
244
+ </div>
245
+ <div class="footer-center">
246
+ <span class="footer-copyright"><a href="https://3leaps.net" class="footer-link">© 2026 3 Leaps, LLC</a></span>
247
+ <span class="footer-separator">·</span><a href="/" class="footer-link">Kitfly</a>
248
+ </div>
249
+ <div class="footer-right">
250
+ <a href="https://kitfly.dev" class="footer-link">Built with Kitfly</a>
251
+ </div>
252
+ </div>
253
+ </footer>
254
+ <!-- Syntax highlighting - Prism.js -->
255
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js"></script>
256
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/plugins/autoloader/prism-autoloader.min.js"></script>
257
+ <!-- Mermaid diagram support -->
258
+ <script type="module">
259
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
260
+
261
+ function getMermaidTheme() {
262
+ const theme = document.documentElement.getAttribute('data-theme');
263
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
264
+ const isDark = theme === 'dark' || (!theme && prefersDark);
265
+ return isDark ? 'dark' : 'neutral';
266
+ }
267
+
268
+ mermaid.initialize({
269
+ startOnLoad: true,
270
+ theme: getMermaidTheme()
271
+ });
272
+
273
+ // Re-render mermaid diagrams when theme changes
274
+ window.reinitMermaid = async function() {
275
+ mermaid.initialize({ startOnLoad: false, theme: getMermaidTheme() });
276
+ const diagrams = document.querySelectorAll('.mermaid');
277
+ for (const el of diagrams) {
278
+ const code = el.getAttribute('data-mermaid-source');
279
+ if (code) {
280
+ el.innerHTML = code;
281
+ el.removeAttribute('data-processed');
282
+ }
283
+ }
284
+ await mermaid.run({ nodes: diagrams });
285
+ };
286
+ </script>
287
+
288
+ <script>
289
+ function toggleTheme() {
290
+ const html = document.documentElement;
291
+ const current = html.getAttribute('data-theme');
292
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
293
+
294
+ let next;
295
+ if (current === 'dark') {
296
+ next = 'light';
297
+ } else if (current === 'light') {
298
+ next = 'dark';
299
+ } else {
300
+ // No explicit theme set, toggle from system preference
301
+ next = prefersDark ? 'light' : 'dark';
302
+ }
303
+
304
+ html.setAttribute('data-theme', next);
305
+ localStorage.setItem('theme', next);
306
+
307
+ // Switch Prism theme
308
+ const prismLight = document.getElementById('prism-light');
309
+ const prismDark = document.getElementById('prism-dark');
310
+ if (next === 'dark') {
311
+ prismLight?.setAttribute('disabled', '');
312
+ prismDark?.removeAttribute('disabled');
313
+ } else {
314
+ prismLight?.removeAttribute('disabled');
315
+ prismDark?.setAttribute('disabled', '');
316
+ }
317
+
318
+ // Re-render mermaid diagrams with new theme
319
+ if (window.reinitMermaid) {
320
+ window.reinitMermaid();
321
+ }
322
+ }
323
+
324
+ // Slides mode hash routing
325
+ (function initSlidesMode() {
326
+ const shell = document.querySelector('.slides-shell');
327
+ if (!shell) return;
328
+
329
+ const slides = Array.from(document.querySelectorAll('.slide'));
330
+ if (!slides.length) return;
331
+
332
+ const prevBtn = document.querySelector('.slide-prev');
333
+ const nextBtn = document.querySelector('.slide-next');
334
+ const counter = document.querySelector('.slide-counter');
335
+ const progressBar = document.querySelector('.slide-progress-bar');
336
+ const navLinks = Array.from(document.querySelectorAll('.sidebar-nav a[href^="#slide-"]'));
337
+ let current = 0;
338
+
339
+ function setActive(n) {
340
+ current = Math.max(0, Math.min(n, slides.length - 1));
341
+ slides.forEach((slide, idx) => slide.classList.toggle('active', idx === current));
342
+ navLinks.forEach((link) => {
343
+ const active = link.getAttribute('href') === '#' + slides[current].id;
344
+ link.classList.toggle('active', active);
345
+ });
346
+ if (counter) counter.textContent = (current + 1) + ' / ' + slides.length;
347
+ if (progressBar) progressBar.style.width = (((current + 1) / slides.length) * 100) + '%';
348
+ if (prevBtn) prevBtn.disabled = current === 0;
349
+ if (nextBtn) nextBtn.disabled = current === slides.length - 1;
350
+ history.replaceState(null, '', '#' + slides[current].id);
351
+ }
352
+
353
+ function setFromHash() {
354
+ const hash = window.location.hash || '';
355
+ const idx = slides.findIndex((s) => '#' + s.id === hash);
356
+ if (idx >= 0) setActive(idx);
357
+ else setActive(0);
358
+ }
359
+
360
+ prevBtn?.addEventListener('click', () => setActive(current - 1));
361
+ nextBtn?.addEventListener('click', () => setActive(current + 1));
362
+
363
+ document.addEventListener('keydown', (e) => {
364
+ if (e.key === 'ArrowRight' || e.key === ' ') {
365
+ e.preventDefault();
366
+ setActive(current + 1);
367
+ } else if (e.key === 'ArrowLeft') {
368
+ e.preventDefault();
369
+ setActive(current - 1);
370
+ } else if (e.key === 'Home') {
371
+ e.preventDefault();
372
+ setActive(0);
373
+ } else if (e.key === 'End') {
374
+ e.preventDefault();
375
+ setActive(slides.length - 1);
376
+ }
377
+ });
378
+
379
+ window.addEventListener('hashchange', setFromHash);
380
+ setFromHash();
381
+ })();
382
+
383
+ // Copy code button
384
+ document.querySelectorAll('.prose pre code').forEach(block => {
385
+ const button = document.createElement('button');
386
+ button.className = 'copy-button';
387
+ button.textContent = 'Copy';
388
+ button.onclick = async () => {
389
+ await navigator.clipboard.writeText(block.textContent);
390
+ button.textContent = 'Copied!';
391
+ setTimeout(() => button.textContent = 'Copy', 2000);
392
+ };
393
+ block.parentElement.appendChild(button);
394
+ });
395
+
396
+ // Mobile nav toggle
397
+ function toggleNav() {
398
+ document.querySelector('.sidebar').classList.toggle('open');
399
+ }
400
+
401
+ // Close nav when clicking outside on mobile
402
+ document.addEventListener('click', (e) => {
403
+ const sidebar = document.querySelector('.sidebar');
404
+ const toggle = document.querySelector('.nav-toggle');
405
+ if (sidebar.classList.contains('open') &&
406
+ !sidebar.contains(e.target) &&
407
+ !toggle.contains(e.target)) {
408
+ sidebar.classList.remove('open');
409
+ }
410
+ });
411
+ </script>
412
+
413
+ </body>
414
+ </html>
package/dist/content/deployment/recipes/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=./vercel.html">
6
+ <title>Redirecting...</title>
7
+ </head>
8
+ <body>
9
+ <p>Redirecting to <a href="./vercel.html">vercel</a>...</p>
10
+ </body>
11
+ </html>