@lowdefy/docs-content 6.1.0 → 7.1.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 (284) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +7 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/validate.md +7 -4
  31. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  32. package/content/agents/agent-endpoint-tools.md +24 -0
  33. package/content/agents/agent-properties.md +13 -3
  34. package/content/agents/agent-server-hooks.md +1 -1
  35. package/content/agents/agentchat.md +43 -7
  36. package/content/agents/agentconversations.md +42 -8
  37. package/content/agents/agents-introduction.md +107 -0
  38. package/content/callback-reference/auth0logoutcallback.md +54 -0
  39. package/content/concepts/ai-agent-docs.md +455 -106
  40. package/content/concepts/blocks.md +150 -0
  41. package/content/concepts/connections-and-requests.md +402 -0
  42. package/content/concepts/custom-html.md +42 -0
  43. package/content/concepts/custom-styling.md +50 -5
  44. package/content/concepts/dynamic-page-content.md +309 -0
  45. package/content/concepts/events-and-actions.md +154 -2
  46. package/content/concepts/four-primitives.md +31 -0
  47. package/content/concepts/html-attributes.md +293 -0
  48. package/content/concepts/i18n.md +8 -3
  49. package/content/concepts/keyboard-shortcuts.md +2 -2
  50. package/content/concepts/layout-overview.md +1 -1
  51. package/content/concepts/logger.md +99 -0
  52. package/content/concepts/lowdefy-api.md +1319 -0
  53. package/content/concepts/lowdefy-schema.md +136 -3
  54. package/content/concepts/menus.md +8 -7
  55. package/content/concepts/module-authoring.md +76 -5
  56. package/content/concepts/modules.md +3 -1
  57. package/content/concepts/notifications.md +180 -0
  58. package/content/concepts/operators.md +7 -0
  59. package/content/concepts/page-and-app-state.md +252 -0
  60. package/content/concepts/page-paths.md +209 -0
  61. package/content/concepts/theming.md +582 -0
  62. package/content/connections/aigateway.md +375 -0
  63. package/content/connections/anthropic.md +169 -2
  64. package/content/connections/awss3.md +178 -2
  65. package/content/connections/axioshttp.md +181 -0
  66. package/content/connections/google.md +169 -2
  67. package/content/connections/mongodb.md +1014 -3
  68. package/content/connections/openai-connection.md +169 -2
  69. package/content/connections/sendgridmail.md +2 -0
  70. package/content/connections/smtp.md +3 -1
  71. package/content/connections/treg.md +329 -0
  72. package/content/container-blocks/affix.md +47 -7
  73. package/content/container-blocks/alert.md +76 -24
  74. package/content/container-blocks/badge.md +100 -24
  75. package/content/container-blocks/box.md +9 -9
  76. package/content/container-blocks/card.md +132 -27
  77. package/content/container-blocks/carousel.md +60 -7
  78. package/content/container-blocks/collapse.md +153 -9
  79. package/content/container-blocks/configprovider.md +35 -13
  80. package/content/container-blocks/confirmmodal.md +69 -23
  81. package/content/container-blocks/content.md +62 -98
  82. package/content/container-blocks/descriptions.md +45 -4
  83. package/content/container-blocks/drawer.md +139 -28
  84. package/content/container-blocks/dropdownmenu.md +119 -31
  85. package/content/container-blocks/flex.md +40 -62
  86. package/content/container-blocks/footer.md +15 -11
  87. package/content/container-blocks/googlemapsheatmap.md +1 -1
  88. package/content/container-blocks/googlemapsscript.md +2 -2
  89. package/content/container-blocks/header.md +71 -36
  90. package/content/container-blocks/label.md +34 -7
  91. package/content/container-blocks/layout.md +52 -34
  92. package/content/container-blocks/masonry.md +17 -71
  93. package/content/container-blocks/mobilemenu.md +131 -88
  94. package/content/container-blocks/modal.md +161 -26
  95. package/content/container-blocks/pageheadermenu.md +138 -31
  96. package/content/container-blocks/pagesidebarlayout.md +230 -27
  97. package/content/container-blocks/pagesidermenu.md +153 -43
  98. package/content/container-blocks/popover.md +34 -31
  99. package/content/container-blocks/result.md +32 -21
  100. package/content/container-blocks/sider.md +85 -122
  101. package/content/container-blocks/span.md +7 -7
  102. package/content/container-blocks/spinner.md +3 -3
  103. package/content/container-blocks/splitter.md +150 -68
  104. package/content/container-blocks/tabs.md +64 -12
  105. package/content/container-blocks/tooltip.md +22 -46
  106. package/content/container-blocks/watermark.md +22 -4
  107. package/content/controls/parallel_for.md +21 -2
  108. package/content/controls/reject.md +24 -3
  109. package/content/controls/return.md +17 -1
  110. package/content/controls/throw.md +1 -0
  111. package/content/controls/try.md +4 -2
  112. package/content/controls/while.md +46 -0
  113. package/content/deployment/deployment-environments.md +10 -7
  114. package/content/deployment/docker.md +22 -7
  115. package/content/deployment/node-server.md +4 -0
  116. package/content/deployment/vercel.md +17 -6
  117. package/content/display-blocks/aggrid.md +36 -19
  118. package/content/display-blocks/anchor.md +16 -15
  119. package/content/display-blocks/avatar.md +57 -37
  120. package/content/display-blocks/breadcrumb.md +70 -21
  121. package/content/display-blocks/button.md +93 -19
  122. package/content/display-blocks/calendar.md +12 -0
  123. package/content/display-blocks/clickablehtml.md +239 -0
  124. package/content/display-blocks/dangeroushtml.md +1 -1
  125. package/content/display-blocks/difflist.md +1 -1
  126. package/content/display-blocks/difftimeline.md +1 -1
  127. package/content/display-blocks/divider.md +64 -3
  128. package/content/display-blocks/dropdownbutton.md +81 -30
  129. package/content/display-blocks/echart.md +35 -1
  130. package/content/display-blocks/eventlog.md +363 -0
  131. package/content/display-blocks/floatbutton.md +129 -42
  132. package/content/display-blocks/html.md +61 -1
  133. package/content/display-blocks/icon.md +250 -67
  134. package/content/display-blocks/img.md +2 -2
  135. package/content/display-blocks/menu.md +146 -73
  136. package/content/display-blocks/message.md +38 -124
  137. package/content/display-blocks/notification.md +94 -222
  138. package/content/display-blocks/paragraph.md +59 -9
  139. package/content/display-blocks/pollingtimer.md +263 -0
  140. package/content/display-blocks/progress.md +96 -17
  141. package/content/display-blocks/qrcode.md +19 -4
  142. package/content/display-blocks/s3download.md +1 -1
  143. package/content/display-blocks/search.md +19 -9
  144. package/content/display-blocks/skeletonbutton.md +1 -0
  145. package/content/display-blocks/skeletoninput.md +1 -0
  146. package/content/display-blocks/statistic.md +75 -17
  147. package/content/display-blocks/steps.md +58 -25
  148. package/content/display-blocks/table.md +2527 -0
  149. package/content/display-blocks/tablelight.md +621 -0
  150. package/content/display-blocks/tag.md +102 -17
  151. package/content/display-blocks/title.md +50 -11
  152. package/content/display-blocks/tour.md +33 -23
  153. package/content/input-blocks/autocomplete.md +81 -9
  154. package/content/input-blocks/buttonselector.md +45 -8
  155. package/content/input-blocks/captcha.md +40 -0
  156. package/content/input-blocks/checkboxselector.md +97 -7
  157. package/content/input-blocks/checkboxswitch.md +33 -3
  158. package/content/input-blocks/colorselector.md +63 -14
  159. package/content/input-blocks/daterangeselector.md +165 -45
  160. package/content/input-blocks/dateselector.md +139 -41
  161. package/content/input-blocks/datetimeselector.md +158 -49
  162. package/content/input-blocks/inputgallery.md +3 -3
  163. package/content/input-blocks/intentinput.md +207 -0
  164. package/content/input-blocks/monthselector.md +120 -52
  165. package/content/input-blocks/multipleselector.md +150 -39
  166. package/content/input-blocks/numberinput.md +98 -12
  167. package/content/input-blocks/pagination.md +70 -14
  168. package/content/input-blocks/paragraphinput.md +51 -37
  169. package/content/input-blocks/passwordinput.md +60 -6
  170. package/content/input-blocks/phonenumberinput.md +59 -26
  171. package/content/input-blocks/placesautocomplete.md +319 -0
  172. package/content/input-blocks/radioselector.md +83 -7
  173. package/content/input-blocks/ratingslider.md +57 -26
  174. package/content/input-blocks/s3uploadbutton.md +24 -24
  175. package/content/input-blocks/s3uploaddragger.md +3 -3
  176. package/content/input-blocks/s3uploadphoto.md +5 -5
  177. package/content/input-blocks/segmentedselector.md +72 -32
  178. package/content/input-blocks/selector.md +109 -21
  179. package/content/input-blocks/switch.md +65 -17
  180. package/content/input-blocks/tableinput.md +445 -0
  181. package/content/input-blocks/tagmultipleselector.md +114 -0
  182. package/content/input-blocks/tagselector.md +114 -0
  183. package/content/input-blocks/textarea.md +32 -3
  184. package/content/input-blocks/textinput.md +70 -29
  185. package/content/input-blocks/tiptapinput.md +1 -1
  186. package/content/input-blocks/tiptapmentioninput.md +2 -2
  187. package/content/input-blocks/titleinput.md +39 -12
  188. package/content/input-blocks/treeinput.md +49 -25
  189. package/content/input-blocks/treemultipleselector.md +127 -10
  190. package/content/input-blocks/treeselector.md +97 -9
  191. package/content/input-blocks/upload.md +64 -15
  192. package/content/input-blocks/uploaddragger.md +17 -1
  193. package/content/input-blocks/uploadphoto.md +18 -1
  194. package/content/input-blocks/weekselector.md +120 -55
  195. package/content/learn/introduction.md +27 -0
  196. package/content/learn/quickstart.md +53 -0
  197. package/content/list-blocks/controlledlist.md +24 -15
  198. package/content/list-blocks/list.md +11 -11
  199. package/content/list-blocks/masonrylist.md +7 -34
  200. package/content/migration/auth-upgrade.md +337 -0
  201. package/content/migration/upgrade-guide.md +1 -0
  202. package/content/migration/v3-to-v4.md +417 -0
  203. package/content/migration/v6-to-v7.md +620 -0
  204. package/content/operators/_agent.md +155 -0
  205. package/content/operators/_app.md +2 -1
  206. package/content/operators/_array.md +122 -1
  207. package/content/operators/_build.md +1 -0
  208. package/content/operators/_credential.md +57 -0
  209. package/content/operators/_cron.md +292 -0
  210. package/content/operators/_date.md +2 -0
  211. package/content/operators/_error.md +24 -1
  212. package/content/operators/_get.md +6 -6
  213. package/content/operators/_hmac.md +78 -0
  214. package/content/operators/_js.md +2 -1
  215. package/content/operators/_location.md +1 -1
  216. package/content/operators/_media.md +13 -0
  217. package/content/operators/_module.md +56 -2
  218. package/content/operators/_operator.md +17 -3
  219. package/content/operators/_path_params.md +82 -0
  220. package/content/operators/_ref.md +258 -0
  221. package/content/operators/_request.md +1 -1
  222. package/content/operators/_request_details.md +6 -0
  223. package/content/operators/_type.md +14 -3
  224. package/content/operators/_url_query.md +2 -0
  225. package/content/operators/_user.md +3 -3
  226. package/content/plugins/plugins-actions.md +10 -0
  227. package/content/plugins/plugins-connections.md +25 -0
  228. package/content/plugins/plugins-dev.md +66 -0
  229. package/content/plugins/plugins-icon-sets.md +267 -0
  230. package/content/plugins/plugins-introduction.md +27 -1
  231. package/content/plugins/plugins.md +19 -0
  232. package/content/plugins/posthog.md +359 -0
  233. package/content/provider-reference/auth-js-providers.md +107 -0
  234. package/content/provider-reference/openidconnectprovider.md +44 -0
  235. package/content/recipes/recipes.md +16 -0
  236. package/content/reference/actions-reference.md +31 -0
  237. package/content/reference/blocks-reference.md +35 -0
  238. package/content/reference/cli.md +403 -0
  239. package/content/reference/connections-reference.md +23 -0
  240. package/content/reference/operators-reference.md +47 -0
  241. package/content/reference/reference.md +16 -0
  242. package/content/reference/schema-reference.md +12 -0
  243. package/content/testing/config-tests.md +677 -0
  244. package/content/testing/e2e-configuration.md +31 -1
  245. package/content/testing/e2e-getting-started.md +1 -1
  246. package/content/testing/e2e-introduction.md +1 -1
  247. package/content/testing/e2e-writing-tests.md +12 -1
  248. package/content/testing/explore-pull-request.md +136 -0
  249. package/content/testing/journey-data-sets.md +326 -0
  250. package/content/tutorial/tutorial-actions-operators.md +2 -2
  251. package/content/tutorial/tutorial-add-blocks.md +2 -2
  252. package/content/tutorial/tutorial-create-page.md +48 -2
  253. package/content/tutorial/tutorial-display-data-page.md +3 -3
  254. package/content/tutorial/tutorial-requests-api.md +155 -0
  255. package/content/tutorial/tutorial-requests-sql.md +153 -0
  256. package/content/tutorial/tutorial-start.md +66 -1
  257. package/content/user-authentication/auth-configuration.md +267 -0
  258. package/content/user-authentication/auth-providers.md +24 -0
  259. package/content/user-authentication/auth-steps.md +141 -0
  260. package/content/user-authentication/login-and-logout.md +160 -8
  261. package/content/user-authentication/mcp-oauth.md +424 -0
  262. package/content/user-authentication/organizations.md +246 -0
  263. package/content/user-authentication/protected-pages-apis.md +97 -0
  264. package/content/user-authentication/roles.md +49 -0
  265. package/content/user-authentication/two-factor.md +229 -0
  266. package/content/user-authentication/user-object.md +58 -0
  267. package/content/user-authentication/users-introduction.md +8 -0
  268. package/content/websockets/websocket-publish.md +105 -0
  269. package/content/websockets/websocket-subscriptions.md +136 -0
  270. package/content/websockets/websockets-introduction.md +101 -0
  271. package/hazards.json +44 -0
  272. package/index.json +3691 -14
  273. package/package.json +11 -1
  274. package/scripts/collectImportedFiles.js +80 -0
  275. package/scripts/extractAgentDocs.js +41 -30
  276. package/scripts/hashDocSources.js +38 -0
  277. package/scripts/isRedirectPage.js +26 -0
  278. package/scripts/recordSourceHashes.js +100 -0
  279. package/scripts/resolvePageSections.js +42 -0
  280. package/scripts/sectionKind.js +27 -0
  281. package/content/concepts/cli.md +0 -223
  282. package/content/other/introduction.md +0 -39
  283. package/content/other/next-auth-providers.md +0 -3
  284. /package/content/{other → actions}/updatesession.md +0 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lowdefy/docs-content",
3
- "version": "6.1.0",
3
+ "version": "7.1.0",
4
4
  "license": "Apache-2.0",
5
5
  "description": "Lowdefy documentation extracted as markdown for AI coding agents.",
6
6
  "homepage": "https://lowdefy.com",
@@ -20,14 +20,24 @@
20
20
  "type": "module",
21
21
  "exports": {
22
22
  "./index.json": "./index.json",
23
+ "./hazards.json": "./hazards.json",
24
+ "./scripts/collectImportedFiles.js": "./scripts/collectImportedFiles.js",
23
25
  "./scripts/extractAgentDocs.js": "./scripts/extractAgentDocs.js",
26
+ "./scripts/hashDocSources.js": "./scripts/hashDocSources.js",
27
+ "./scripts/isRedirectPage.js": "./scripts/isRedirectPage.js",
28
+ "./scripts/resolvePageSections.js": "./scripts/resolvePageSections.js",
29
+ "./scripts/sectionKind.js": "./scripts/sectionKind.js",
24
30
  "./content/*": "./content/*"
25
31
  },
26
32
  "files": [
27
33
  "content/**",
34
+ "hazards.json",
28
35
  "index.json",
29
36
  "scripts/*"
30
37
  ],
38
+ "dependencies": {
39
+ "@lowdefy/nunjucks": "7.1.0"
40
+ },
31
41
  "publishConfig": {
32
42
  "access": "public"
33
43
  }
@@ -0,0 +1,80 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */
16
+
17
+ import fs from 'fs';
18
+ import path from 'path';
19
+
20
+ // Static imports and re-exports (`... from './x.js'`), side-effect imports
21
+ // (`import './x.js'`) and dynamic imports with a literal specifier.
22
+ const specifierPatterns = [
23
+ /\bfrom\s*['"]([^'"]+)['"]/g,
24
+ /\bimport\s*['"]([^'"]+)['"]/g,
25
+ /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g,
26
+ ];
27
+
28
+ function isJsFile(file) {
29
+ return ['.js', '.mjs'].includes(path.extname(file));
30
+ }
31
+
32
+ function readRelativeSpecifiers(filePath) {
33
+ const source = fs.readFileSync(filePath, 'utf8');
34
+ const specifiers = new Set();
35
+ specifierPatterns.forEach((pattern) => {
36
+ for (const match of source.matchAll(pattern)) {
37
+ if (match[1].startsWith('./') || match[1].startsWith('../')) {
38
+ specifiers.add(match[1]);
39
+ }
40
+ }
41
+ });
42
+ return [...specifiers];
43
+ }
44
+
45
+ // A page can reference a JS file, such as a block's meta.js, that builds its
46
+ // content from the files it imports: AgGrid's meta.js calls createDisplayMeta.js,
47
+ // where the property schema lives. Returns those imported files, followed
48
+ // through JS files and relative to configDirectory like the refMap paths, so an
49
+ // edit to any of them changes the page's source hash. Paths use forward slashes
50
+ // on every OS, as each path is part of the hash. Only relative imports are
51
+ // followed: a package import is versioned with its package.
52
+ function collectImportedFiles({ configDirectory, files }) {
53
+ const imported = new Set();
54
+ const queue = files.filter(isJsFile).map((file) => path.resolve(configDirectory, file));
55
+ const visited = new Set(queue);
56
+ while (queue.length > 0) {
57
+ const filePath = queue.pop();
58
+ if (!fs.existsSync(filePath)) {
59
+ continue;
60
+ }
61
+ readRelativeSpecifiers(filePath).forEach((specifier) => {
62
+ const importedPath = path.resolve(path.dirname(filePath), specifier);
63
+ if (visited.has(importedPath) || !fs.existsSync(importedPath)) {
64
+ return;
65
+ }
66
+ visited.add(importedPath);
67
+ // Read for its version, as recordSourceHashes leaves it out.
68
+ if (path.basename(importedPath) === 'package.json') {
69
+ return;
70
+ }
71
+ imported.add(path.relative(configDirectory, importedPath).split(path.sep).join('/'));
72
+ if (isJsFile(importedPath)) {
73
+ queue.push(importedPath);
74
+ }
75
+ });
76
+ }
77
+ return [...imported];
78
+ }
79
+
80
+ export default collectImportedFiles;
@@ -18,45 +18,48 @@ import fs from 'fs';
18
18
  import path, { dirname } from 'path';
19
19
  import { fileURLToPath } from 'url';
20
20
 
21
+ import { nunjucksFunction } from '@lowdefy/nunjucks';
22
+
23
+ import isRedirectPage from './isRedirectPage.js';
24
+ import resolvePageSections from './resolvePageSections.js';
25
+ import sectionKind from './sectionKind.js';
26
+
21
27
  // Runs inside the docs app build (see packages/docs/templates/generateSiteAssets.js),
22
28
  // where pages are fully resolved: _refs inlined, template vars substituted.
23
29
  // Markdown content lives on Markdown/MarkdownWithCode block properties in
24
30
  // document order, so a plain block walk reconstructs each page as markdown.
25
31
 
26
- function sectionKind(section) {
27
- if (section.endsWith('Blocks') || section === 'Controls') return 'block';
28
- if (section === 'Operators') return 'operator';
29
- if (section === 'Actions') return 'action';
30
- if (section === 'Connections') return 'connection';
31
- return undefined;
32
+ function isPlainObject(value) {
33
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
32
34
  }
33
35
 
34
- function resolvePageSections(pages, menus) {
35
- const sectionMap = new Map();
36
- function walkLinks(links, parentGroup) {
37
- (links ?? []).forEach((link) => {
38
- if (link.type === 'MenuGroup') {
39
- const group = { label: link.properties?.title ?? link.id };
40
- walkLinks(link.links, group);
41
- } else if (link.type === 'MenuLink' && link.pageId) {
42
- if (parentGroup) {
43
- sectionMap.set(link.pageId, parentGroup);
44
- }
45
- }
46
- });
36
+ // Many docs pages write their markdown as a `_nunjucks` template so it can
37
+ // print the current version (`on: { version: _ref: version.yaml }`). With its
38
+ // _refs resolved, such a template renders to the same markdown at build time
39
+ // as in the browser. A template that reads state or other runtime operators
40
+ // (the live examples on block pages) has no static rendering and is skipped.
41
+ function renderStaticNunjucks(value) {
42
+ if (!isPlainObject(value) || !isPlainObject(value._nunjucks)) return undefined;
43
+ const { template, on = {} } = value._nunjucks;
44
+ if (typeof template !== 'string' || !isPlainObject(on)) return undefined;
45
+ const vars = {};
46
+ for (const [key, varValue] of Object.entries(on)) {
47
+ if (key.startsWith('~')) continue;
48
+ if (key.startsWith('_') || (typeof varValue === 'object' && varValue !== null)) {
49
+ return undefined;
50
+ }
51
+ vars[key] = varValue;
47
52
  }
48
- (menus ?? []).forEach((menu) => {
49
- walkLinks(menu.links, null);
50
- });
51
- return sectionMap;
53
+ return nunjucksFunction(template)(vars);
52
54
  }
53
55
 
54
56
  function extractPageMarkdown(page) {
55
57
  const parts = [];
56
58
  function collect(value) {
57
- // Unresolved runtime operators are objects — only static strings are docs content.
58
- if (typeof value === 'string' && value.trim() !== '') {
59
- parts.push(value.trim());
59
+ const markdown = typeof value === 'string' ? value : renderStaticNunjucks(value);
60
+ // Other runtime operators are objects — only static content is docs content.
61
+ if (typeof markdown === 'string' && markdown.trim() !== '') {
62
+ parts.push(markdown.trim());
60
63
  }
61
64
  }
62
65
  function walkBlock(block) {
@@ -94,14 +97,21 @@ function extractAgentDocs({ pages, menus, outputDir }) {
94
97
  const packageJson = JSON.parse(
95
98
  fs.readFileSync(path.join(dirname(fileURLToPath(import.meta.url)), '../package.json'), 'utf8')
96
99
  );
97
- const sectionMap = resolvePageSections(pages, menus);
100
+ const sectionMap = resolvePageSections({ menus });
98
101
  const contentDir = path.join(outputDir, 'content');
99
102
  fs.rmSync(contentDir, { recursive: true, force: true });
100
103
 
101
104
  const docs = [];
105
+ // The ref each page was resolved from (a non-enumerable build marker).
106
+ // recordSourceHashes, which runs after the build, maps it to the page's
107
+ // source files through the build's refMap.
108
+ const sources = {};
102
109
  pages.filter(Boolean).forEach((page) => {
110
+ if (isRedirectPage({ page })) {
111
+ return;
112
+ }
103
113
  const title = page.properties?.title ?? page.id;
104
- const section = sectionMap.get(page.id)?.label ?? 'Other';
114
+ const section = sectionMap.get(page.id) ?? 'Other';
105
115
  const markdown = extractPageMarkdown(page);
106
116
  if (markdown === '') {
107
117
  return;
@@ -113,17 +123,18 @@ function extractAgentDocs({ pages, menus, outputDir }) {
113
123
  fs.writeFileSync(absolutePath, `# ${title}\n\n${markdown}\n`);
114
124
 
115
125
  const doc = { slug, title, section, path: filePath };
116
- const kind = sectionKind(section);
126
+ const kind = sectionKind({ section });
117
127
  if (kind) {
118
128
  doc.kind = kind;
119
129
  doc.typeName = title;
120
130
  }
121
131
  docs.push(doc);
132
+ sources[slug] = { refId: page['~r'] };
122
133
  });
123
134
 
124
135
  fs.writeFileSync(
125
136
  path.join(outputDir, 'index.json'),
126
- JSON.stringify({ version: packageJson.version, docs }, null, 2)
137
+ JSON.stringify({ version: packageJson.version, docs, sources }, null, 2)
127
138
  );
128
139
  }
129
140
 
@@ -0,0 +1,38 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */
16
+
17
+ import crypto from 'crypto';
18
+ import fs from 'fs';
19
+ import path from 'path';
20
+
21
+ // A hash of the files a docs page is built from (its page file and every file
22
+ // it references), recorded at extraction and recomputed by the docs app's
23
+ // tests to find pages whose extracted content is stale. Line endings are
24
+ // normalised, so a Windows checkout hashes like any other. A file that no
25
+ // longer exists hashes as missing, so the page counts as changed.
26
+ function hashDocSources({ configDirectory, files }) {
27
+ const hash = crypto.createHash('sha256');
28
+ files.forEach((file) => {
29
+ const filePath = path.resolve(configDirectory, file);
30
+ const content = fs.existsSync(filePath)
31
+ ? fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n')
32
+ : '\0missing';
33
+ hash.update(`${file}\0${content}\0`);
34
+ });
35
+ return hash.digest('hex');
36
+ }
37
+
38
+ export default hashDocSources;
@@ -0,0 +1,26 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */
16
+
17
+ // Redirect stubs keep old deep links working by linking to the page that
18
+ // replaced them on load. They hold no docs content, so agents get no doc
19
+ // for them.
20
+ function isRedirectPage({ page }) {
21
+ const onInit = page.events?.onInit;
22
+ const actions = Array.isArray(onInit) ? onInit : onInit?.try;
23
+ return (actions ?? []).some((action) => action?.type === 'Link');
24
+ }
25
+
26
+ export default isRedirectPage;
@@ -0,0 +1,100 @@
1
+ #!/usr/bin/env node
2
+ /*
3
+ Copyright 2020-2026 Lowdefy, Inc
4
+
5
+ Licensed under the Apache License, Version 2.0 (the "License");
6
+ you may not use this file except in compliance with the License.
7
+ You may obtain a copy of the License at
8
+
9
+ http://www.apache.org/licenses/LICENSE-2.0
10
+
11
+ Unless required by applicable law or agreed to in writing, software
12
+ distributed under the License is distributed on an "AS IS" BASIS,
13
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ See the License for the specific language governing permissions and
15
+ limitations under the License.
16
+ */
17
+
18
+ import fs from 'fs';
19
+ import path, { dirname } from 'path';
20
+ import { fileURLToPath } from 'url';
21
+ import { parseArgs } from 'util';
22
+
23
+ import collectImportedFiles from './collectImportedFiles.js';
24
+ import hashDocSources from './hashDocSources.js';
25
+
26
+ // Second step of `pnpm docs:content`. extractAgentDocs runs inside the docs
27
+ // build, which knows each page's ref id but not yet the files behind it; the
28
+ // build's refMap.json (written at its end) maps ref ids to files and their
29
+ // parents. For each doc this finds the ref that pages.yaml resolved to the page,
30
+ // lists that ref's file, every file referenced below it and the files those JS
31
+ // files import (collectImportedFiles), and records them with their hash in
32
+ // index.json. A package.json is read for its version, which every release
33
+ // bumps, not for page content, so it is left out: otherwise each release and
34
+ // dependency update would mark every doc stale. The page frame
35
+ // (pageFrame, with its header, footer and feedback requests) holds no markdown
36
+ // and wraps every page, so it is left out too: otherwise one edit to it would
37
+ // change all the hashes, and two branches doing that would conflict in
38
+ // index.json on every doc.
39
+ function collectSourceFiles({ configDirectory, refMap, entryRefId, pageFrame }) {
40
+ const children = new Map();
41
+ Object.entries(refMap).forEach(([id, ref]) => {
42
+ const siblings = children.get(ref.parent) ?? [];
43
+ siblings.push(id);
44
+ children.set(ref.parent, siblings);
45
+ });
46
+ const files = new Set();
47
+ const queue = [entryRefId];
48
+ while (queue.length > 0) {
49
+ const id = queue.pop();
50
+ const filePath = refMap[id].path;
51
+ if (filePath === pageFrame) {
52
+ continue;
53
+ }
54
+ if (typeof filePath === 'string' && path.basename(filePath) !== 'package.json') {
55
+ files.add(filePath);
56
+ }
57
+ queue.push(...(children.get(id) ?? []));
58
+ }
59
+ collectImportedFiles({ configDirectory, files: [...files] }).forEach((file) => files.add(file));
60
+ return [...files].sort();
61
+ }
62
+
63
+ function findEntryRef({ refMap, refId, pagesFile }) {
64
+ for (let id = refId; refMap[id] !== undefined; id = refMap[id].parent) {
65
+ if (refMap[refMap[id].parent]?.path === pagesFile) {
66
+ return id;
67
+ }
68
+ }
69
+ throw new Error(`Ref ${refId} is not below ${pagesFile} in the build's refMap.`);
70
+ }
71
+
72
+ function recordSourceHashes({ configDirectory, outputDir, pageFrame, pagesFile, refMapPath }) {
73
+ const refMap = JSON.parse(fs.readFileSync(refMapPath, 'utf8'));
74
+ const indexPath = path.join(outputDir, 'index.json');
75
+ const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
76
+ const sources = {};
77
+ index.docs.forEach(({ slug }) => {
78
+ const entryRefId = findEntryRef({ refMap, refId: index.sources[slug].refId, pagesFile });
79
+ const files = collectSourceFiles({ configDirectory, refMap, entryRefId, pageFrame });
80
+ sources[slug] = { files, hash: hashDocSources({ configDirectory, files }) };
81
+ });
82
+ fs.writeFileSync(indexPath, JSON.stringify({ ...index, sources }, null, 2));
83
+ }
84
+
85
+ const { values } = parseArgs({
86
+ options: {
87
+ 'config-directory': { type: 'string' },
88
+ 'page-frame': { type: 'string', default: 'templates/general.yaml.njk' },
89
+ 'pages-file': { type: 'string', default: 'pages.yaml' },
90
+ 'ref-map': { type: 'string' },
91
+ },
92
+ });
93
+
94
+ recordSourceHashes({
95
+ configDirectory: path.resolve(values['config-directory']),
96
+ outputDir: path.resolve(dirname(fileURLToPath(import.meta.url)), '..'),
97
+ pageFrame: values['page-frame'],
98
+ pagesFile: values['pages-file'],
99
+ refMapPath: path.resolve(values['ref-map']),
100
+ });
@@ -0,0 +1,42 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */
16
+
17
+ // Agent doc paths (`<section>/<pageId>`) are public (docs.lowdefy.com/md/,
18
+ // llms.txt) and used as MCP lookup keys, so they must not move when the
19
+ // sidebar is regrouped. The section comes from a fixed `properties.docsSection`
20
+ // in menus.yaml, never from group titles: the page's own link first, then the
21
+ // nearest group above it that sets one, then its menu.
22
+ function resolvePageSections({ menus }) {
23
+ const sectionMap = new Map();
24
+ function walkLinks(links, inheritedSection) {
25
+ (links ?? []).forEach((link) => {
26
+ const section = link.properties?.docsSection ?? inheritedSection;
27
+ if (link.type === 'MenuGroup') {
28
+ walkLinks(link.links, section);
29
+ return;
30
+ }
31
+ if (link.type === 'MenuLink' && link.pageId && section) {
32
+ sectionMap.set(link.pageId, section);
33
+ }
34
+ });
35
+ }
36
+ (menus ?? []).forEach((menu) => {
37
+ walkLinks(menu.links, menu.properties?.docsSection);
38
+ });
39
+ return sectionMap;
40
+ }
41
+
42
+ export default resolvePageSections;
@@ -0,0 +1,27 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */
16
+
17
+ // The plugin type of every page in a section. Sections not named after a
18
+ // plugin type (Reference, Concepts, ...) give their pages no type.
19
+ function sectionKind({ section }) {
20
+ if (section.endsWith('Blocks') || section === 'Controls') return 'block';
21
+ if (section === 'Operators') return 'operator';
22
+ if (section === 'Actions') return 'action';
23
+ if (section === 'Connections') return 'connection';
24
+ return undefined;
25
+ }
26
+
27
+ export default sectionKind;