vitepress-openapi 0.2.16 → 0.2.17

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 (256) hide show
  1. package/dist/{OAJSONEditor-BfaXXObm.js → OAJSONEditor-6uG2SFZK.js} +6 -6
  2. package/dist/{OAJSONEditor-fTqoBDiY.cjs → OAJSONEditor-D-Yhb6db.cjs} +4 -4
  3. package/dist/{angular-html-Dl5L_ndT.js → angular-html-BUsdri4u.js} +2 -2
  4. package/dist/angular-html-BzD9NQW5.cjs +1 -0
  5. package/dist/{angular-ts-ByuE09su.cjs → angular-ts-D1fX05LE.cjs} +1 -1
  6. package/dist/{angular-ts-DATG01QH.js → angular-ts-DLzsnsUB.js} +2 -2
  7. package/dist/{apl-REpE4EOr.cjs → apl-Bo4qJ495.cjs} +1 -1
  8. package/dist/{apl-B903Y1iI.js → apl-D9bD1gNv.js} +5 -5
  9. package/dist/{astro-B6XJ1XzP.js → astro-D8q6Gy7P.js} +5 -5
  10. package/dist/{astro-wd_9JORh.cjs → astro-DCjm-pbh.cjs} +1 -1
  11. package/dist/{blade-CJNVUHnO.cjs → blade-B6fombNo.cjs} +1 -1
  12. package/dist/{blade-DU7K6RH3.js → blade-Sc601tfi.js} +7 -7
  13. package/dist/{c-BFcbaMUO.js → c-CfqZXQ2T.js} +1 -1
  14. package/dist/c-Dn__oIvS.cjs +1 -0
  15. package/dist/{chapel-BDpe9hj3.cjs → chapel-D7VyqyYt.cjs} +1 -1
  16. package/dist/{chapel-CyR2VtwX.js → chapel-xSzmwfXQ.js} +1 -1
  17. package/dist/{cobol-CDgLba1H.cjs → cobol-CAKxSKZT.cjs} +1 -1
  18. package/dist/{cobol-ZUVB5fnm.js → cobol-CHAgZDLS.js} +2 -2
  19. package/dist/{coffee-D9j_lkLc.js → coffee-CeAuLo4O.js} +1 -1
  20. package/dist/{coffee-BxVt1U7S.cjs → coffee-JnCJAydr.cjs} +1 -1
  21. package/dist/{core-DCROFLpl.cjs → core-CNg5cW98.cjs} +3 -3
  22. package/dist/{core-ZiHa6_mm.js → core-s1UIPu_z.js} +114 -114
  23. package/dist/cpp-1aC9AELp.cjs +1 -0
  24. package/dist/{cpp-NN3vBjLe.js → cpp-DAEET6ev.js} +3 -3
  25. package/dist/{crystal-Cg-JMHNA.cjs → crystal-BfArRaXr.cjs} +1 -1
  26. package/dist/{crystal-BCSv9BMD.js → crystal-C1qz7UnE.js} +6 -6
  27. package/dist/css-BVuZPxTF.cjs +1 -0
  28. package/dist/{css-BDew7Z2b.js → css-BZAFXxqD.js} +1 -1
  29. package/dist/{dist-Dsa_0AoM.cjs → dist-CpZb0vTN.cjs} +5 -5
  30. package/dist/{dist-CN9hkg4t.js → dist-DV8PoRsD.js} +1 -1
  31. package/dist/{edge-DXKIJOV7.js → edge-CWZ5MU2M.js} +3 -3
  32. package/dist/{edge-CMIfIdja.cjs → edge-JzsrLjb_.cjs} +1 -1
  33. package/dist/{elixir-BjNct3TS.js → elixir-Crtqxz1W.js} +1 -1
  34. package/dist/{elixir-BmJsBojU.cjs → elixir-QzvqYFsV.cjs} +1 -1
  35. package/dist/{elm-CPQSACRc.js → elm-9rlZJ0du.js} +1 -1
  36. package/dist/{elm-rLsOgMwT.cjs → elm-DTTDc-PO.cjs} +1 -1
  37. package/dist/{engine-javascript-CtAw-nzg.js → engine-javascript-CoT6aZfI.js} +2 -2
  38. package/dist/{engine-javascript-B9hqc1Sn.cjs → engine-javascript-DWPOYZRs.cjs} +2 -2
  39. package/dist/{erb-CQUldNHj.js → erb-C6UwauYe.js} +2 -2
  40. package/dist/{erb-CiTsuMX9.cjs → erb-DPWXQYaP.cjs} +1 -1
  41. package/dist/generate-BAgVJTNQ.js +103 -0
  42. package/dist/generate-BVoluROJ.cjs +1 -0
  43. package/dist/generateMarkdown-BYnrcWs0.js +692 -0
  44. package/dist/generateMarkdown-DyJdABwj.cjs +31 -0
  45. package/dist/{git-rebase-CjFDc1kk.cjs → git-rebase-Cwp0uWvv.cjs} +1 -1
  46. package/dist/{git-rebase-5OapP1hA.js → git-rebase-xIgRvJ_q.js} +1 -1
  47. package/dist/{glimmer-js-DJj4duzR.js → glimmer-js-CNGdvMhA.js} +4 -4
  48. package/dist/{glimmer-js-CPs3ZMWA.cjs → glimmer-js-Df_yNNoE.cjs} +1 -1
  49. package/dist/{glimmer-ts-drtM04VL.js → glimmer-ts-Dq4P7Mkf.js} +4 -4
  50. package/dist/{glimmer-ts-CuERAYsk.cjs → glimmer-ts-DsAOmOGY.cjs} +1 -1
  51. package/dist/glsl-CjiF-xkH.cjs +1 -0
  52. package/dist/{glsl-DPV3oxNS.js → glsl-DZfvb15l.js} +2 -2
  53. package/dist/{graphql-b3MqwVzn.js → graphql-CZmb-US9.js} +5 -5
  54. package/dist/graphql-r7AX53Pp.cjs +1 -0
  55. package/dist/{hack-Dnr29SMc.cjs → hack-Cs2ncrxq.cjs} +1 -1
  56. package/dist/{hack-BV8Fk8S0.js → hack-DIIRgI4h.js} +2 -2
  57. package/dist/haml-3bvHwbYf.cjs +1 -0
  58. package/dist/{haml-DYADyojV.js → haml-aboBnjLl.js} +3 -3
  59. package/dist/{handlebars-XYDCrTNM.cjs → handlebars-C7PZ80pQ.cjs} +1 -1
  60. package/dist/{handlebars-D7Wg8zxD.js → handlebars-Z3oHMxHt.js} +4 -4
  61. package/dist/html-CtaiB3Oi.cjs +1 -0
  62. package/dist/{html-oFWSlHLM.js → html-Cz0Xqdyq.js} +3 -3
  63. package/dist/{html-derivative-B_93GY2L.cjs → html-derivative-BYOQo3PG.cjs} +1 -1
  64. package/dist/{html-derivative-7yg_dBt4.js → html-derivative-BjrHnqif.js} +1 -1
  65. package/dist/{http-BpWcfGzO.cjs → http-BA9nOlAq.cjs} +1 -1
  66. package/dist/{http-C-Hd6Lz4.js → http-ieHS9PeS.js} +4 -4
  67. package/dist/{hurl-D53hSFo7.cjs → hurl-DFGEnvSS.cjs} +1 -1
  68. package/dist/{hurl-DjXOdham.js → hurl-Dg9NkXrC.js} +2 -2
  69. package/dist/{java-CcAzK28d.js → java-DCXCvNHA.js} +1 -1
  70. package/dist/java-DTzZZzv7.cjs +1 -0
  71. package/dist/javascript-DOKgRqe8.cjs +1 -0
  72. package/dist/{javascript-CFpHKvG0.js → javascript-f9cb-Pl7.js} +1 -1
  73. package/dist/{jinja-BzmRQBYE.js → jinja-B2DAjJOY.js} +1 -1
  74. package/dist/{jinja-DhuEKxK7.cjs → jinja-DE8g1bjX.cjs} +1 -1
  75. package/dist/{jison-CfNmROg3.js → jison-5BvvygJS.js} +1 -1
  76. package/dist/{jison-DkP6w3Kb.cjs → jison-BCQciWJO.cjs} +1 -1
  77. package/dist/js-yaml-B-Up3zwX.cjs +28 -0
  78. package/dist/{js-yaml-xxJ42vHJ.js → js-yaml-o4oD1Gp3.js} +1 -1
  79. package/dist/json-BcxNDt_H.cjs +1 -0
  80. package/dist/{json-BUhydBtV.js → json-DZfYi9f2.js} +1 -1
  81. package/dist/{jsx-BgXsA-DL.js → jsx-D0ksVAAA.js} +1 -1
  82. package/dist/jsx-DxOBIFYM.cjs +1 -0
  83. package/dist/{julia-CFY_QNYf.cjs → julia-B3y7weJz.cjs} +1 -1
  84. package/dist/{julia-QFUzXXyx.js → julia-Dk4vCuW5.js} +4 -4
  85. package/dist/{just-unRxJYdl.cjs → just-B7ftAo6t.cjs} +1 -1
  86. package/dist/{just-BQQqo7uc.js → just-BDbjiXnk.js} +5 -5
  87. package/dist/{latex-61rhD9l1.js → latex-CC_8gzv9.js} +1 -1
  88. package/dist/{latex-CMXzYJ7A.cjs → latex-QeOQCy8M.cjs} +1 -1
  89. package/dist/{liquid-Dlc1A5fD.cjs → liquid-BVZIda1i.cjs} +1 -1
  90. package/dist/{liquid-DJCM2ZDj.js → liquid-CJVpPXmh.js} +4 -4
  91. package/dist/llms-DWks2vGp.cjs +26 -0
  92. package/dist/llms-yFQ0insM.js +418 -0
  93. package/dist/lua-BoAqNcbB.cjs +1 -0
  94. package/dist/{lua-CQxTc8eB.js → lua-Bwwgpolt.js} +2 -2
  95. package/dist/{marko-lDIEsg9U.cjs → marko-CX9I4GhY.cjs} +1 -1
  96. package/dist/{marko-Dd0qsahM.js → marko-z-UpeqN9.js} +3 -3
  97. package/dist/{mdc-_80um6kj.js → mdc-ANp6h8jQ.js} +2 -2
  98. package/dist/{mdc-CyWtd_UH.cjs → mdc-BPd7ZDIZ.cjs} +1 -1
  99. package/dist/{nginx-DDrDrYzT.js → nginx-BUK9HsFk.js} +1 -1
  100. package/dist/{nginx-Bys-Mt_F.cjs → nginx-CLECRmW5.cjs} +1 -1
  101. package/dist/{nim-B-WnW_TA.cjs → nim-4G662efB.cjs} +1 -1
  102. package/dist/{nim-BKM9BEwv.js → nim-pupbS7ww.js} +6 -6
  103. package/dist/{useOpenapi-Dr3AneGd.js → normalizeExamples-BFR42ENV.js} +4055 -2184
  104. package/dist/normalizeExamples-DNaOGXm0.cjs +45 -0
  105. package/dist/{org-DFPWKQMZ.js → org-B8vjAQ9v.js} +26 -26
  106. package/dist/{org-BQi9zqMo.cjs → org-XYh7PPQk.cjs} +1 -1
  107. package/dist/{perl-BIiCtWTQ.js → perl-ChiZYWB8.js} +5 -5
  108. package/dist/{perl-CkLK5ExR.cjs → perl-Qi4toP6W.cjs} +1 -1
  109. package/dist/{php-CgjckyHQ.cjs → php-93axekrF.cjs} +1 -1
  110. package/dist/{php-DOw5HPZo.js → php-JTDYSOFN.js} +6 -6
  111. package/dist/{pug-ZRJG_B3i.cjs → pug-BHWWe-s7.cjs} +1 -1
  112. package/dist/{pug-BGkLdaFt.js → pug-BR1NlFnA.js} +3 -3
  113. package/dist/{qml-BHFWpY8E.cjs → qml-71TJR8lk.cjs} +1 -1
  114. package/dist/{qml-Bpj0emxI.js → qml-BBCxB4Da.js} +1 -1
  115. package/dist/r-BVapaf2o.cjs +1 -0
  116. package/dist/{r-beK_-64Q.js → r-u-VAz7bR.js} +1 -1
  117. package/dist/{razor-Q3MoMGDn.js → razor-Cqi5RzG6.js} +1 -1
  118. package/dist/{razor-COBqjWAJ.cjs → razor-DMdT60zm.cjs} +1 -1
  119. package/dist/{regexp-BsdKen3m.js → regexp-9Pkh3Nf7.js} +1 -1
  120. package/dist/regexp-CwHm4hi_.cjs +1 -0
  121. package/dist/{rst-B0t1spY-.cjs → rst-BtwmHjj9.cjs} +1 -1
  122. package/dist/{rst-DpM5_nag.js → rst-CLZRH5oU.js} +6 -6
  123. package/dist/{ruby-kbh8ViY5.js → ruby-BZUQEFGQ.js} +12 -12
  124. package/dist/{ruby-CsFQlb64.cjs → ruby-DuGe7Fs0.cjs} +1 -1
  125. package/dist/{sas-CnYUys8b.cjs → sas-B7hIWqYI.cjs} +1 -1
  126. package/dist/{sas-BgQhrf78.js → sas-BO2zDPuE.js} +1 -1
  127. package/dist/scss-BpK0m8eZ.cjs +1 -0
  128. package/dist/{scss-NPDrxHVt.js → scss-OFCrSwaR.js} +2 -2
  129. package/dist/{shellscript-DhwNgJpI.js → shellscript-BNTFxSmg.js} +1 -1
  130. package/dist/shellscript-KJDkFDLp.cjs +1 -0
  131. package/dist/{shellsession-BzIHueWc.js → shellsession-B5j5FuGA.js} +1 -1
  132. package/dist/{shellsession-D7Pf_B_j.cjs → shellsession-DWalcvtJ.cjs} +1 -1
  133. package/dist/{soy-Bacl__9y.cjs → soy-BQn3ItqC.cjs} +1 -1
  134. package/dist/{soy-xHdJtla5.js → soy-C2Q794LP.js} +1 -1
  135. package/dist/{sql-AGUE5-dk.js → sql-8JHRpHTE.js} +1 -1
  136. package/dist/sql-C5y5nUuw.cjs +1 -0
  137. package/dist/{stata-BpsgLaw1.js → stata-BrNyU7bS.js} +1 -1
  138. package/dist/{stata-ByZ8yj3l.cjs → stata-DyBO95gA.cjs} +1 -1
  139. package/dist/{surrealql-Dfwdqk76.cjs → surrealql-CAAIvFqO.cjs} +1 -1
  140. package/dist/{surrealql-CE6SK0JG.js → surrealql-DgN6gei3.js} +1 -1
  141. package/dist/{svelte-DRtnTFsc.cjs → svelte-DGjw_UH1.cjs} +1 -1
  142. package/dist/{svelte-B8Y6hosE.js → svelte-FhQBX-tv.js} +3 -3
  143. package/dist/{templ-BofvAMnQ.js → templ-BUggPx5p.js} +2 -2
  144. package/dist/{templ-BIgW0e2S.cjs → templ-Cxuj5rzV.cjs} +1 -1
  145. package/dist/tex-B3aY5DbH.cjs +1 -0
  146. package/dist/{tex-CLtxJoaQ.js → tex-BlOdu2Xy.js} +2 -2
  147. package/dist/{ts-tags-Cv2SdymF.cjs → ts-tags-BymwG1F9.cjs} +1 -1
  148. package/dist/{ts-tags-DRRvATIb.js → ts-tags-DZBZzNkR.js} +7 -7
  149. package/dist/tsx-DgA8B92F.cjs +1 -0
  150. package/dist/{tsx--6NZUZt2.js → tsx-mByJmMSt.js} +1 -1
  151. package/dist/{twig-BTg98s4P.js → twig--2v8RtVi.js} +5 -5
  152. package/dist/{twig-C8K9fEv7.cjs → twig-CWwcCfHy.cjs} +1 -1
  153. package/dist/types/src/cli.d.ts +1 -0
  154. package/dist/types/src/components/Common/Highlight/OAShiki.vue.d.ts +2 -2
  155. package/dist/types/src/components/Common/Highlight/OAVueJsonPretty.vue.d.ts +2 -2
  156. package/dist/types/src/components/Common/OACodeBlock.vue.d.ts +2 -2
  157. package/dist/types/src/components/Common/OACodeValue.vue.d.ts +2 -2
  158. package/dist/types/src/components/Common/OAJSONEditor.vue.d.ts +2 -2
  159. package/dist/types/src/components/Parameter/OAParameterAttribute.vue.d.ts +2 -2
  160. package/dist/types/src/components/Playground/OAPlaygroundParameterInput.vue.d.ts +2 -2
  161. package/dist/types/src/components/ui/badge/index.d.ts +1 -1
  162. package/dist/types/src/components/ui/button/index.d.ts +1 -1
  163. package/dist/types/src/index.d.ts +18 -3
  164. package/dist/types/src/lib/codeSamples/buildOperationRequest.d.ts +15 -0
  165. package/dist/types/src/lib/codeSamples/buildRequest.d.ts +6 -0
  166. package/dist/types/src/lib/constants.d.ts +3 -0
  167. package/dist/types/src/lib/markdown/generateMarkdown.d.ts +111 -0
  168. package/dist/types/src/lib/markdown/llmsSite.d.ts +137 -0
  169. package/dist/types/src/lib/markdown/markdownUtils.d.ts +35 -0
  170. package/dist/types/src/lib/markdown/operationToMarkdown.d.ts +66 -0
  171. package/dist/types/src/lib/parser/getSchemaUi.d.ts +1 -0
  172. package/dist/types/src/node/cli.d.ts +5 -0
  173. package/dist/types/src/node/generate.d.ts +38 -0
  174. package/dist/types/src/node/llms.d.ts +99 -0
  175. package/dist/types/src/node/llmsPlugin.d.ts +10 -0
  176. package/dist/typescript-BWfpZQ2O.cjs +1 -0
  177. package/dist/{typescript-DBKp3fLc.js → typescript-DF15DAwn.js} +1 -1
  178. package/dist/{typst-wzR7m38K.cjs → typst-BEqsnZtv.cjs} +1 -1
  179. package/dist/{typst-BMPcWpxF.js → typst-uhRd3eU5.js} +29 -29
  180. package/dist/useSidebar-B2LH297o.cjs +6 -0
  181. package/dist/useSidebar-CoebjdWM.js +313 -0
  182. package/dist/vitepress-openapi.cli.cjs.js +22 -0
  183. package/dist/vitepress-openapi.cli.es.js +67 -0
  184. package/dist/vitepress-openapi.client.cjs.js +1 -1
  185. package/dist/vitepress-openapi.client.es.js +7 -6
  186. package/dist/vitepress-openapi.node.cjs.js +1 -1
  187. package/dist/vitepress-openapi.node.es.js +47 -2
  188. package/dist/vitepress-openapi.vue.cjs.js +1 -1
  189. package/dist/vitepress-openapi.vue.es.js +4 -3
  190. package/dist/{vue-DLzq6csB.cjs → vue-BQl-5Fd6.cjs} +1 -1
  191. package/dist/{vue-DWAybQg2.js → vue-CSJXDMn1.js} +6 -6
  192. package/dist/{vue-CPzdKbEl.js → vue-DIM9jH1x.js} +2483 -4670
  193. package/dist/vue-DwsEa2e4.cjs +7 -0
  194. package/dist/{vue-html-IeY1Py_m.cjs → vue-html-AqZQgz92.cjs} +1 -1
  195. package/dist/{vue-html-BSam2lRJ.js → vue-html-DYm4V3uo.js} +1 -1
  196. package/dist/{vue-vine-icUsAH0H.js → vue-vine-BLrCVeql.js} +3 -3
  197. package/dist/{vue-vine-Db6Q7xvd.cjs → vue-vine-C1QCIUv6.cjs} +1 -1
  198. package/dist/xml-DbN80t5u.cjs +1 -0
  199. package/dist/{xml-Cj_af9Z1.js → xml-Df1jLF7H.js} +2 -2
  200. package/dist/{xsl-DblyyLAc.cjs → xsl-7fKL5NbN.cjs} +1 -1
  201. package/dist/{xsl-D-tBFomZ.js → xsl-C2LJLnIq.js} +1 -1
  202. package/dist/{yaml-D4q2Gm3x.js → yaml-DABI1u00.js} +1 -1
  203. package/dist/yaml-DNB0t8B9.cjs +1 -0
  204. package/package.json +4 -1
  205. package/src/cli.ts +6 -0
  206. package/src/composables/useSidebar.ts +1 -1
  207. package/src/index.ts +26 -5
  208. package/src/lib/codeSamples/buildHarRequest.ts +5 -0
  209. package/src/lib/codeSamples/buildOperationRequest.ts +52 -0
  210. package/src/lib/codeSamples/buildRequest.ts +49 -28
  211. package/src/lib/constants.ts +5 -0
  212. package/src/lib/examples/getSchemaUiJson.ts +1 -1
  213. package/src/lib/markdown/generateMarkdown.ts +451 -0
  214. package/src/lib/markdown/llmsSite.ts +475 -0
  215. package/src/lib/markdown/markdownUtils.ts +104 -0
  216. package/src/lib/markdown/operationToMarkdown.ts +834 -0
  217. package/src/lib/parser/generateCodeSamples.ts +6 -31
  218. package/src/lib/parser/generateMissingOperationIds.ts +1 -1
  219. package/src/lib/parser/generateMissingSummary.ts +1 -1
  220. package/src/lib/parser/generateMissingTags.ts +1 -1
  221. package/src/lib/parser/generateRequestBodyUi.ts +1 -1
  222. package/src/lib/parser/generateResponseUi.ts +1 -1
  223. package/src/lib/parser/generateSecurityUi.ts +1 -1
  224. package/src/lib/parser/getSchemaUi.ts +7 -3
  225. package/src/lib/sidebar/generateSidebarItemsByPaths.ts +1 -1
  226. package/src/lib/spec/createOpenApiSpec.ts +1 -1
  227. package/src/node/cli.ts +107 -0
  228. package/src/node/generate.ts +207 -0
  229. package/src/node/llms.ts +431 -0
  230. package/src/node/llmsPlugin.ts +29 -0
  231. package/dist/angular-html-Dk2XGZ_t.cjs +0 -1
  232. package/dist/c-DkEd8-YD.cjs +0 -1
  233. package/dist/cpp-BPWm4FiD.cjs +0 -1
  234. package/dist/css-Cca861pZ.cjs +0 -1
  235. package/dist/glsl-vKFvWHtP.cjs +0 -1
  236. package/dist/graphql-DG0SCdKc.cjs +0 -1
  237. package/dist/haml-cdCU_QQV.cjs +0 -1
  238. package/dist/html-DOohh95v.cjs +0 -1
  239. package/dist/java-YSQdp8jH.cjs +0 -1
  240. package/dist/javascript-CcZ4Z9Pe.cjs +0 -1
  241. package/dist/js-yaml-D7HstSVO.cjs +0 -28
  242. package/dist/json-BuUbxxHW.cjs +0 -1
  243. package/dist/jsx-LBqujUwg.cjs +0 -1
  244. package/dist/lua-De5jN6Ym.cjs +0 -1
  245. package/dist/r-CP5u50Ge.cjs +0 -1
  246. package/dist/regexp-Cquj00oh.cjs +0 -1
  247. package/dist/scss-FW7lpUTk.cjs +0 -1
  248. package/dist/shellscript-C1Cbf_Wu.cjs +0 -1
  249. package/dist/sql-BCbZO9Vk.cjs +0 -1
  250. package/dist/tex-UEva1VjO.cjs +0 -1
  251. package/dist/tsx-CRyT9Jau.cjs +0 -1
  252. package/dist/typescript-BbUbA8EZ.cjs +0 -1
  253. package/dist/useOpenapi-Bt0dpttK.cjs +0 -50
  254. package/dist/vue-Da82SaTm.cjs +0 -7
  255. package/dist/xml-An_1AySF.cjs +0 -1
  256. package/dist/yaml-BZ7EODQj.cjs +0 -1
@@ -0,0 +1,475 @@
1
+ import type { OpenAPIDocument } from '../../types'
2
+ import type { OpenApiSpecInstance } from '../spec/createOpenApiSpec'
3
+ import type { MarkdownFile, OperationEntry, TagGroup } from './generateMarkdown'
4
+ import type { OperationToMarkdownOptions } from './operationToMarkdown'
5
+ import { LLMS_FULL_SEPARATOR, llmsOperationLink, prepareMarkdownSpec, renderIndex, renderLlmsFullHeader, renderLlmsTxt } from './generateMarkdown'
6
+ import { escapeLinkLabel, heading, inlineCode } from './markdownUtils'
7
+ import { operationToMarkdown, rewriteOperationLinks } from './operationToMarkdown'
8
+
9
+ export interface LlmsSiteOptions extends Omit<OperationToMarkdownOptions, 'headingLevel' | 'operationLink'> {
10
+ /**
11
+ * Route of the operation pages, relative to the site root, with an `{operationId}`
12
+ * placeholder (e.g. `'operations/{operationId}'`).
13
+ */
14
+ operationRoute: string
15
+ /** Routes of pages rendering the whole spec (e.g. `OASpec`): they get every operation. */
16
+ specRoutes?: string[]
17
+ /** Route of the API overview page (title, servers, authentication and operations by tag). */
18
+ introductionRoute?: string
19
+ /**
20
+ * Route of the tag pages, with a `{tag}` placeholder (e.g. `'tags/{tag}'`).
21
+ * Each gets the tag description and all its operations.
22
+ */
23
+ tagRoute?: string
24
+ /**
25
+ * Value of `{tag}` for a tag name. Must match the route params of your tag pages.
26
+ * Defaults to the tag name as is, like `usePaths().getTags()`.
27
+ */
28
+ tagParam?: (tag: string) => string
29
+ /**
30
+ * Extension of the files written next to each page.
31
+ * @default 'md'
32
+ */
33
+ extension?: 'md' | 'txt'
34
+ /**
35
+ * Also generate `llms.txt` and `llms-full.txt` at the site root.
36
+ * @default true
37
+ */
38
+ llmsTxt?: boolean
39
+ /** Tag for operations without tags. */
40
+ defaultTag?: string
41
+ /**
42
+ * Maximum size in bytes of a file with many operations (whole-spec pages, tag pages and
43
+ * `llms-full.txt`). Above it, a summary is written instead: the overview and one line per
44
+ * operation. `false` (or `Infinity`) disables the limit.
45
+ * @default 5 * 1024 * 1024
46
+ */
47
+ maxSize?: number | false
48
+ }
49
+
50
+ export interface LlmsSiteFilesOptions extends LlmsSiteOptions {
51
+ /**
52
+ * Site base path, used in links.
53
+ * @default '/'
54
+ */
55
+ base?: string
56
+ /** Whether a route has a page. Routes without one get no file and no link. */
57
+ hasPage?: (route: string) => boolean | Promise<boolean>
58
+ }
59
+
60
+ export const DEFAULT_LLMS_MAX_SIZE = 5 * 1024 * 1024
61
+
62
+ const OPERATION_ID_PLACEHOLDER = '{operationId}'
63
+ const TAG_PLACEHOLDER = '{tag}'
64
+ const RE_EDGE_SLASHES = /^\/+|\/+$/g
65
+ const RE_PAGE_EXTENSION = /\.(?:md|html)$/
66
+
67
+ /**
68
+ * Normalizes a route: no leading/trailing slashes and no `.md`/`.html` extension.
69
+ */
70
+ export function normalizeRoute(route: string): string {
71
+ return route.replace(RE_EDGE_SLASHES, '').replace(RE_PAGE_EXTENSION, '')
72
+ }
73
+
74
+ /**
75
+ * UTF-8 byte length of a string, without encoding it.
76
+ */
77
+ export function utf8Length(text: string): number {
78
+ let length = 0
79
+ for (let index = 0; index < text.length; index++) {
80
+ const code = text.charCodeAt(index)
81
+ if (code < 0x80) {
82
+ length += 1
83
+ }
84
+ else if (code < 0x800) {
85
+ length += 2
86
+ }
87
+ else if (code >= 0xD800 && code <= 0xDBFF) {
88
+ // Surrogate pair: one 4-byte character.
89
+ length += 4
90
+ index++
91
+ }
92
+ else {
93
+ length += 3
94
+ }
95
+ }
96
+ return length
97
+ }
98
+
99
+ function resolveMaxSize(maxSize: number | false | undefined): number {
100
+ return maxSize === false ? Number.POSITIVE_INFINITY : (maxSize ?? DEFAULT_LLMS_MAX_SIZE)
101
+ }
102
+
103
+ function formatSize(bytes: number): string {
104
+ return bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.ceil(bytes / 1024)} KB`
105
+ }
106
+
107
+ /**
108
+ * Joins `head` and `count` parts (rendered one at a time) with `separator`, plus a final newline.
109
+ * Stops as soon as the size exceeds `maxSize`, without building the whole string.
110
+ */
111
+ async function joinWithinSize(
112
+ head: string,
113
+ count: number,
114
+ renderPart: (index: number) => string | Promise<string>,
115
+ separator: string,
116
+ maxSize: number,
117
+ ): Promise<{ content: string } | { exceeded: number }> {
118
+ const parts = [head]
119
+ let size = utf8Length(head) + 1
120
+ for (let index = 0; index < count; index++) {
121
+ const part = await renderPart(index)
122
+ size += utf8Length(separator) + utf8Length(part)
123
+ if (size > maxSize) {
124
+ return { exceeded: size }
125
+ }
126
+ parts.push(part)
127
+ }
128
+ return { content: `${parts.join(separator)}\n` }
129
+ }
130
+
131
+ function warnSize(label: string, size: number, maxSize: number): void {
132
+ console.warn(`[vitepress-openapi] ${label}: over ${size} bytes, more than maxSize (${maxSize} bytes): wrote a summary instead.`)
133
+ }
134
+
135
+ export interface LlmsSummaryOptions {
136
+ /** URL of an operation's page, or `undefined` to list it as plain text. */
137
+ operationUrl?: (operation: OperationEntry) => string | undefined
138
+ /** Link to the full spec, in the note. */
139
+ specUrl?: string
140
+ openapiUrl?: string
141
+ maxSize: number
142
+ /** Summarize a single tag (a tag page) instead of the whole spec. */
143
+ group?: TagGroup
144
+ }
145
+
146
+ /**
147
+ * Summary written instead of a file over `maxSize`: a note, the overview (or the tag) and
148
+ * one line per operation, grouped by tag.
149
+ */
150
+ export function renderLlmsSummary(openapi: OpenApiSpecInstance, groups: TagGroup[], options: LlmsSummaryOptions): string {
151
+ const specUrl = options.specUrl ?? options.openapiUrl
152
+ const note = `> **Note:** the full content is larger than ${formatSize(options.maxSize)}, so only a summary of each operation is included.${
153
+ specUrl ? ` See the [OpenAPI specification](${specUrl}) for every detail.` : ''}`
154
+
155
+ const line = (operation: OperationEntry) => {
156
+ const url = options.operationUrl?.(operation)
157
+ const summary = url ? `[${escapeLinkLabel(operation.summary)}](${url})` : operation.summary
158
+ return `- ${inlineCode(`${operation.method.toUpperCase()} ${operation.path}`)} – ${summary}`
159
+ }
160
+
161
+ if (options.group) {
162
+ const group = options.group
163
+ return `${[heading(1, group.name), note, group.description?.trim(), group.operations.map(line).join('\n')].filter(Boolean).join('\n\n')}\n`
164
+ }
165
+
166
+ const [title, ...overview] = renderIndex(openapi, [], { openapiUrl: options.openapiUrl }).split('\n\n')
167
+ const sections = groups
168
+ .filter(group => group.operations.length)
169
+ .map(group => `${heading(2, group.name)}\n\n${group.operations.map(line).join('\n')}`)
170
+ return `${[title, note, ...overview, ...sections].join('\n\n')}\n`
171
+ }
172
+
173
+ /**
174
+ * `base` + `path`, each path segment percent-encoded (so `?` and `#` in a tag or operationId stay in the path).
175
+ */
176
+ export function joinUrl(base: string, path: string): string {
177
+ return `${base.endsWith('/') ? base : `${base}/`}${path.split('/').map(encodeURIComponent).join('/')}`
178
+ }
179
+
180
+ export interface LlmsSiteEntry {
181
+ /** Page files (no `llms.txt`/`llms-full.txt`). */
182
+ files: MarkdownFile[]
183
+ /** `llms-full.txt` content: every operation of the spec, or a summary when over `maxSize`. */
184
+ full: string
185
+ /** Logs a warning if `full` is a summary (call it when writing `llms-full.txt`). */
186
+ warnFull: () => void
187
+ /** `llms.txt` content, with optional extra `## Section` blocks. */
188
+ renderLlmsTxt: (extraSections?: string[]) => string
189
+ /** This spec as a single `llms.txt` section, to merge it into another one. */
190
+ renderLlmsSection: () => string
191
+ }
192
+
193
+ /**
194
+ * Markdown files for a site: one per operation page (`{route}.{extension}`), one per
195
+ * whole-spec page, and `llms.txt`/`llms-full.txt`. Paths are relative to the site output.
196
+ */
197
+ export async function generateLlmsSiteFiles(
198
+ spec: OpenAPIDocument | string | OpenApiSpecInstance,
199
+ options: LlmsSiteFilesOptions,
200
+ ): Promise<MarkdownFile[]> {
201
+ const entry = await buildLlmsSiteEntry(spec, options)
202
+ return options.llmsTxt === false
203
+ ? entry.files
204
+ : (entry.warnFull(), [
205
+ ...entry.files,
206
+ { path: 'llms.txt', content: entry.renderLlmsTxt() },
207
+ { path: 'llms-full.txt', content: entry.full },
208
+ ])
209
+ }
210
+
211
+ /**
212
+ * Like `generateLlmsSiteFiles`, but returns the `llms.txt` parts so several specs can be merged.
213
+ */
214
+ export async function buildLlmsSiteEntry(
215
+ spec: OpenAPIDocument | string | OpenApiSpecInstance,
216
+ options: LlmsSiteFilesOptions,
217
+ ): Promise<LlmsSiteEntry> {
218
+ const {
219
+ operationRoute,
220
+ specRoutes = [],
221
+ introductionRoute,
222
+ tagRoute,
223
+ tagParam = (tag: string) => tag,
224
+ extension = 'md',
225
+ llmsTxt: _llmsTxt,
226
+ base = '/',
227
+ defaultTag,
228
+ hasPage = () => true,
229
+ maxSize: maxSizeOption,
230
+ ...operationOptions
231
+ } = options
232
+ const maxSize = resolveMaxSize(maxSizeOption)
233
+
234
+ if (!operationRoute?.includes(OPERATION_ID_PLACEHOLDER)) {
235
+ throw new Error(`[vitepress-openapi] \`operationRoute\` must contain ${OPERATION_ID_PLACEHOLDER}.`)
236
+ }
237
+ if (tagRoute !== undefined && !tagRoute.includes(TAG_PLACEHOLDER)) {
238
+ throw new Error(`[vitepress-openapi] \`tagRoute\` must contain ${TAG_PLACEHOLDER}.`)
239
+ }
240
+
241
+ const { openapi, operations, groups } = prepareMarkdownSpec(spec, defaultTag)
242
+ const routeFor = (operationId: string) => normalizeRoute(operationRoute.replaceAll(OPERATION_ID_PLACEHOLDER, operationId))
243
+ const urlFor = (route: string) => joinUrl(base, `${route}.${extension}`)
244
+
245
+ const withPage = new Set<string>()
246
+ for (const operation of operations) {
247
+ if (await hasPage(routeFor(operation.operationId))) {
248
+ withPage.add(operation.operationId)
249
+ }
250
+ }
251
+
252
+ const tagRouteFor = (group: TagGroup) => normalizeRoute(tagRoute!.replaceAll(TAG_PLACEHOLDER, tagParam(group.name)))
253
+ const tagsWithPage = new Set<TagGroup>()
254
+ if (tagRoute) {
255
+ for (const group of groups) {
256
+ if (await hasPage(tagRouteFor(group))) {
257
+ tagsWithPage.add(group)
258
+ }
259
+ }
260
+ }
261
+ const tagUrl = (group: TagGroup) => tagsWithPage.has(group) ? urlFor(tagRouteFor(group)) : undefined
262
+ const operationUrl = (operation: OperationEntry) => withPage.has(operation.operationId) ? urlFor(routeFor(operation.operationId)) : undefined
263
+ const introduction = introductionRoute ? normalizeRoute(introductionRoute) : ''
264
+ const hasIntroduction = !!introduction && await hasPage(introduction)
265
+
266
+ // Operation links point to sibling files; operations without a page keep their original link.
267
+ const operationLink = {
268
+ href: (operationId: string) => withPage.has(operationId) ? urlFor(routeFor(operationId)) : undefined,
269
+ }
270
+ groups.forEach((group) => {
271
+ group.description = rewriteOperationLinks(group.description, openapi, operationLink)
272
+ })
273
+
274
+ const rendered = new Map<string, string>()
275
+ for (const operation of operations) {
276
+ rendered.set(operation.operationId, await operationToMarkdown(openapi, operation.operationId, {
277
+ ...operationOptions,
278
+ operationLink,
279
+ headingLevel: 1,
280
+ }))
281
+ }
282
+
283
+ const files: MarkdownFile[] = operations
284
+ .filter(operation => withPage.has(operation.operationId))
285
+ .map(operation => ({
286
+ path: `${routeFor(operation.operationId)}.${extension}`,
287
+ content: `${rendered.get(operation.operationId)}\n`,
288
+ }))
289
+
290
+ // `llms-full.txt` and whole-spec pages: every operation, or a summary when over `maxSize`.
291
+ const renderedOperations = [...rendered.values()]
292
+ const fullResult = await joinWithinSize(renderLlmsFullHeader(openapi), renderedOperations.length, index => renderedOperations[index], LLMS_FULL_SEPARATOR, maxSize)
293
+ const full = 'content' in fullResult
294
+ ? fullResult.content
295
+ : renderLlmsSummary(openapi, groups, { operationUrl, openapiUrl: operationOptions.openapiUrl, maxSize })
296
+ const warnFull = (label: string) => {
297
+ if ('exceeded' in fullResult) {
298
+ warnSize(label, fullResult.exceeded, maxSize)
299
+ }
300
+ }
301
+
302
+ if (hasIntroduction) {
303
+ files.push({
304
+ path: `${introduction}.${extension}`,
305
+ content: `${renderIndex(openapi, groups, {
306
+ operationUrl,
307
+ tagUrl,
308
+ openapiUrl: operationOptions.openapiUrl,
309
+ rewriteLinks: markdown => rewriteOperationLinks(markdown, openapi, operationLink),
310
+ })}\n`,
311
+ })
312
+ }
313
+
314
+ for (const group of tagsWithPage) {
315
+ const path = `${tagRouteFor(group)}.${extension}`
316
+ const result = await joinWithinSize(
317
+ [heading(1, group.name), group.description?.trim()].filter(Boolean).join('\n\n'),
318
+ group.operations.length,
319
+ index => operationToMarkdown(openapi, group.operations[index].operationId, { ...operationOptions, operationLink, headingLevel: 2 }),
320
+ '\n\n',
321
+ maxSize,
322
+ )
323
+ if ('exceeded' in result) {
324
+ warnSize(path, result.exceeded, maxSize)
325
+ }
326
+ files.push({
327
+ path,
328
+ content: 'content' in result
329
+ ? result.content
330
+ : renderLlmsSummary(openapi, groups, { group, operationUrl, openapiUrl: operationOptions.openapiUrl, maxSize }),
331
+ })
332
+ }
333
+
334
+ for (const route of specRoutes.map(normalizeRoute)) {
335
+ if (route && await hasPage(route)) {
336
+ const path = `${route}.${extension}`
337
+ warnFull(path)
338
+ files.push({ path, content: full })
339
+ }
340
+ }
341
+
342
+ // Only linked entries: operations with a page, and tags with a page or such operations.
343
+ const linkedGroups = groups
344
+ .filter(group => tagsWithPage.has(group) || group.operations.some(operation => withPage.has(operation.operationId)))
345
+ .map(group => ({ ...group, operations: group.operations.filter(operation => withPage.has(operation.operationId)) }))
346
+ const links = {
347
+ operationUrl: (operation: OperationEntry) => urlFor(routeFor(operation.operationId)),
348
+ overviewUrl: hasIntroduction ? urlFor(introduction) : undefined,
349
+ tagUrl: (group: TagGroup) => tagUrl(groups.find(original => original.name === group.name)!),
350
+ fullUrl: joinUrl(base, 'llms-full.txt'),
351
+ openapiUrl: operationOptions.openapiUrl,
352
+ }
353
+
354
+ return {
355
+ files,
356
+ full,
357
+ warnFull: () => warnFull('llms-full.txt'),
358
+ renderLlmsTxt: extraSections => renderLlmsTxt(openapi, linkedGroups, { ...links, extraSections }),
359
+ renderLlmsSection: () => {
360
+ const lines = [
361
+ links.overviewUrl && `- [Overview](${links.overviewUrl}): API description, servers, authentication and all operations`,
362
+ ...linkedGroups.flatMap(group => group.operations.map(operation => llmsOperationLink(operation, links.operationUrl(operation)))),
363
+ ].filter(Boolean)
364
+ return [heading(2, String(openapi.getInfo()?.title || 'API Reference')), lines.join('\n')].join('\n\n')
365
+ },
366
+ }
367
+ }
368
+
369
+ export type LlmsPageMode = 'spec' | 'operation' | 'introduction' | 'tag'
370
+
371
+ export interface LlmsPageOptions extends Omit<OperationToMarkdownOptions, 'headingLevel' | 'operationLink'> {
372
+ /** @default 'spec' */
373
+ mode?: LlmsPageMode
374
+ operationId?: string
375
+ tag?: string
376
+ defaultTag?: string
377
+ /** See `LlmsSiteOptions.maxSize`. Applies to the `'spec'` and `'tag'` modes. */
378
+ maxSize?: number | false
379
+ /** URL of the page's spec, linked from the summary note. */
380
+ specUrl?: string
381
+ /** Name of the file in warnings (e.g. its route). */
382
+ label?: string
383
+ }
384
+
385
+ /**
386
+ * Markdown of a page that renders its own spec: the whole spec, an operation, the overview or a tag.
387
+ * Operation links become plain text: they would point to pages of another spec.
388
+ * Returns `undefined` when the operation or tag doesn't exist.
389
+ */
390
+ export async function renderLlmsPage(
391
+ spec: OpenAPIDocument | string | OpenApiSpecInstance,
392
+ options: LlmsPageOptions = {},
393
+ ): Promise<{ title: string, content: string } | undefined> {
394
+ const { mode = 'spec', operationId, tag, defaultTag, maxSize: maxSizeOption, specUrl, label = 'page', ...operationOptions } = options
395
+ const maxSize = resolveMaxSize(maxSizeOption)
396
+ const { openapi, operations, groups } = prepareMarkdownSpec(spec, defaultTag)
397
+ const operationLink = { href: () => null }
398
+ const title = String(openapi.getInfo()?.title || 'API Reference')
399
+ const render = (id: string, headingLevel: number) => operationToMarkdown(openapi, id, { ...operationOptions, operationLink, headingLevel })
400
+
401
+ if (mode === 'operation') {
402
+ const operation = operations.find(operation => operation.operationId === operationId)
403
+ return operation ? { title: operation.summary, content: `${await render(operation.operationId, 1)}\n` } : undefined
404
+ }
405
+
406
+ if (mode === 'introduction') {
407
+ const rewriteLinks = (markdown: string) => rewriteOperationLinks(markdown, openapi, operationLink)
408
+ groups.forEach((group) => {
409
+ group.description = rewriteLinks(group.description)
410
+ })
411
+ return { title, content: `${renderIndex(openapi, groups, { openapiUrl: operationOptions.openapiUrl, rewriteLinks })}\n` }
412
+ }
413
+
414
+ if (mode === 'tag') {
415
+ const group = groups.find(group => group.name === tag)
416
+ if (!group) {
417
+ return undefined
418
+ }
419
+ group.description = rewriteOperationLinks(group.description, openapi, operationLink)
420
+ const result = await joinWithinSize(
421
+ [heading(1, group.name), group.description?.trim()].filter(Boolean).join('\n\n'),
422
+ group.operations.length,
423
+ index => render(group.operations[index].operationId, 2),
424
+ '\n\n',
425
+ maxSize,
426
+ )
427
+ if ('content' in result) {
428
+ return { title: group.name, content: result.content }
429
+ }
430
+ warnSize(label, result.exceeded, maxSize)
431
+ return { title: group.name, content: renderLlmsSummary(openapi, groups, { group, specUrl, openapiUrl: operationOptions.openapiUrl, maxSize }) }
432
+ }
433
+
434
+ const result = await joinWithinSize(renderLlmsFullHeader(openapi), operations.length, index => render(operations[index].operationId, 1), LLMS_FULL_SEPARATOR, maxSize)
435
+ if ('content' in result) {
436
+ return { title, content: result.content }
437
+ }
438
+ warnSize(label, result.exceeded, maxSize)
439
+ return { title, content: renderLlmsSummary(openapi, groups, { specUrl, openapiUrl: operationOptions.openapiUrl, maxSize }) }
440
+ }
441
+
442
+ /**
443
+ * Path of a request relative to the site base (decoded, without query), or `undefined`.
444
+ */
445
+ export function getLlmsRequestPath(url: string | undefined, base: string): string | undefined {
446
+ if (!url) {
447
+ return undefined
448
+ }
449
+ let pathname: string
450
+ try {
451
+ pathname = decodeURIComponent(url.split(/[?#]/)[0])
452
+ }
453
+ catch {
454
+ return undefined
455
+ }
456
+ const prefix = base.endsWith('/') ? base : `${base}/`
457
+ return pathname.startsWith(prefix) ? pathname.slice(prefix.length) : undefined
458
+ }
459
+
460
+ export function getLlmsContentType(path: string): string {
461
+ return path.endsWith('.md') ? 'text/markdown; charset=utf-8' : 'text/plain; charset=utf-8'
462
+ }
463
+
464
+ /**
465
+ * Serves a generated file for a request URL (dev server). Returns `undefined` when no file matches.
466
+ */
467
+ export function resolveLlmsRequest(
468
+ url: string | undefined,
469
+ base: string,
470
+ files: MarkdownFile[],
471
+ ): { body: string, contentType: string } | undefined {
472
+ const path = getLlmsRequestPath(url, base)
473
+ const file = path === undefined ? undefined : files.find(file => file.path === path)
474
+ return file ? { body: file.content, contentType: getLlmsContentType(file.path) } : undefined
475
+ }
@@ -0,0 +1,104 @@
1
+ const RE_NEWLINES = /\r?\n/g
2
+ const RE_PIPE = /\|/g
3
+ const RE_BACKTICK_RUNS = /`+/g
4
+ const RE_UNSAFE_FILE_CHARS = /[^\p{L}\p{N}_.-]+/gu
5
+ const RE_REPEATED_DASHES = /-{2,}/g
6
+ const RE_EDGE_DASHES_DOTS = /^[-.]+|[-.]+$/g
7
+ const RE_ENDS_WITH_PUNCTUATION = /[.!?:;]$/
8
+ const RE_LINK_LABEL_SPECIAL = /[\\[\]]/g
9
+
10
+ /**
11
+ * Escapes a link label (`[label](url)`): backslashes and brackets would end or break it.
12
+ */
13
+ export function escapeLinkLabel(label: unknown): string {
14
+ return String(label).replace(RE_LINK_LABEL_SPECIAL, '\\$&')
15
+ }
16
+
17
+ export function heading(level: number, text: string): string {
18
+ return `${'#'.repeat(Math.min(Math.max(level, 1), 6))} ${text}`
19
+ }
20
+
21
+ /**
22
+ * Inline code span that survives backticks in its content.
23
+ */
24
+ export function inlineCode(value: unknown): string {
25
+ const text = String(value)
26
+ const longestRun = Math.max(0, ...(text.match(RE_BACKTICK_RUNS) ?? []).map(run => run.length))
27
+ const ticks = '`'.repeat(longestRun + 1)
28
+ const padding = text.startsWith('`') || text.endsWith('`') ? ' ' : ''
29
+ return `${ticks}${padding}${text}${padding}${ticks}`
30
+ }
31
+
32
+ /**
33
+ * Fenced code block whose fence is longer than any backtick run in the code.
34
+ */
35
+ export function codeBlock(code: string, lang = ''): string {
36
+ const longestRun = Math.max(0, ...(code.match(RE_BACKTICK_RUNS) ?? []).map(run => run.length))
37
+ const fence = '`'.repeat(Math.max(3, longestRun + 1))
38
+ return `${fence}${lang}\n${code.replace(/\n+$/, '')}\n${fence}`
39
+ }
40
+
41
+ /**
42
+ * Escapes a value for a GFM table cell: pipes and newlines would break the row.
43
+ */
44
+ export function tableCell(value: unknown): string {
45
+ if (value === undefined || value === null) {
46
+ return ''
47
+ }
48
+ return String(value).trim().replace(RE_PIPE, '\\|').replace(RE_NEWLINES, '<br>')
49
+ }
50
+
51
+ export function table(headers: string[], rows: unknown[][]): string {
52
+ return [
53
+ `| ${headers.map(tableCell).join(' | ')} |`,
54
+ `| ${headers.map(() => '---').join(' | ')} |`,
55
+ ...rows.map(row => `| ${row.map(tableCell).join(' | ')} |`),
56
+ ].join('\n')
57
+ }
58
+
59
+ /**
60
+ * Indents every line after the first, so multi-line text stays inside a list item.
61
+ */
62
+ export function indentContinuation(text: string, indent: string): string {
63
+ return text.trim()
64
+ .split(RE_NEWLINES)
65
+ .map((line, index) => index === 0 || !line.trim() ? line.trimEnd() : `${indent}${line}`)
66
+ .join('\n')
67
+ }
68
+
69
+ /**
70
+ * Appends attribute sentences (e.g. `Default: x.`) to a description, keeping
71
+ * multi-paragraph descriptions intact.
72
+ */
73
+ export function withAttributes(description: string | undefined | null, attributes: Array<string | false | undefined>): string {
74
+ const text = description?.trim() ?? ''
75
+ const attrs = attributes.filter(Boolean).join(' ')
76
+ if (!text || !attrs) {
77
+ return text || attrs
78
+ }
79
+ if (text.includes('\n')) {
80
+ return `${text}\n\n${attrs}`
81
+ }
82
+ return `${RE_ENDS_WITH_PUNCTUATION.test(text) ? text : `${text}.`} ${attrs}`
83
+ }
84
+
85
+ /**
86
+ * Turns an identifier (e.g. an operationId with slashes or spaces) into a safe file name.
87
+ */
88
+ export function sanitizeFileName(value: string, fallback = 'operation'): string {
89
+ const sanitized = value
90
+ .replace(RE_UNSAFE_FILE_CHARS, '-')
91
+ .replace(RE_REPEATED_DASHES, '-')
92
+ .replace(RE_EDGE_DASHES_DOTS, '')
93
+ return sanitized || fallback
94
+ }
95
+
96
+ /**
97
+ * YAML frontmatter block. Strings are JSON-encoded, which is valid YAML.
98
+ */
99
+ export function frontmatter(data: Record<string, unknown>): string {
100
+ const lines = Object.entries(data)
101
+ .filter(([, value]) => value !== undefined && value !== '')
102
+ .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
103
+ return ['---', ...lines, '---'].join('\n')
104
+ }