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.
- package/dist/{OAJSONEditor-BfaXXObm.js → OAJSONEditor-6uG2SFZK.js} +6 -6
- package/dist/{OAJSONEditor-fTqoBDiY.cjs → OAJSONEditor-D-Yhb6db.cjs} +4 -4
- package/dist/{angular-html-Dl5L_ndT.js → angular-html-BUsdri4u.js} +2 -2
- package/dist/angular-html-BzD9NQW5.cjs +1 -0
- package/dist/{angular-ts-ByuE09su.cjs → angular-ts-D1fX05LE.cjs} +1 -1
- package/dist/{angular-ts-DATG01QH.js → angular-ts-DLzsnsUB.js} +2 -2
- package/dist/{apl-REpE4EOr.cjs → apl-Bo4qJ495.cjs} +1 -1
- package/dist/{apl-B903Y1iI.js → apl-D9bD1gNv.js} +5 -5
- package/dist/{astro-B6XJ1XzP.js → astro-D8q6Gy7P.js} +5 -5
- package/dist/{astro-wd_9JORh.cjs → astro-DCjm-pbh.cjs} +1 -1
- package/dist/{blade-CJNVUHnO.cjs → blade-B6fombNo.cjs} +1 -1
- package/dist/{blade-DU7K6RH3.js → blade-Sc601tfi.js} +7 -7
- package/dist/{c-BFcbaMUO.js → c-CfqZXQ2T.js} +1 -1
- package/dist/c-Dn__oIvS.cjs +1 -0
- package/dist/{chapel-BDpe9hj3.cjs → chapel-D7VyqyYt.cjs} +1 -1
- package/dist/{chapel-CyR2VtwX.js → chapel-xSzmwfXQ.js} +1 -1
- package/dist/{cobol-CDgLba1H.cjs → cobol-CAKxSKZT.cjs} +1 -1
- package/dist/{cobol-ZUVB5fnm.js → cobol-CHAgZDLS.js} +2 -2
- package/dist/{coffee-D9j_lkLc.js → coffee-CeAuLo4O.js} +1 -1
- package/dist/{coffee-BxVt1U7S.cjs → coffee-JnCJAydr.cjs} +1 -1
- package/dist/{core-DCROFLpl.cjs → core-CNg5cW98.cjs} +3 -3
- package/dist/{core-ZiHa6_mm.js → core-s1UIPu_z.js} +114 -114
- package/dist/cpp-1aC9AELp.cjs +1 -0
- package/dist/{cpp-NN3vBjLe.js → cpp-DAEET6ev.js} +3 -3
- package/dist/{crystal-Cg-JMHNA.cjs → crystal-BfArRaXr.cjs} +1 -1
- package/dist/{crystal-BCSv9BMD.js → crystal-C1qz7UnE.js} +6 -6
- package/dist/css-BVuZPxTF.cjs +1 -0
- package/dist/{css-BDew7Z2b.js → css-BZAFXxqD.js} +1 -1
- package/dist/{dist-Dsa_0AoM.cjs → dist-CpZb0vTN.cjs} +5 -5
- package/dist/{dist-CN9hkg4t.js → dist-DV8PoRsD.js} +1 -1
- package/dist/{edge-DXKIJOV7.js → edge-CWZ5MU2M.js} +3 -3
- package/dist/{edge-CMIfIdja.cjs → edge-JzsrLjb_.cjs} +1 -1
- package/dist/{elixir-BjNct3TS.js → elixir-Crtqxz1W.js} +1 -1
- package/dist/{elixir-BmJsBojU.cjs → elixir-QzvqYFsV.cjs} +1 -1
- package/dist/{elm-CPQSACRc.js → elm-9rlZJ0du.js} +1 -1
- package/dist/{elm-rLsOgMwT.cjs → elm-DTTDc-PO.cjs} +1 -1
- package/dist/{engine-javascript-CtAw-nzg.js → engine-javascript-CoT6aZfI.js} +2 -2
- package/dist/{engine-javascript-B9hqc1Sn.cjs → engine-javascript-DWPOYZRs.cjs} +2 -2
- package/dist/{erb-CQUldNHj.js → erb-C6UwauYe.js} +2 -2
- package/dist/{erb-CiTsuMX9.cjs → erb-DPWXQYaP.cjs} +1 -1
- package/dist/generate-BAgVJTNQ.js +103 -0
- package/dist/generate-BVoluROJ.cjs +1 -0
- package/dist/generateMarkdown-BYnrcWs0.js +692 -0
- package/dist/generateMarkdown-DyJdABwj.cjs +31 -0
- package/dist/{git-rebase-CjFDc1kk.cjs → git-rebase-Cwp0uWvv.cjs} +1 -1
- package/dist/{git-rebase-5OapP1hA.js → git-rebase-xIgRvJ_q.js} +1 -1
- package/dist/{glimmer-js-DJj4duzR.js → glimmer-js-CNGdvMhA.js} +4 -4
- package/dist/{glimmer-js-CPs3ZMWA.cjs → glimmer-js-Df_yNNoE.cjs} +1 -1
- package/dist/{glimmer-ts-drtM04VL.js → glimmer-ts-Dq4P7Mkf.js} +4 -4
- package/dist/{glimmer-ts-CuERAYsk.cjs → glimmer-ts-DsAOmOGY.cjs} +1 -1
- package/dist/glsl-CjiF-xkH.cjs +1 -0
- package/dist/{glsl-DPV3oxNS.js → glsl-DZfvb15l.js} +2 -2
- package/dist/{graphql-b3MqwVzn.js → graphql-CZmb-US9.js} +5 -5
- package/dist/graphql-r7AX53Pp.cjs +1 -0
- package/dist/{hack-Dnr29SMc.cjs → hack-Cs2ncrxq.cjs} +1 -1
- package/dist/{hack-BV8Fk8S0.js → hack-DIIRgI4h.js} +2 -2
- package/dist/haml-3bvHwbYf.cjs +1 -0
- package/dist/{haml-DYADyojV.js → haml-aboBnjLl.js} +3 -3
- package/dist/{handlebars-XYDCrTNM.cjs → handlebars-C7PZ80pQ.cjs} +1 -1
- package/dist/{handlebars-D7Wg8zxD.js → handlebars-Z3oHMxHt.js} +4 -4
- package/dist/html-CtaiB3Oi.cjs +1 -0
- package/dist/{html-oFWSlHLM.js → html-Cz0Xqdyq.js} +3 -3
- package/dist/{html-derivative-B_93GY2L.cjs → html-derivative-BYOQo3PG.cjs} +1 -1
- package/dist/{html-derivative-7yg_dBt4.js → html-derivative-BjrHnqif.js} +1 -1
- package/dist/{http-BpWcfGzO.cjs → http-BA9nOlAq.cjs} +1 -1
- package/dist/{http-C-Hd6Lz4.js → http-ieHS9PeS.js} +4 -4
- package/dist/{hurl-D53hSFo7.cjs → hurl-DFGEnvSS.cjs} +1 -1
- package/dist/{hurl-DjXOdham.js → hurl-Dg9NkXrC.js} +2 -2
- package/dist/{java-CcAzK28d.js → java-DCXCvNHA.js} +1 -1
- package/dist/java-DTzZZzv7.cjs +1 -0
- package/dist/javascript-DOKgRqe8.cjs +1 -0
- package/dist/{javascript-CFpHKvG0.js → javascript-f9cb-Pl7.js} +1 -1
- package/dist/{jinja-BzmRQBYE.js → jinja-B2DAjJOY.js} +1 -1
- package/dist/{jinja-DhuEKxK7.cjs → jinja-DE8g1bjX.cjs} +1 -1
- package/dist/{jison-CfNmROg3.js → jison-5BvvygJS.js} +1 -1
- package/dist/{jison-DkP6w3Kb.cjs → jison-BCQciWJO.cjs} +1 -1
- package/dist/js-yaml-B-Up3zwX.cjs +28 -0
- package/dist/{js-yaml-xxJ42vHJ.js → js-yaml-o4oD1Gp3.js} +1 -1
- package/dist/json-BcxNDt_H.cjs +1 -0
- package/dist/{json-BUhydBtV.js → json-DZfYi9f2.js} +1 -1
- package/dist/{jsx-BgXsA-DL.js → jsx-D0ksVAAA.js} +1 -1
- package/dist/jsx-DxOBIFYM.cjs +1 -0
- package/dist/{julia-CFY_QNYf.cjs → julia-B3y7weJz.cjs} +1 -1
- package/dist/{julia-QFUzXXyx.js → julia-Dk4vCuW5.js} +4 -4
- package/dist/{just-unRxJYdl.cjs → just-B7ftAo6t.cjs} +1 -1
- package/dist/{just-BQQqo7uc.js → just-BDbjiXnk.js} +5 -5
- package/dist/{latex-61rhD9l1.js → latex-CC_8gzv9.js} +1 -1
- package/dist/{latex-CMXzYJ7A.cjs → latex-QeOQCy8M.cjs} +1 -1
- package/dist/{liquid-Dlc1A5fD.cjs → liquid-BVZIda1i.cjs} +1 -1
- package/dist/{liquid-DJCM2ZDj.js → liquid-CJVpPXmh.js} +4 -4
- package/dist/llms-DWks2vGp.cjs +26 -0
- package/dist/llms-yFQ0insM.js +418 -0
- package/dist/lua-BoAqNcbB.cjs +1 -0
- package/dist/{lua-CQxTc8eB.js → lua-Bwwgpolt.js} +2 -2
- package/dist/{marko-lDIEsg9U.cjs → marko-CX9I4GhY.cjs} +1 -1
- package/dist/{marko-Dd0qsahM.js → marko-z-UpeqN9.js} +3 -3
- package/dist/{mdc-_80um6kj.js → mdc-ANp6h8jQ.js} +2 -2
- package/dist/{mdc-CyWtd_UH.cjs → mdc-BPd7ZDIZ.cjs} +1 -1
- package/dist/{nginx-DDrDrYzT.js → nginx-BUK9HsFk.js} +1 -1
- package/dist/{nginx-Bys-Mt_F.cjs → nginx-CLECRmW5.cjs} +1 -1
- package/dist/{nim-B-WnW_TA.cjs → nim-4G662efB.cjs} +1 -1
- package/dist/{nim-BKM9BEwv.js → nim-pupbS7ww.js} +6 -6
- package/dist/{useOpenapi-Dr3AneGd.js → normalizeExamples-BFR42ENV.js} +4055 -2184
- package/dist/normalizeExamples-DNaOGXm0.cjs +45 -0
- package/dist/{org-DFPWKQMZ.js → org-B8vjAQ9v.js} +26 -26
- package/dist/{org-BQi9zqMo.cjs → org-XYh7PPQk.cjs} +1 -1
- package/dist/{perl-BIiCtWTQ.js → perl-ChiZYWB8.js} +5 -5
- package/dist/{perl-CkLK5ExR.cjs → perl-Qi4toP6W.cjs} +1 -1
- package/dist/{php-CgjckyHQ.cjs → php-93axekrF.cjs} +1 -1
- package/dist/{php-DOw5HPZo.js → php-JTDYSOFN.js} +6 -6
- package/dist/{pug-ZRJG_B3i.cjs → pug-BHWWe-s7.cjs} +1 -1
- package/dist/{pug-BGkLdaFt.js → pug-BR1NlFnA.js} +3 -3
- package/dist/{qml-BHFWpY8E.cjs → qml-71TJR8lk.cjs} +1 -1
- package/dist/{qml-Bpj0emxI.js → qml-BBCxB4Da.js} +1 -1
- package/dist/r-BVapaf2o.cjs +1 -0
- package/dist/{r-beK_-64Q.js → r-u-VAz7bR.js} +1 -1
- package/dist/{razor-Q3MoMGDn.js → razor-Cqi5RzG6.js} +1 -1
- package/dist/{razor-COBqjWAJ.cjs → razor-DMdT60zm.cjs} +1 -1
- package/dist/{regexp-BsdKen3m.js → regexp-9Pkh3Nf7.js} +1 -1
- package/dist/regexp-CwHm4hi_.cjs +1 -0
- package/dist/{rst-B0t1spY-.cjs → rst-BtwmHjj9.cjs} +1 -1
- package/dist/{rst-DpM5_nag.js → rst-CLZRH5oU.js} +6 -6
- package/dist/{ruby-kbh8ViY5.js → ruby-BZUQEFGQ.js} +12 -12
- package/dist/{ruby-CsFQlb64.cjs → ruby-DuGe7Fs0.cjs} +1 -1
- package/dist/{sas-CnYUys8b.cjs → sas-B7hIWqYI.cjs} +1 -1
- package/dist/{sas-BgQhrf78.js → sas-BO2zDPuE.js} +1 -1
- package/dist/scss-BpK0m8eZ.cjs +1 -0
- package/dist/{scss-NPDrxHVt.js → scss-OFCrSwaR.js} +2 -2
- package/dist/{shellscript-DhwNgJpI.js → shellscript-BNTFxSmg.js} +1 -1
- package/dist/shellscript-KJDkFDLp.cjs +1 -0
- package/dist/{shellsession-BzIHueWc.js → shellsession-B5j5FuGA.js} +1 -1
- package/dist/{shellsession-D7Pf_B_j.cjs → shellsession-DWalcvtJ.cjs} +1 -1
- package/dist/{soy-Bacl__9y.cjs → soy-BQn3ItqC.cjs} +1 -1
- package/dist/{soy-xHdJtla5.js → soy-C2Q794LP.js} +1 -1
- package/dist/{sql-AGUE5-dk.js → sql-8JHRpHTE.js} +1 -1
- package/dist/sql-C5y5nUuw.cjs +1 -0
- package/dist/{stata-BpsgLaw1.js → stata-BrNyU7bS.js} +1 -1
- package/dist/{stata-ByZ8yj3l.cjs → stata-DyBO95gA.cjs} +1 -1
- package/dist/{surrealql-Dfwdqk76.cjs → surrealql-CAAIvFqO.cjs} +1 -1
- package/dist/{surrealql-CE6SK0JG.js → surrealql-DgN6gei3.js} +1 -1
- package/dist/{svelte-DRtnTFsc.cjs → svelte-DGjw_UH1.cjs} +1 -1
- package/dist/{svelte-B8Y6hosE.js → svelte-FhQBX-tv.js} +3 -3
- package/dist/{templ-BofvAMnQ.js → templ-BUggPx5p.js} +2 -2
- package/dist/{templ-BIgW0e2S.cjs → templ-Cxuj5rzV.cjs} +1 -1
- package/dist/tex-B3aY5DbH.cjs +1 -0
- package/dist/{tex-CLtxJoaQ.js → tex-BlOdu2Xy.js} +2 -2
- package/dist/{ts-tags-Cv2SdymF.cjs → ts-tags-BymwG1F9.cjs} +1 -1
- package/dist/{ts-tags-DRRvATIb.js → ts-tags-DZBZzNkR.js} +7 -7
- package/dist/tsx-DgA8B92F.cjs +1 -0
- package/dist/{tsx--6NZUZt2.js → tsx-mByJmMSt.js} +1 -1
- package/dist/{twig-BTg98s4P.js → twig--2v8RtVi.js} +5 -5
- package/dist/{twig-C8K9fEv7.cjs → twig-CWwcCfHy.cjs} +1 -1
- package/dist/types/src/cli.d.ts +1 -0
- package/dist/types/src/components/Common/Highlight/OAShiki.vue.d.ts +2 -2
- package/dist/types/src/components/Common/Highlight/OAVueJsonPretty.vue.d.ts +2 -2
- package/dist/types/src/components/Common/OACodeBlock.vue.d.ts +2 -2
- package/dist/types/src/components/Common/OACodeValue.vue.d.ts +2 -2
- package/dist/types/src/components/Common/OAJSONEditor.vue.d.ts +2 -2
- package/dist/types/src/components/Parameter/OAParameterAttribute.vue.d.ts +2 -2
- package/dist/types/src/components/Playground/OAPlaygroundParameterInput.vue.d.ts +2 -2
- package/dist/types/src/components/ui/badge/index.d.ts +1 -1
- package/dist/types/src/components/ui/button/index.d.ts +1 -1
- package/dist/types/src/index.d.ts +18 -3
- package/dist/types/src/lib/codeSamples/buildOperationRequest.d.ts +15 -0
- package/dist/types/src/lib/codeSamples/buildRequest.d.ts +6 -0
- package/dist/types/src/lib/constants.d.ts +3 -0
- package/dist/types/src/lib/markdown/generateMarkdown.d.ts +111 -0
- package/dist/types/src/lib/markdown/llmsSite.d.ts +137 -0
- package/dist/types/src/lib/markdown/markdownUtils.d.ts +35 -0
- package/dist/types/src/lib/markdown/operationToMarkdown.d.ts +66 -0
- package/dist/types/src/lib/parser/getSchemaUi.d.ts +1 -0
- package/dist/types/src/node/cli.d.ts +5 -0
- package/dist/types/src/node/generate.d.ts +38 -0
- package/dist/types/src/node/llms.d.ts +99 -0
- package/dist/types/src/node/llmsPlugin.d.ts +10 -0
- package/dist/typescript-BWfpZQ2O.cjs +1 -0
- package/dist/{typescript-DBKp3fLc.js → typescript-DF15DAwn.js} +1 -1
- package/dist/{typst-wzR7m38K.cjs → typst-BEqsnZtv.cjs} +1 -1
- package/dist/{typst-BMPcWpxF.js → typst-uhRd3eU5.js} +29 -29
- package/dist/useSidebar-B2LH297o.cjs +6 -0
- package/dist/useSidebar-CoebjdWM.js +313 -0
- package/dist/vitepress-openapi.cli.cjs.js +22 -0
- package/dist/vitepress-openapi.cli.es.js +67 -0
- package/dist/vitepress-openapi.client.cjs.js +1 -1
- package/dist/vitepress-openapi.client.es.js +7 -6
- package/dist/vitepress-openapi.node.cjs.js +1 -1
- package/dist/vitepress-openapi.node.es.js +47 -2
- package/dist/vitepress-openapi.vue.cjs.js +1 -1
- package/dist/vitepress-openapi.vue.es.js +4 -3
- package/dist/{vue-DLzq6csB.cjs → vue-BQl-5Fd6.cjs} +1 -1
- package/dist/{vue-DWAybQg2.js → vue-CSJXDMn1.js} +6 -6
- package/dist/{vue-CPzdKbEl.js → vue-DIM9jH1x.js} +2483 -4670
- package/dist/vue-DwsEa2e4.cjs +7 -0
- package/dist/{vue-html-IeY1Py_m.cjs → vue-html-AqZQgz92.cjs} +1 -1
- package/dist/{vue-html-BSam2lRJ.js → vue-html-DYm4V3uo.js} +1 -1
- package/dist/{vue-vine-icUsAH0H.js → vue-vine-BLrCVeql.js} +3 -3
- package/dist/{vue-vine-Db6Q7xvd.cjs → vue-vine-C1QCIUv6.cjs} +1 -1
- package/dist/xml-DbN80t5u.cjs +1 -0
- package/dist/{xml-Cj_af9Z1.js → xml-Df1jLF7H.js} +2 -2
- package/dist/{xsl-DblyyLAc.cjs → xsl-7fKL5NbN.cjs} +1 -1
- package/dist/{xsl-D-tBFomZ.js → xsl-C2LJLnIq.js} +1 -1
- package/dist/{yaml-D4q2Gm3x.js → yaml-DABI1u00.js} +1 -1
- package/dist/yaml-DNB0t8B9.cjs +1 -0
- package/package.json +4 -1
- package/src/cli.ts +6 -0
- package/src/composables/useSidebar.ts +1 -1
- package/src/index.ts +26 -5
- package/src/lib/codeSamples/buildHarRequest.ts +5 -0
- package/src/lib/codeSamples/buildOperationRequest.ts +52 -0
- package/src/lib/codeSamples/buildRequest.ts +49 -28
- package/src/lib/constants.ts +5 -0
- package/src/lib/examples/getSchemaUiJson.ts +1 -1
- package/src/lib/markdown/generateMarkdown.ts +451 -0
- package/src/lib/markdown/llmsSite.ts +475 -0
- package/src/lib/markdown/markdownUtils.ts +104 -0
- package/src/lib/markdown/operationToMarkdown.ts +834 -0
- package/src/lib/parser/generateCodeSamples.ts +6 -31
- package/src/lib/parser/generateMissingOperationIds.ts +1 -1
- package/src/lib/parser/generateMissingSummary.ts +1 -1
- package/src/lib/parser/generateMissingTags.ts +1 -1
- package/src/lib/parser/generateRequestBodyUi.ts +1 -1
- package/src/lib/parser/generateResponseUi.ts +1 -1
- package/src/lib/parser/generateSecurityUi.ts +1 -1
- package/src/lib/parser/getSchemaUi.ts +7 -3
- package/src/lib/sidebar/generateSidebarItemsByPaths.ts +1 -1
- package/src/lib/spec/createOpenApiSpec.ts +1 -1
- package/src/node/cli.ts +107 -0
- package/src/node/generate.ts +207 -0
- package/src/node/llms.ts +431 -0
- package/src/node/llmsPlugin.ts +29 -0
- package/dist/angular-html-Dk2XGZ_t.cjs +0 -1
- package/dist/c-DkEd8-YD.cjs +0 -1
- package/dist/cpp-BPWm4FiD.cjs +0 -1
- package/dist/css-Cca861pZ.cjs +0 -1
- package/dist/glsl-vKFvWHtP.cjs +0 -1
- package/dist/graphql-DG0SCdKc.cjs +0 -1
- package/dist/haml-cdCU_QQV.cjs +0 -1
- package/dist/html-DOohh95v.cjs +0 -1
- package/dist/java-YSQdp8jH.cjs +0 -1
- package/dist/javascript-CcZ4Z9Pe.cjs +0 -1
- package/dist/js-yaml-D7HstSVO.cjs +0 -28
- package/dist/json-BuUbxxHW.cjs +0 -1
- package/dist/jsx-LBqujUwg.cjs +0 -1
- package/dist/lua-De5jN6Ym.cjs +0 -1
- package/dist/r-CP5u50Ge.cjs +0 -1
- package/dist/regexp-Cquj00oh.cjs +0 -1
- package/dist/scss-FW7lpUTk.cjs +0 -1
- package/dist/shellscript-C1Cbf_Wu.cjs +0 -1
- package/dist/sql-BCbZO9Vk.cjs +0 -1
- package/dist/tex-UEva1VjO.cjs +0 -1
- package/dist/tsx-CRyT9Jau.cjs +0 -1
- package/dist/typescript-BbUbA8EZ.cjs +0 -1
- package/dist/useOpenapi-Bt0dpttK.cjs +0 -50
- package/dist/vue-Da82SaTm.cjs +0 -7
- package/dist/xml-An_1AySF.cjs +0 -1
- 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
|
+
}
|