@aiquants/markdown 12.3.0 → 13.0.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.
- package/README.md +276 -65
- package/dist/{abnfDiagram-VRR7QNED-B_QmXzWv.js → abnfDiagram-VRR7QNED-B3Q9attM.js} +9 -9
- package/dist/abnfDiagram-VRR7QNED-QW4YM2AY.cjs +1 -0
- package/dist/arc-BBLXr5EU.js +83 -0
- package/dist/arc-Cn8XXgbN.cjs +1 -0
- package/dist/{architectureDiagram-ZJ3FMSHR-CEb923Bc.js → architectureDiagram-ZJ3FMSHR-BaSp0hC2.js} +123 -123
- package/dist/architectureDiagram-ZJ3FMSHR-BfmjNYww.cjs +36 -0
- package/dist/{blockDiagram-677ZJIJ3-CmKMdhaS.js → blockDiagram-677ZJIJ3-DFcPQ19k.js} +166 -166
- package/dist/{blockDiagram-677ZJIJ3-D7RRzjUx.cjs → blockDiagram-677ZJIJ3-u7d3VCxA.cjs} +1 -1
- package/dist/{c4Diagram-LMCZKHZV-CG6fvZQo.js → c4Diagram-LMCZKHZV-DW0yo5tR.js} +2 -2
- package/dist/{c4Diagram-LMCZKHZV-W7Qa-ecL.cjs → c4Diagram-LMCZKHZV-nScsMUE3.cjs} +1 -1
- package/dist/{channel-TsF8sms_.js → channel-B2FBCr9X.js} +1 -1
- package/dist/channel-DlkTPSf_.cjs +1 -0
- package/dist/{chunk-2Q5K7J3B-CopwR1m3.js → chunk-2Q5K7J3B-BkE4Fsuz.js} +1 -1
- package/dist/chunk-2Q5K7J3B-evSha-HP.cjs +1 -0
- package/dist/{chunk-32BRIVSS-BnNlhc1M.js → chunk-32BRIVSS-CqpDiZD2.js} +1 -1
- package/dist/chunk-32BRIVSS-rIw6tBRO.cjs +1 -0
- package/dist/{chunk-5VM5RSS4-lKwSmIqG.cjs → chunk-5VM5RSS4-CYVpj2mc.cjs} +1 -1
- package/dist/{chunk-5VM5RSS4-O28FGAOF.js → chunk-5VM5RSS4-DAgNhPcU.js} +1 -1
- package/dist/{chunk-EX3LRPZG-CtFe4olX.cjs → chunk-EX3LRPZG-Ct2cyGh-.cjs} +1 -1
- package/dist/{chunk-EX3LRPZG-C36gZH3_.js → chunk-EX3LRPZG-QFjD28UF.js} +21 -21
- package/dist/{chunk-JWPE2WC7-DG0ebjV4.js → chunk-JWPE2WC7-Bj2m1SXZ.js} +1 -1
- package/dist/chunk-JWPE2WC7-Dgw1ILoe.cjs +1 -0
- package/dist/{chunk-MOJQB5TN-nqR_swpx.js → chunk-MOJQB5TN-B1fdnpCz.js} +122 -122
- package/dist/{chunk-MOJQB5TN-DADVbG98.cjs → chunk-MOJQB5TN-yjlPYCh4.cjs} +3 -3
- package/dist/{chunk-PUDLZKDR-BUSFO-Gx.cjs → chunk-PUDLZKDR-BlQ3qKcC.cjs} +4 -4
- package/dist/{chunk-PUDLZKDR-CD96jce3.js → chunk-PUDLZKDR-CIcw3cpm.js} +21 -21
- package/dist/chunk-RYQCIY6F-B-V6UOJy.cjs +1 -0
- package/dist/{chunk-RYQCIY6F-DJkrr1sD.js → chunk-RYQCIY6F-DyVk8fNp.js} +5 -5
- package/dist/{chunk-V7JOEXUC-BzCaDGop.cjs → chunk-V7JOEXUC-B1EgagKh.cjs} +3 -3
- package/dist/{chunk-V7JOEXUC-eBy2sAXD.js → chunk-V7JOEXUC-C776k7_V.js} +15 -15
- package/dist/{chunk-VR4S4FIN-C-qPzUSR.js → chunk-VR4S4FIN-CyqARa17.js} +5 -5
- package/dist/chunk-VR4S4FIN-Sx71KwIQ.cjs +1 -0
- package/dist/{chunk-XXDRQBXY-BK6HOWf6.js → chunk-XXDRQBXY-B-99Fbs_.js} +3 -3
- package/dist/chunk-XXDRQBXY-BgeRIUG1.cjs +1 -0
- package/dist/classDiagram-OUVF2IWQ-BLAiuPPL.cjs +1 -0
- package/dist/{classDiagram-v2-EOCWNBFH-CPDmG5kI.js → classDiagram-OUVF2IWQ-DJ0hW16Q.js} +2 -2
- package/dist/classDiagram-v2-EOCWNBFH-BLAiuPPL.cjs +1 -0
- package/dist/{classDiagram-OUVF2IWQ-CPDmG5kI.js → classDiagram-v2-EOCWNBFH-DJ0hW16Q.js} +2 -2
- package/dist/{code-blocks-BWr5Xg1I.js → code-blocks-C6J8rVTc.js} +23 -22
- package/dist/{code-blocks-BdKjppKq.cjs → code-blocks-CTESwslp.cjs} +3 -3
- package/dist/code-blocks.cjs +1 -1
- package/dist/code-blocks.d.ts +1 -0
- package/dist/code-blocks.js +15 -14
- package/dist/components/CopyButton.d.ts +1 -2
- package/dist/components/MarkdownRenderer.d.ts +31 -2
- package/dist/components/MarkdownViewer.d.ts +11 -2
- package/dist/components/MermaidDiagram.d.ts +1 -0
- package/dist/components/ReadingPlaceKeeper.d.ts +32 -0
- package/dist/components/SelectionKeeper.d.ts +38 -0
- package/dist/components/SpreadsheetBlock.d.ts +2 -1
- package/dist/components/blockKeys.d.ts +9 -2
- package/dist/components/blockOffsets.d.ts +3 -0
- package/dist/components/clipboard.d.ts +1 -0
- package/dist/components/embeds/ClientFrame.d.ts +1 -0
- package/dist/components/embeds/ProviderEmbed.d.ts +2 -1
- package/dist/components/embeds/embedLabels.d.ts +1 -1
- package/dist/components/embeds/linkCardFetch.d.ts +2 -0
- package/dist/components/embeds.d.ts +5 -0
- package/dist/components/headingLevels.d.ts +6 -0
- package/dist/components/htmlNodes.d.ts +2 -0
- package/dist/components/htmlSanitizer.d.ts +15 -2
- package/dist/components/labels.d.ts +3 -2
- package/dist/components/links.d.ts +1 -0
- package/dist/components/mdastNodes/CodeNode.d.ts +3 -1
- package/dist/components/mermaidLabels.d.ts +5 -0
- package/dist/components/mermaidSetup.d.ts +10 -0
- package/dist/components/missingImageLabels.d.ts +2 -0
- package/dist/components/ownPixels.d.ts +1 -0
- package/dist/components/rawHtml.d.ts +7 -3
- package/dist/components/spreadsheetModel.d.ts +1 -0
- package/dist/components/viewerLabels.d.ts +11 -2
- package/dist/contentColors.d.ts +21 -0
- package/dist/conversion.d.ts +7 -0
- package/dist/converter/NOTICES.md +6 -6
- package/dist/converter/createMarkdownConverter.d.ts +1 -0
- package/dist/converter/protocol.d.ts +4 -0
- package/dist/converter.cjs +1 -1
- package/dist/converter.js +89 -71
- package/dist/converter.wasm +0 -0
- package/dist/{cose-bilkent-JH36ORCC-BxO1rjEU.js → cose-bilkent-JH36ORCC-CR6Hdvto.js} +24 -24
- package/dist/cose-bilkent-JH36ORCC-reAbGeDU.cjs +1 -0
- package/dist/cynefinDiagram-TSTJHNR4-2qz-sUtp.cjs +62 -0
- package/dist/{cynefinDiagram-TSTJHNR4-DBD-B_Un.js → cynefinDiagram-TSTJHNR4-D1eY-FSf.js} +65 -65
- package/dist/dagre-VKFMJZFB-Byr9WPjb.cjs +4 -0
- package/dist/{dagre-VKFMJZFB-B8vZCPJg.js → dagre-VKFMJZFB-CXSczF8v.js} +26 -26
- package/dist/{diagram-FQU43EPY-DwhEcKWF.cjs → diagram-FQU43EPY-2YWng437.cjs} +1 -1
- package/dist/{diagram-FQU43EPY-YrRTNuX-.js → diagram-FQU43EPY-BZo0xcaj.js} +54 -54
- package/dist/diagram-G47NLZAW-CQS7BN4F.cjs +24 -0
- package/dist/{diagram-G47NLZAW-D4vmirJw.js → diagram-G47NLZAW-CvJW9ny8.js} +65 -65
- package/dist/{diagram-NH7WQ7WH-Drekwiur.js → diagram-NH7WQ7WH-C6VIkj-R.js} +18 -18
- package/dist/diagram-NH7WQ7WH-DXUwOBe7.cjs +24 -0
- package/dist/{diagram-OA4YK3LP-DZsM4Fpo.js → diagram-OA4YK3LP-Co6nMbJc.js} +29 -29
- package/dist/{diagram-OA4YK3LP-DeJ7pMIO.cjs → diagram-OA4YK3LP-DBUm2qxb.cjs} +3 -3
- package/dist/{diagram-WEI45ONY-CjRbsbkF.js → diagram-WEI45ONY-BaMbc5o2.js} +76 -76
- package/dist/diagram-WEI45ONY-ChpK2gP3.cjs +41 -0
- package/dist/ebnfDiagram-CCIWWBDH-DMIRHp8N.cjs +1 -0
- package/dist/{ebnfDiagram-CCIWWBDH-D0kt5Zdu.js → ebnfDiagram-CCIWWBDH-i7CR-FU0.js} +3 -3
- package/dist/embeds/frames.d.ts +4 -0
- package/dist/embeds/linkCards.d.ts +3 -1
- package/dist/embeds/providers.d.ts +1 -0
- package/dist/embeds/testing.cjs +1 -1
- package/dist/embeds/testing.js +1 -1
- package/dist/embeds-B4g6w7Tf.cjs +1 -0
- package/dist/embeds-Dra-dGKD.js +64 -0
- package/dist/embeds.cjs +1 -1
- package/dist/embeds.d.ts +2 -2
- package/dist/embeds.js +31 -70
- package/dist/{erDiagram-Q63AITRT-Ce4GpK2Z.js → erDiagram-Q63AITRT-DC-HhdaO.js} +69 -69
- package/dist/{erDiagram-Q63AITRT-DqFANbZx.cjs → erDiagram-Q63AITRT-DjRvJyWK.cjs} +1 -1
- package/dist/errors-BWZJx2MD.cjs +1 -0
- package/dist/errors-CapTNE7l.js +62 -0
- package/dist/errors.d.ts +2 -2
- package/dist/extractHeadings-BAhmauKo.js +5296 -0
- package/dist/extractHeadings-qiJXegCx.cjs +11 -0
- package/dist/flowDiagram-23GEKE2U-CiNzp6BS.js +7 -0
- package/dist/flowDiagram-23GEKE2U-DzZNPkRJ.cjs +1 -0
- package/dist/{ganttDiagram-NO4QXBWP-DjpANtqX.js → ganttDiagram-NO4QXBWP-BwbtaPxc.js} +69 -69
- package/dist/ganttDiagram-NO4QXBWP-CJv5UQ4O.cjs +292 -0
- package/dist/gen/markdown/v1/linkcard_connect.d.ts +19 -0
- package/dist/gen/markdown/v1/linkcard_pb.d.ts +87 -0
- package/dist/gen/markdown/v1/markdown_pb.d.ts +4 -0
- package/dist/{gitGraphDiagram-IHSO6WYX-DzhnsGXo.js → gitGraphDiagram-IHSO6WYX--yebcp4V.js} +26 -26
- package/dist/gitGraphDiagram-IHSO6WYX-dSwtW7X6.cjs +106 -0
- package/dist/index.cjs +1 -1
- package/dist/index.client.cjs +1 -1
- package/dist/index.client.d.ts +2 -2
- package/dist/index.client.js +42 -36
- package/dist/index.js +42 -36
- package/dist/index.server.cjs +1 -1
- package/dist/index.server.d.ts +2 -1
- package/dist/index.server.js +126 -873
- package/dist/{infoDiagram-FWYZ7A6U-hraoyboI.js → infoDiagram-FWYZ7A6U-B4AiTiqD.js} +9 -9
- package/dist/infoDiagram-FWYZ7A6U-BOj0VF20.cjs +2 -0
- package/dist/{ishikawaDiagram-FXEZZL3T-cBJei3wJ.js → ishikawaDiagram-FXEZZL3T-BsYs_qnQ.js} +55 -55
- package/dist/{ishikawaDiagram-FXEZZL3T-D5b25aDN.cjs → ishikawaDiagram-FXEZZL3T-CisV4kPO.cjs} +1 -1
- package/dist/{journeyDiagram-5HDEW3XC-DrNyUSsx.cjs → journeyDiagram-5HDEW3XC-BAvgWwpr.cjs} +1 -1
- package/dist/{journeyDiagram-5HDEW3XC-IkQqMl8f.js → journeyDiagram-5HDEW3XC-DbDo-dqu.js} +29 -29
- package/dist/{kanban-definition-HUTT4EX6-D2UL88Cz.js → kanban-definition-HUTT4EX6-BlPZISwH.js} +111 -111
- package/dist/{kanban-definition-HUTT4EX6-CvBgN3eX.cjs → kanban-definition-HUTT4EX6-RjzOWas9.cjs} +2 -2
- package/dist/{linear-BiJV9gYf.js → linear-BXWX8YXI.js} +33 -33
- package/dist/linear-CKPQExK8.cjs +1 -0
- package/dist/linkCardServer/linkCardCore.d.ts +10 -0
- package/dist/linkCardServer/linkCardHandler.server.d.ts +1 -6
- package/dist/linkCardServer/pageFetchPort.d.ts +19 -0
- package/dist/linkCardServer/{pageMetadata.server.d.ts → pageMetadata.d.ts} +11 -3
- package/dist/linkCards-BikpIncf.cjs +1 -0
- package/dist/linkCards-DfSLqLPF.js +50 -0
- package/dist/linkCards.cjs +1 -0
- package/dist/linkCards.d.ts +2 -0
- package/dist/linkCards.js +5 -0
- package/dist/markdownServiceClient-C47z3Ynu.cjs +1 -0
- package/dist/markdownServiceClient-uDeklhtG.js +480 -0
- package/dist/markdownServiceClient.d.ts +20 -0
- package/dist/mermaid.core-C4EClWgB.js +15595 -0
- package/dist/mermaid.core-CRP55Hm1.cjs +305 -0
- package/dist/mermaidFrame/NOTICES.md +1345 -0
- package/dist/mermaidFrame/cssCleaner.d.ts +13 -0
- package/dist/mermaidFrame/drawer.d.ts +34 -0
- package/dist/mermaidFrame/frame.d.ts +1 -0
- package/dist/mermaidFrame/frame.js +3307 -0
- package/dist/mermaidFrame/katexInert.d.ts +4 -0
- package/dist/mermaidFrame/protocol.d.ts +38 -0
- package/dist/mermaidFrame/serve.d.ts +14 -0
- package/dist/mermaidFrame/svgCleaner.d.ts +4 -0
- package/dist/{mindmap-definition-LN4V7U3C-CK67hf6V.js → mindmap-definition-LN4V7U3C-BEWpoMMG.js} +75 -75
- package/dist/{mindmap-definition-LN4V7U3C-CBrUse7P.cjs → mindmap-definition-LN4V7U3C-DnbSfqWP.cjs} +3 -3
- package/dist/pageFetchPort-2H18xcdi.cjs +1 -0
- package/dist/pageFetchPort-DVpXsKCz.js +624 -0
- package/dist/{pegDiagram-2B236MQR-CwWX4Irn.js → pegDiagram-2B236MQR-BF7gLiB-.js} +3 -3
- package/dist/pegDiagram-2B236MQR-BJysMObA.cjs +1 -0
- package/dist/{pieDiagram-ENE6RG2P-MO42pSl8.js → pieDiagram-ENE6RG2P-D_YzC3qc.js} +65 -65
- package/dist/{pieDiagram-ENE6RG2P-BKvggS7k.cjs → pieDiagram-ENE6RG2P-UMpeIUyV.cjs} +2 -2
- package/dist/{providers-BwQK7hZa.js → providers-CSvkTZsr.js} +17 -2
- package/dist/{providers-DO2t7ks4.cjs → providers-Cx0FuVQU.cjs} +1 -1
- package/dist/{quadrantDiagram-ABIIQ3AL-BHhoAvLS.cjs → quadrantDiagram-ABIIQ3AL-DANY0ipQ.cjs} +1 -1
- package/dist/{quadrantDiagram-ABIIQ3AL-CzHgLdS3.js → quadrantDiagram-ABIIQ3AL-DDm-r_6D.js} +57 -57
- package/dist/railroadDiagram-RFXS5EU6-CDUd4th1.cjs +1 -0
- package/dist/{railroadDiagram-RFXS5EU6-Bu_Fhi5x.js → railroadDiagram-RFXS5EU6-hJ6uB90G.js} +3 -3
- package/dist/remarkProcessor.server.d.ts +2 -0
- package/dist/{requirementDiagram-TGXJPOKE-CY-JYM-P.js → requirementDiagram-TGXJPOKE-BJef5Jb0.js} +29 -29
- package/dist/{requirementDiagram-TGXJPOKE-BhdvQnjG.cjs → requirementDiagram-TGXJPOKE-DaoCo7go.cjs} +1 -1
- package/dist/{sankeyDiagram-HTMAVEWB-BmHtjxlW.js → sankeyDiagram-HTMAVEWB-BZQs0bE-.js} +48 -48
- package/dist/{sankeyDiagram-HTMAVEWB-CUeYKZeQ.cjs → sankeyDiagram-HTMAVEWB-DXiv0YOu.cjs} +3 -3
- package/dist/{sequenceDiagram-DBY2YBRQ-GepntdDB.cjs → sequenceDiagram-DBY2YBRQ-CJGpsnsv.cjs} +1 -1
- package/dist/{sequenceDiagram-DBY2YBRQ-Cn2CC9BC.js → sequenceDiagram-DBY2YBRQ-D05U2w26.js} +86 -86
- package/dist/serviceClient.cjs +1 -0
- package/dist/serviceClient.d.ts +3 -0
- package/dist/serviceClient.js +9 -0
- package/dist/{sizeCapture-X5ZJPWSS-CZF99dy_.js → sizeCapture-X5ZJPWSS-DTr0Vm61.js} +1 -1
- package/dist/sizeCapture-X5ZJPWSS-DjuH1zNP.cjs +1 -0
- package/dist/{stateDiagram-2N3HPSRC-CCbBvBua.js → stateDiagram-2N3HPSRC-B8nvJKpB.js} +20 -20
- package/dist/stateDiagram-2N3HPSRC-BrB47FD-.cjs +1 -0
- package/dist/stateDiagram-v2-6OUMAXLB-CC8gOGDK.cjs +1 -0
- package/dist/{stateDiagram-v2-6OUMAXLB-_A1QESxx.js → stateDiagram-v2-6OUMAXLB-CV-JqAeP.js} +2 -2
- package/dist/styles/markdown.css +1 -1
- package/dist/styles/markdown.standalone.css +1 -1
- package/dist/{swimlanes-5IMT3BWC-B-BDM_Ae.js → swimlanes-5IMT3BWC-BPtufzUd.js} +3 -3
- package/dist/swimlanes-5IMT3BWC-WAbDPRgt.cjs +1 -0
- package/dist/{swimlanesDiagram-G3AALYLV-BysT2rWl.js → swimlanesDiagram-G3AALYLV-BQKEmJFX.js} +2 -2
- package/dist/{swimlanesDiagram-G3AALYLV-DZuQxKuB.cjs → swimlanesDiagram-G3AALYLV-BTwwtLZL.cjs} +1 -1
- package/dist/{timeline-definition-FHXFAJF6-DVzdzbl1.js → timeline-definition-FHXFAJF6-DJ6GV7Fz.js} +34 -34
- package/dist/{timeline-definition-FHXFAJF6-oFf_sUOI.cjs → timeline-definition-FHXFAJF6-qdkrah7t.cjs} +1 -1
- package/dist/vennDiagram-L72KCM5P-B5onSWPA.cjs +34 -0
- package/dist/{vennDiagram-L72KCM5P-Bm1TGZux.js → vennDiagram-L72KCM5P-DWnnndTj.js} +196 -196
- package/dist/viewer-settings.cjs +1 -1
- package/dist/viewer-settings.d.ts +8 -0
- package/dist/viewer-settings.js +11 -5
- package/dist/{wardleyDiagram-EHGQE667-BC_1RAbp.js → wardleyDiagram-EHGQE667-DFmDgQSb.js} +41 -41
- package/dist/{wardleyDiagram-EHGQE667-CqB3gLCH.cjs → wardleyDiagram-EHGQE667-DdeBbvVM.cjs} +2 -2
- package/dist/{xychartDiagram-FW5EYKEG-a1vb5UxD.cjs → xychartDiagram-FW5EYKEG-CiJQMClv.cjs} +1 -1
- package/dist/{xychartDiagram-FW5EYKEG-ClITdEhV.js → xychartDiagram-FW5EYKEG-L2Kj4cZA.js} +28 -28
- package/package.json +29 -13
- package/dist/abnfDiagram-VRR7QNED-Crz-ChMJ.cjs +0 -1
- package/dist/arc-BKGy6Me1.js +0 -83
- package/dist/arc-CYJCyviq.cjs +0 -1
- package/dist/architectureDiagram-ZJ3FMSHR-gTB8pttO.cjs +0 -36
- package/dist/channel-BKoPLS2j.cjs +0 -1
- package/dist/chunk-2Q5K7J3B-DgtYKcDs.cjs +0 -1
- package/dist/chunk-32BRIVSS-D-6GBFtx.cjs +0 -1
- package/dist/chunk-JWPE2WC7-5sd39cpa.cjs +0 -1
- package/dist/chunk-RYQCIY6F-BBTBydZd.cjs +0 -1
- package/dist/chunk-VR4S4FIN-CHKLwvYh.cjs +0 -1
- package/dist/chunk-XXDRQBXY-DttkP7wv.cjs +0 -1
- package/dist/classDiagram-OUVF2IWQ-BKruajP_.cjs +0 -1
- package/dist/classDiagram-v2-EOCWNBFH-BKruajP_.cjs +0 -1
- package/dist/cose-bilkent-JH36ORCC-Cjfa6NyL.cjs +0 -1
- package/dist/cynefinDiagram-TSTJHNR4-B3boTACW.cjs +0 -62
- package/dist/dagre-VKFMJZFB-DF3Mvuas.cjs +0 -4
- package/dist/diagram-G47NLZAW-CKIEbGLS.cjs +0 -24
- package/dist/diagram-NH7WQ7WH-D6wMwkLQ.cjs +0 -24
- package/dist/diagram-WEI45ONY-SYHw7k8b.cjs +0 -41
- package/dist/ebnfDiagram-CCIWWBDH-23bjk9FU.cjs +0 -1
- package/dist/errors-BW5JXRoX.cjs +0 -1
- package/dist/errors-Blk_XJ9C.js +0 -55
- package/dist/extractHeadings-DlQcPv5N.js +0 -20361
- package/dist/extractHeadings-wWAipplS.cjs +0 -315
- package/dist/flowDiagram-23GEKE2U-CRC9U6qD.cjs +0 -1
- package/dist/flowDiagram-23GEKE2U-CRo7TM3K.js +0 -7
- package/dist/ganttDiagram-NO4QXBWP-CR55KG5d.cjs +0 -292
- package/dist/gitGraphDiagram-IHSO6WYX-BWYUn1Bi.cjs +0 -106
- package/dist/infoDiagram-FWYZ7A6U-CsUGc58_.cjs +0 -2
- package/dist/linear-DwqXGYLc.cjs +0 -1
- package/dist/linkCardServer/addressGuard.server.d.ts +0 -25
- package/dist/linkCardServer/pageFetch.server.d.ts +0 -37
- package/dist/linkCards-1JxY8wdm.js +0 -48
- package/dist/linkCards-Bjd_vW39.cjs +0 -1
- package/dist/pegDiagram-2B236MQR-C5pLIpKI.cjs +0 -1
- package/dist/railroadDiagram-RFXS5EU6-CwGmOFD_.cjs +0 -1
- package/dist/sizeCapture-X5ZJPWSS-Cd-k8xwk.cjs +0 -1
- package/dist/stateDiagram-2N3HPSRC-D2cvrAtN.cjs +0 -1
- package/dist/stateDiagram-v2-6OUMAXLB-BaktPIVY.cjs +0 -1
- package/dist/swimlanes-5IMT3BWC-DtdLK5z3.cjs +0 -1
- package/dist/vennDiagram-L72KCM5P-Ba2FGeN1.cjs +0 -34
- /package/dist/linkCardServer/{htmlEncoding.server.d.ts → htmlEncoding.d.ts} +0 -0
- /package/dist/linkCardServer/{metadataCache.server.d.ts → metadataCache.d.ts} +0 -0
package/README.md
CHANGED
|
@@ -6,10 +6,12 @@ Advanced Markdown renderer for React with support for various extensions and cus
|
|
|
6
6
|
|
|
7
7
|
- **Rich Markdown Support**: Full support for CommonMark, GitHub Flavored Markdown (GFM), and LaTeX Math expressions.
|
|
8
8
|
- **Offloaded Parser**: CPU-heavy Markdown parsing and AST transformation are offloaded to a high-performance Go API server running `goldmark` and `ConnectRPC`.
|
|
9
|
-
- **Browser Converter**: the same Go converter, compiled to WebAssembly and run in a worker, converts in the browser
|
|
9
|
+
- **Browser Converter**: the same Go converter, compiled to WebAssembly and run in a worker, converts in the browser as the service does, without a round trip (`@aiquants/markdown/converter`).
|
|
10
10
|
- **Custom Extensions & Plugins**: GitHub alerts, Zenn-style directives (`:::message` / `:::details`), single-line display math, and pluggable subscript, superscript, mark highlights, table cell merges, and opt-in embeds: posts and videos of ten SNS and video providers as script-free cross-origin frames, and link cards from the host's metadata endpoint.
|
|
11
11
|
- **Dynamic Configuration**: Easily enable or disable custom extensions dynamically using parse options.
|
|
12
12
|
- **Syntax Highlighting**: Code blocks with Shiki syntax highlighting, every token at a 7:1 contrast ratio or better in the GitHub, Zenn and None styles, light and dark (see [Code blocks](#code-blocks)).
|
|
13
|
+
- **Text That Grows and Untrusted Text**: a text that grows renders block by block as the converter cuts it, keeping the reader's selection and a code block's place (see [Text that grows](#text-that-grows)), and a model's answer renders under its own allow list, its images and links handed to the host's components (see [Untrusted text](#untrusted-text)).
|
|
14
|
+
- **Reader's Display Options**: one toolbar popover holds the document style, a reading width and colour pairs that keep every text at 7:1 or better in every built-in style (see [Reader's display options](#readers-display-options)).
|
|
13
15
|
- **TypeScript**: Full TypeScript support with comprehensive type definitions.
|
|
14
16
|
|
|
15
17
|
## Installation
|
|
@@ -29,16 +31,16 @@ Markdown の解析は Go 製サービス (`markdown-api`) が担当します。
|
|
|
29
31
|
| --- | --- |
|
|
30
32
|
| Linux x64 / arm64 | ✅ |
|
|
31
33
|
| macOS x64 (Intel) / arm64 (Apple Silicon) | ✅ |
|
|
32
|
-
| Windows x64 / arm64 |
|
|
34
|
+
| Windows x64 / arm64 | ❌ Node.js からサービスを起こしません (Windows のホストはサービスを自らの実行ファイルの中で動かします)。`parseMarkdown` はソケットを見ることも起こすこともせずに、理由を添えて `unavailable` で断り、リンクカードの口はサービスへ届かない時と同じに 500 を答えます |
|
|
33
35
|
|
|
34
36
|
`postinstall` スクリプトは不要です (実行権限は npm の `bin` 契約で保証されます)。ライフサイクルスクリプトを禁止している環境でもそのまま動きます。
|
|
35
37
|
|
|
36
|
-
`parseMarkdown`
|
|
38
|
+
`parseMarkdown` と `createLinkCardHandler` の処理は、最初の呼び出し時にサービスが待ち受けていなければ自動起動します。起こすのはソケットで何も聞いていないと分かる時だけで、聞き手の列が満ちている時やこのプロセスの記述子が尽きた時は、動く子に触れずに呼び出しを続けます。プロセスマネージャ (supervisor / systemd など) で `markdown-api` を別プロセスとして管理している構成では、そのソケットへそのまま接続します。
|
|
37
39
|
|
|
38
40
|
<details>
|
|
39
41
|
<summary>上記以外のプラットフォームで使う</summary>
|
|
40
42
|
|
|
41
|
-
|
|
43
|
+
サービスを自分でビルドし、その場所を教えてください (Windows を除く)。
|
|
42
44
|
|
|
43
45
|
```bash
|
|
44
46
|
git clone https://github.com/fehde-k/aiquants.git
|
|
@@ -56,15 +58,23 @@ export MARKDOWN_API_BINARY=/path/to/markdown-api
|
|
|
56
58
|
|
|
57
59
|
| 変数 | 既定値 | 用途 |
|
|
58
60
|
| --- | --- | --- |
|
|
59
|
-
| `MARKDOWN_SOCKET_PATH` | (必須) | サービスと通信する UNIX ドメインソケットのパス (サービスも同じ変数を読む)。未設定か空なら `parseMarkdown`
|
|
61
|
+
| `MARKDOWN_SOCKET_PATH` | (必須) | サービスと通信する UNIX ドメインソケットのパス (サービスも同じ変数を読む)。未設定か空なら `parseMarkdown` は変数を名指して失敗し、`createLinkCardHandler` の処理は 500 で答え、サービスは起動しない (パスを推し量らない)。プロセスの間は変えない (輸送は接続を開く時に読み、開いた接続を使い続ける)。ソケットのディレクトリは持ち主だけが書けること (ソケットの上では何も認証しないので、ほかの利用者が先に道を取ると、呼び出しのトークンと文書を受け取り、答えを返せる) |
|
|
60
62
|
| `MARKDOWN_SOCKET_MODE` | `0600` | サービスのソケットの権限。`0600` (所有者のみ) か `0660` (所有者とグループ) だけで、ほかの値ではサービスが値を名指して起動しない (ソケットの上では何も認証しないため、ほかの利用者へは開かない) |
|
|
61
63
|
| `MARKDOWN_API_BINARY` | (なし) | 自前ビルドしたバイナリの明示指定 |
|
|
62
|
-
| `MARKDOWN_API_STARTUP_TIMEOUT_MS` | `10000` | 自動起動したサービスが待ち受け開始するまでの猶予 |
|
|
64
|
+
| `MARKDOWN_API_STARTUP_TIMEOUT_MS` | `10000` | 自動起動したサービスが待ち受け開始するまでの猶予 (ミリ秒。子が先に終われば待たない)。未設定か空なら既定値で、正の整数のほかの値は子を起こす時に `RangeError` で変数を名指す |
|
|
63
65
|
| `MARKDOWN_MAX_SOURCE_BYTES` | `8388608` (8 MiB) | サービスが受け付ける Markdown の本文の最大 (`@import` で取り込んだ分を含む) |
|
|
64
|
-
| `MARKDOWN_MAX_HTML_BYTES` | `33554432` (32 MiB) | サービスが作る HTML の最大 (呼び出しの `maxHtmlBytes` はこれを下げることだけができる) |
|
|
66
|
+
| `MARKDOWN_MAX_HTML_BYTES` | `33554432` (32 MiB) | サービスが作る HTML の最大 (呼び出しの `maxHtmlBytes` はこれを下げることだけができる)。応答の塊の位置 (`blockOffsets`) が uint32 に収まるよう 4294967295 以下で、超える値ではサービスが起動しない |
|
|
65
67
|
| `MARKDOWN_CONVERT_TIMEOUT` | `30s` | 変換 1 回の最長の時間 (Go の時間の書式。呼び出しの `timeoutMs` はこれを短くすることだけができる) |
|
|
68
|
+
| `MARKDOWN_CONVERSION_CAPACITY` | `1` | `MARKDOWN_SMALL_CONVERSION_MAX_BYTES` を超える文書の枠で同時に走る変換の重み (`@import` を含む本文の大きさ + 64 KiB) の合計の上限を、最大の文書の本数で表す正の整数 (既定では 500 KB の文書が 14 本)。超えた変換は来た順に待ち、待ちも変換の時間に入るので、1 本が期限まで走れば同じ枠の後ろは最長で期限まで待つ。最大の文書 1 本のメモリは文書の形で 0.24〜3.83 GiB で、2 本なら最悪 7.7 GiB |
|
|
69
|
+
| `MARKDOWN_SMALL_CONVERSION_MAX_BYTES` | `262144` (256 KiB) | 小さな文書の枠の本文の最大 (`@import` を含む。本文の上限より小さい正の整数)。枠の間で溢れないので、大きな文書がどれだけ長く走っても小さな文書は待たない |
|
|
70
|
+
| `MARKDOWN_SMALL_CONVERSION_CAPACITY` | `8` | 小さな文書の枠で同時に走る変換の重みの合計の上限を、その枠の最大の文書の本数で表す正の整数 (既定ではごく小さな文書が 40 本) |
|
|
71
|
+
| `MARKDOWN_CONVERSION_MEMORY_BYTES` | `6442450944` (6 GiB) | プロセスのヒープのバイト数がこれを超えると、最も長く走っている変換から `unavailable` で止め (上限の 4/3 で全て止まる)、超えている間は新しい変換を始めずに `unavailable` で断る。プロセス全体を数える |
|
|
66
72
|
|
|
67
|
-
後の
|
|
73
|
+
後の 4 つはサービス (`markdown-api`) が読む。自動起動したサービスは呼び出し元のプロセスの環境を受け継ぐ。正の数 (時間は正の時間) 以外の値ではサービスが起動しない。
|
|
74
|
+
|
|
75
|
+
`parseMarkdown` とリンクのカードは `@aiquants/local-service-transport` の輸送でサービスへ届く。呼び出しは HTTP/2 の接続 1 本を分け合い、止めた呼び出しの後は次の呼び出しから新しい接続へ移る。
|
|
76
|
+
|
|
77
|
+
自動起動したサービスは起こしたホストの子で、ホストと一緒に終わる。ソケットを複数のホストで分けると、先に終わるホストの子の上の呼び出しは失敗し、次の呼び出しが子を起こす (サービスは起動のときに道のソケットを生死を問わず消すため、後に起きた子が道を取る)。ソケットを分けるホストでは、サービスをプロセスマネージャで起こす。
|
|
68
78
|
|
|
69
79
|
## Usage
|
|
70
80
|
|
|
@@ -108,6 +118,7 @@ console.log("Hello, World!")
|
|
|
108
118
|
// parseResult: ParseResult
|
|
109
119
|
// htmlContent: string — レンダリング済み HTML
|
|
110
120
|
// headings: { text: string; depth: number; id: string }[] — 目次構築用の見出し一覧
|
|
121
|
+
// blockOffsets?: readonly number[] — 最上位のブロックの始まりの位置 (includeStreamingHints の時だけ)
|
|
111
122
|
return (
|
|
112
123
|
<MarkdownRenderer
|
|
113
124
|
htmlContent={parseResult.htmlContent}
|
|
@@ -137,6 +148,9 @@ const parseResult = await parseMarkdown(
|
|
|
137
148
|
resolveImports: false, // expand <!-- @import "path" --> (default false)
|
|
138
149
|
validateExistence: true, // probe local images and doc links (data-asset-exists / data-doc-exists; default true)
|
|
139
150
|
includeSourceLines: false, // annotate each block with data-source-lines="<first>-<last>" (default false)
|
|
151
|
+
includeStreamingHints: false, // answer blockOffsets and mark open code blocks with data-open-code (default false)
|
|
152
|
+
cjkFriendlyEmphasis: false, // read emphasis next to CJK punctuation (default false: CommonMark's rules)
|
|
153
|
+
hardLineBreaks: false, // render a paragraph's line breaks as <br> (default false)
|
|
140
154
|
signal: controller.signal, // cancels the conversion in the service too
|
|
141
155
|
timeoutMs: 10_000, // the conversion's deadline
|
|
142
156
|
enableSubscript: false, // Disable subscript (leaves ~2~ as plain text)
|
|
@@ -152,15 +166,21 @@ const parseResult = await parseMarkdown(
|
|
|
152
166
|
| Option | Required | Meaning |
|
|
153
167
|
| --- | --- | --- |
|
|
154
168
|
| `deniedPathSegments` | ✅ | Deny rules applied to every target the conversion resolves: `@import` targets, images and links. A pattern matches one whole path segment (`*` matches any run of characters within it), compared after NFKC normalization and case folding at every percent-decoding level (the semantics of `@aiquants/markdown-explorer`'s deny rules). Local targets must also stay inside `workspaceRoot`, also once symbolic links are resolved. A refused image renders without `src`, a refused link without a destination (with `validateExistence`, both are marked like a missing target, whether or not the target exists), and a refused import rejects the call. |
|
|
155
|
-
| `maxHtmlBytes` | ✅ | The largest HTML in bytes, a positive integer up to `MAX_HTML_BYTES_LIMIT
|
|
156
|
-
| `resolveImports` | | Expand `<!-- @import "path" -->` directives (default `false`: a directive stays an HTML comment and nothing is read). Only Markdown (`.md`) targets the deny rules admit are read, nested imports included; a refused target rejects the call with `permission_denied`. |
|
|
169
|
+
| `maxHtmlBytes` | ✅ | The largest HTML in bytes, a positive integer up to `MAX_HTML_BYTES_LIMIT`; with `includeStreamingHints`, the HTML and its block offsets together, 5 bytes an offset. The service stops while it renders and the call rejects with `MarkdownResourceExhaustedError`, as it does for an answer with a longer HTML. |
|
|
170
|
+
| `resolveImports` | | Expand `<!-- @import "path" -->` directives (default `false`: a directive stays an HTML comment and nothing is read). Only Markdown (`.md`) targets the deny rules admit are read, nested imports included; a refused target rejects the call with `permission_denied`. Imports nest at most 100 deep, one inside the next; a deeper chain rejects with `MarkdownResourceExhaustedError` before the import past the limit is read. |
|
|
157
171
|
| `validateExistence` | | Probe local targets (default `true`): a local storage image also gets `data-asset-exists` (`"true"` or `"false"`) and a local doc link `data-doc-exists` (`"true"` or `"false"`). Cloud targets are never probed, and `data-asset-src` is written for every admitted storage image either way. |
|
|
158
172
|
| `includeSourceLines` | | Annotate every rendered block with `data-source-lines="<first>-<last>"`, the 1-based lines of `markdownText` it came from, both inclusive (default `false`; see "Source lines" below). |
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
173
|
+
| `includeStreamingHints` | | Answer what a host needs to render a text that grows (default `false`; see [Text that grows](#text-that-grows)): the result's `blockOffsets`, the UTF-16 offsets at which the top-level blocks of `htmlContent` start (a block is one child of the HTML body other than ASCII white space alone, with the white space after it; the first block also holds the white space before it, so the offsets start at 0 and increase, and an empty HTML has none), and `data-open-code=""` on the `pre` of every code block that runs to the end of `markdownText`: a fenced or indented code block that no later block follows and whose last line (the opening line of a fenced block without lines) has nothing after it but white space and `>`. Either way a `data-open-code` the author wrote is removed, so the attribute is always the converter's own, and with it the HTML is the HTML without it plus the attribute alone. |
|
|
174
|
+
| `cjkFriendlyEmphasis` | | Read the delimiters of emphasis and strikethrough by the CJK-friendly amendments of markdown-cjk-friendly, so emphasis opens and closes next to CJK punctuation: `これは**「重要」**です。` is strong emphasis, where CommonMark leaves the asterisks as text (default `false`: CommonMark's rules). |
|
|
175
|
+
| `hardLineBreaks` | | Render a `<br>` before every line break inside a paragraph (a soft line break) (default `false`: the line feed alone, which a browser shows as a space between CJK characters or not at all). |
|
|
176
|
+
| `signal` | | Cancels the call, a wait for the service to start included; the service stops converting. |
|
|
177
|
+
| `timeoutMs` | | The conversion's deadline in milliseconds (a positive integer up to 2147483647), counted from the call, a wait for the service to start included; the service stops at it or at `MARKDOWN_CONVERT_TIMEOUT`, whichever comes first. Without it the call has no deadline on this side and rests on the service's limit. |
|
|
161
178
|
| `enable*` | | Switch the syntax extensions and HTML plugins (each enabled unless `false`). The text plugins leave `summary` text (a `:::details` title included) as written. |
|
|
162
179
|
|
|
163
|
-
Invalid options throw `TypeError` / `RangeError` before any request. A conversion stopped at a size limit (the HTML limit, the service's source limit or a message limit) rejects with `MarkdownResourceExhaustedError` (its `cause` is the connect error); every other failure rejects with
|
|
180
|
+
Invalid options throw `TypeError` / `RangeError` before any request. A conversion stopped at a size limit (the HTML limit, the service's source limit or a message limit) rejects with `MarkdownResourceExhaustedError` (its `cause` is the connect error); every other failure rejects with a `ConnectError`: the service's own (`invalid_argument`, `permission_denied`, `deadline_exceeded`, `internal`), or `unavailable` when the service stays out of reach or goes away during the call, with the transport's failure as `cause` when there is one.
|
|
181
|
+
A document also rejects with `MarkdownResourceExhaustedError` when it would make the converter copy more than its own bytes plus 64 KiB of any one of three things: the empty cells its tables add, the bytes its link references copy, or the elements and attributes of the formatting elements its raw HTML leaves open, which the parser reopens as a browser does.
|
|
182
|
+
A connection that could not be opened names the socket and the errno. The service also answers `unavailable` when it is too busy for the call: more conversions wait than it lets wait, or it stopped the call, or did not start it, to keep its memory within its limit. That answer tells the load, not the document, so call again later and do not remember it for the document.
|
|
183
|
+
A call `signal` stopped rejects with `canceled`, whatever the signal's reason. A call that stops or reaches its deadline while the service starts leaves that start to the calls sharing it.
|
|
164
184
|
|
|
165
185
|
### Image and link targets
|
|
166
186
|
|
|
@@ -171,7 +191,7 @@ An image destination is a URL decoded once: `` names the file `a%
|
|
|
171
191
|
- **Existence**: with `validateExistence`, a local storage image also carries `data-asset-exists` (`"true"` or `"false"`); a cloud image is never probed.
|
|
172
192
|
- **Refused targets** (the deny rules, or outside `workspaceRoot`) have neither a `src` nor `data-asset-src`; with `validateExistence` they carry `data-asset-exists="false"` whether or not they exist.
|
|
173
193
|
- **Storage links** are `data-link-kind="doc"`: they keep the authored `href` (its fragment is what a host reads) and carry the document path in `data-doc-path`; a local one also gets `data-doc-exists` under `validateExistence`.
|
|
174
|
-
- `data-asset-src` and `data-
|
|
194
|
+
- The asset markers (`data-asset-src`, `data-asset-exists`) and the link markers (`data-link-kind`, `data-doc-path`, `data-doc-exists`) come only from the converter: those written in the document's raw HTML (on any element, an `a` without an `href` included) or added by an HTML plugin are removed, and one a plugin rewrote gets the converter's value back.
|
|
175
195
|
- Of an element's duplicate attributes only the first counts, as in a browser: the converter drops the rest, so the HTML carries no duplicate attribute and a repeated `src` or marker cannot make the converter and the browser read different values.
|
|
176
196
|
|
|
177
197
|
`MarkdownRenderer` shows an image without a `src` (or with `data-asset-exists="false"`) as a placeholder naming its `data-asset-src`, so HTML rendered before the host wrote the URLs shows which files are missing instead of blank space.
|
|
@@ -197,14 +217,14 @@ const lines = parseSourceLines(block?.getAttribute(SOURCE_LINES_ATTRIBUTE))
|
|
|
197
217
|
|
|
198
218
|
### Browser converter
|
|
199
219
|
|
|
200
|
-
`@aiquants/markdown/converter` runs the service's Go converter, compiled to WebAssembly, in a worker, so a browser converts a document
|
|
220
|
+
`@aiquants/markdown/converter` runs the service's Go converter, compiled to WebAssembly, in a worker, so a browser converts a document as the service does, without a round trip: with existence validation off and `@import` directives left as written, the HTML and the headings are the service's byte for byte (the package's end-to-end tests compare both on the same documents). The one exception is a local target the service refuses only after asking its file system, which the browser, with none to ask, keeps. A host serves two assets and passes their URLs, here with Vite:
|
|
201
221
|
|
|
202
222
|
```ts
|
|
203
223
|
import { createMarkdownConverter } from "@aiquants/markdown/converter"
|
|
204
224
|
import converterWorkerUrl from "@aiquants/markdown/converter/worker?worker&url"
|
|
205
225
|
import converterWasmUrl from "@aiquants/markdown/converter.wasm?url"
|
|
206
226
|
|
|
207
|
-
const converter = createMarkdownConverter({ workerUrl: converterWorkerUrl, wasmUrl: converterWasmUrl, timeoutMs: 10_000 })
|
|
227
|
+
const converter = createMarkdownConverter({ workerUrl: converterWorkerUrl, wasmUrl: converterWasmUrl, timeoutMs: 10_000, loadTimeoutMs: 30_000 })
|
|
208
228
|
const { htmlContent, headings } = await converter.convert(
|
|
209
229
|
{
|
|
210
230
|
markdownText,
|
|
@@ -217,13 +237,35 @@ const { htmlContent, headings } = await converter.convert(
|
|
|
217
237
|
```
|
|
218
238
|
|
|
219
239
|
- **Options** are `BrowserParseOptions`: `ParseOptions` without `resolveImports`, `validateExistence` (the browser has no storage), `signal` and `timeoutMs` (the call has its own). They are validated as `parseMarkdown` validates them.
|
|
220
|
-
- **Paths**: `filePath` is read as the service reads it. Give a local document's path relative to any absolute `workspaceRoot`: the converter writes workspace-relative document paths (`data-asset-src`, `data-doc-path`), the same as the service with the real root.
|
|
240
|
+
- **Paths**: `filePath` is read as the service reads it. Give a local document's path relative to any absolute `workspaceRoot`: the converter writes workspace-relative document paths (`data-asset-src`, `data-doc-path`), the same as the service with the real root. `workspaceRoot` is required for every document, a cloud URI too, and a local document must lie inside it (not at the root itself): the browser and the service refuse anything else in the same words, as `invalid_argument`. The deny rules apply as written;
|
|
241
|
+
symbolic links are not resolved, since there is no file system, so the service stays the authority when the host serves a target.
|
|
221
242
|
- **One conversion at a time**, in call order. One aborted before it starts never runs; one aborted while it runs rejects at once with the signal's reason and its answer is dropped, since a WebAssembly call cannot be interrupted. `timeoutMs` counts from the moment the converter is loaded; past it the converter stops its worker, rejects with `MarkdownConversionTimeoutError` and starts a new worker for the next conversion.
|
|
222
|
-
- **
|
|
223
|
-
- **
|
|
243
|
+
- **Loading**: `loadTimeoutMs` (optional; a positive integer a timer can hold) bounds every load of the converter: the first one, and the load of a worker that replaces one stopped past `timeoutMs` or one that failed. A load downloads and compiles the WebAssembly and starts Go, so a slow network needs a longer limit than `timeoutMs`. Past it the converter stops the worker and fails every pending and later conversion as `unavailable`, as a converter that cannot load does; without it a load waits as long as it takes. The converter reads nothing a worker it stopped sends later.
|
|
244
|
+
- **Errors**: `MarkdownResourceExhaustedError` past a size limit (the same class `./server` exports; the browser applies the service's default limits, an 8 MiB source and a 32 MiB HTML, lowered by `maxHtmlBytes`), `MarkdownConversionTimeoutError`, and `MarkdownConversionError` with `code`: `invalid_argument` for a refused request, `internal` when the converter failed on the document, `unavailable` when the converter could not load or was disposed (every later call fails the same way; create a new converter to retry) or no provider serves the document's scheme. `dispose()` stops the worker.
|
|
245
|
+
- **Assets**: `converter.wasm` is about 6.8 MiB (gzip 1.8 MiB, brotli 1.5 MiB); serve it as `application/wasm`, so it compiles while it downloads, and compressed. The first conversion starts the worker, compiles the module and starts Go (about 0.4 s in Chromium); a 700-line document then converts in about 35 ms, the worker's round trip included. The worker is one self-contained script that starts with the `wasm_exec.js` of the Go toolchain that built the module, under its BSD license; `dist/converter/NOTICES.md` lists the licenses of everything linked into the module.
|
|
224
246
|
- **Content Security Policy**: a page that sets `script-src` needs `'wasm-unsafe-eval'` in it, and `worker-src 'self'` (or a `script-src` that covers the worker) for the same-origin worker.
|
|
225
247
|
- **Building from source** needs the Go toolchain on PATH: `pnpm run build` compiles `cmd/markdown-wasm` of `packages/go/markdown-api` and bundles the worker with the same toolchain's `wasm_exec.js` (`pnpm run build:converter` alone).
|
|
226
248
|
|
|
249
|
+
### Service client
|
|
250
|
+
|
|
251
|
+
`@aiquants/markdown/service-client` sends the same conversion as `parseMarkdown` through a connect transport the host brings, for a page that reaches the service over a process of its own. It loads no Node built-in and no Node transport. The transport must speak the binary format, which the service's size budget assumes (`createConnectTransport` of `@connectrpc/connect-web` with `useBinaryFormat: true`, for example):
|
|
252
|
+
|
|
253
|
+
```ts
|
|
254
|
+
import { createMarkdownServiceClient } from "@aiquants/markdown/service-client"
|
|
255
|
+
|
|
256
|
+
const service = createMarkdownServiceClient({ transport })
|
|
257
|
+
const { htmlContent, headings } = await service.convert(
|
|
258
|
+
{ markdownText, filePath: "notes/my-file.md", workspaceRoot: "/workspace", userOAuthToken: undefined },
|
|
259
|
+
{ deniedPathSegments: hostDenyRules, maxHtmlBytes: 4 * 1024 * 1024, timeoutMs: 10_000, signal: controller.signal },
|
|
260
|
+
)
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
- **Options** are `ParseOptions`, checked before anything is sent.
|
|
264
|
+
- **Transport**: in Node, use `createLocalServiceTransport` of `@aiquants/local-service-transport`, as `parseMarkdown` does. A fast run of stopped calls loses a plain shared HTTP/2 connection, and every later call fails or hangs until the process restarts; this transport moves the next calls to a new connection.
|
|
265
|
+
- **Storage**: every call names `X-Storage-Auth-Mode: oauth2`; a token that is no RFC 6750 bearer token is refused with a `TypeError` that does not repeat it; and `userOAuthToken` (`undefined` when the reader holds none) rides as the bearer token: the service reads the cloud only with the reader's own credentials.
|
|
266
|
+
- **Errors** are the browser converter's classes, with the transport's failure as `cause` when there is one: `MarkdownResourceExhaustedError` past a size limit, an answer longer than `maxHtmlBytes` included; `MarkdownConversionTimeoutError` past a deadline, whose `timeoutMs` is the limit the call set, or `null` when the call set none and the service stopped at its own; and `MarkdownConversionError` with `code`: `unavailable` when the service cannot be reached, goes away during the call or has no provider for the document's scheme, `invalid_argument` for a refused request, `internal`.
|
|
267
|
+
A call `signal` stopped rejects with a `ConnectError` of code `canceled`, whatever the signal's reason. Any other code (`unauthenticated`, `permission_denied`) stays the `ConnectError` it is.
|
|
268
|
+
|
|
227
269
|
## Viewer, embeds and links
|
|
228
270
|
|
|
229
271
|
`MarkdownRenderer` keys every top-level block by its content, from the keys of the last committed render: a fingerprint of the block's HTML without `data-source-lines` (a ```` ```spreadsheets ```` block's fingerprint also leaves its table's text out), and the content itself. A block takes the earliest unclaimed key of the same fingerprint and content, then the earliest unclaimed key of its fingerprint (a table whose cells changed), else a new key.
|
|
@@ -242,13 +284,15 @@ When the document around a block changes (a paragraph added above, the lines it
|
|
|
242
284
|
|
|
243
285
|
The document stylesheets size their text in `rem`, so the document follows text-only zoom (the browser's default font size, the root `font-size`) together with the viewer's controls; at the default 16 px root they look exactly as GitHub's and Zenn's own stylesheets.
|
|
244
286
|
|
|
287
|
+
Both sheets of the components also carry the reader's colour pairs and the captions' line height, outside every cascade layer (see [Reader's display options](#readers-display-options)); a host adds nothing for them.
|
|
288
|
+
|
|
245
289
|
#### Host setup
|
|
246
290
|
|
|
247
291
|
- **A Tailwind v4 host** imports `markdown.css` in its Tailwind entry, tells Tailwind to scan the package's build output for the utilities the components use, and declares the `dark` variant those utilities follow. The path of `@source` is relative to the CSS file that declares it:
|
|
248
292
|
|
|
249
293
|
```css
|
|
250
294
|
@import "tailwindcss";
|
|
251
|
-
/* No layer(): the sheet's link
|
|
295
|
+
/* No layer(): the sheet's link, link-card and colour-pair rules and the diagram's focus ring must stay outside every cascade layer */
|
|
252
296
|
@import "@aiquants/markdown/styles/markdown.css";
|
|
253
297
|
@source "../node_modules/@aiquants/markdown/dist/**/*.js";
|
|
254
298
|
/* The components' dark: utilities follow this build's dark variant; this one is the standalone sheet's */
|
|
@@ -269,26 +313,63 @@ The document stylesheets size their text in `rem`, so the document follows text-
|
|
|
269
313
|
|
|
270
314
|
### Raw HTML
|
|
271
315
|
|
|
272
|
-
Every renderer of the package — `MarkdownRenderer` (and so `MarkdownViewer`) for the converter's HTML, and `NodesRenderer`'s raw HTML nodes and HTML containers for an mdast tree — renders raw HTML through one allow list. It runs on the tree html-react-parser builds, right where the tree is rendered, so it needs no DOM and holds the same under server rendering and in the browser; nothing is serialized and parsed again.
|
|
316
|
+
Every renderer of the package — `MarkdownRenderer` (and so `MarkdownViewer`) for the converter's HTML, and `NodesRenderer`'s raw HTML nodes and HTML containers for an mdast tree — renders raw HTML through one allow list, the document list below (`MarkdownRenderer` also takes a narrower one for untrusted text; see [Untrusted text](#untrusted-text)). It runs on the tree html-react-parser builds, right where the tree is rendered, so it needs no DOM and holds the same under server rendering and in the browser; nothing is serialized and parsed again.
|
|
273
317
|
|
|
274
318
|
- **Removed with their content**: `script`, `style`, `template`, `noscript`, `noembed`, `noframes`, `plaintext`, `xmp`, `title`, `head`, `meta`, `link`, `base`, `object`, `embed`, `applet`, `param`, `frame`, `frameset`, `select`, `datalist`, `track`, `math`, `foreignObject`, every iframe that is not an allowed embed (see [Embeds](#embeds)), and every `input` except a disabled checkbox (a task-list item).
|
|
275
319
|
- **Kept**: the elements Markdown produces and common text and structure elements (`a`, `img`, `p`, `div`, `span`, headings, lists, tables, `blockquote`, `pre`, `code`, `details`, `summary`, `aside`, `section`, `figure`, `sup`, `sub`, `mark`, `video`, `audio`, `source` …) and, for icons, an `svg` with `g` and `path` inside it (anything else inside an `svg` is removed).
|
|
276
320
|
- **Unwrapped** (the element is dropped, its children render): every other element — `form`, `button`, `textarea`, `label`, `font`, `center`, custom elements and the like — so its text survives.
|
|
277
321
|
- **Attributes**: `title`, `lang`, `dir`, `role`, `hidden`, `translate`, `aria-*`, a reduced `class`, `id` and `style`, and each element's own (`href`, `src`, `alt`, `width`, `height`, `colspan`, `rowspan`, `align`, `open`, `start` …; a link keeps `name`, the fragment target of older documents).
|
|
278
|
-
The `data-*` attributes the renderers read survive on their element only: `data-link-kind`, `data-doc-path`, `data-doc-exists`, `data-footnote-ref` and `data-footnote-backref` on links, `data-asset-src` and `data-asset-exists` on images, and `data-footnotes` on sections. A paragraph's `data-embed-url` never renders: when it is a safe URL the paragraph becomes an embed placeholder (see [Embeds](#embeds)); the 5.x `div` markers (`data-plugin-type`, `data-video-id`, `data-tweet-id`, `data-url`) are dropped.
|
|
322
|
+
The `data-*` attributes the renderers read survive on their element only: `data-link-kind`, `data-doc-path`, `data-doc-exists`, `data-footnote-ref` and `data-footnote-backref` on links, `data-asset-src` and `data-asset-exists` on images, `data-open-code` on `pre` (only its presence is read), and `data-footnotes` on sections. A paragraph's `data-embed-url` never renders: when it is a safe URL the paragraph becomes an embed placeholder (see [Embeds](#embeds)); the 5.x `div` markers (`data-plugin-type`, `data-video-id`, `data-tweet-id`, `data-url`) are dropped.
|
|
279
323
|
Event handlers, `target`, `rel`, `name` (except on links), `srcset`, `usemap`, `ping`, `formaction`, `xlink:href`, `tabindex` and every other attribute are dropped.
|
|
280
324
|
- **Attribute names** are read as an HTML parser stores them: in lower case, and of names that differ only in case the first one written. Kept attributes carry lower-case names, so `<p STYLE="text-align:center">` or `<a HREF="https://…">` renders the same on the server (where html-react-parser keeps the author's case) and in the browser, and hydrates without a mismatch.
|
|
281
325
|
- **`class`** keeps only the package's own tokens: the converter's markup (`markdown-alert`, `markdown-alert-{note,tip,important,warning,caution}`, `markdown-alert-title`, `octicon`, `octicon-{info,light-bulb,report,alert,stop}`, `mr-2`, `message`, `alert`, `info`, `warning`, `message-symbol`, `message-content`, `markdown-details`, `markdown-details-content`, `footnotes`, `footnote-ref`, `footnote-backref`, `math`, `inline`, `display`) and a code block's language (`language-*`).
|
|
282
326
|
An author's tokens and utility classes (`fixed inset-0 z-50` …) are dropped, so a document can neither restyle the page nor lay an element over it; a link's `className` (also the one `linkComponent` receives) holds only the kept tokens and the package's link classes. Tables carry their alignment in `align` and `style`, not in classes.
|
|
283
327
|
- **`id`** survives only on a heading (the table of contents, in-document links and a host's fragment navigation name headings by it), on the converter's footnotes (`fnref:N` / `fnrefK:N` on a reference's `sup`, `fn:N` on a note's `li`) and in the user-content namespace (`user-content-…`, the prefix GitHub-style footnotes use; write raw HTML fragment targets with it, or as `<a name="…">`).
|
|
284
|
-
Every other element loses its id, so a document cannot take a name the page or a script looks up (`getElementById`, the named properties of `window`). A heading keeps whatever id the document gives it: a host should not look up its own elements by an id a document could also give a heading (prefer refs).
|
|
328
|
+
Every other element loses its id, so a document cannot take a name the page or a script looks up (`getElementById`, the named properties of `window`). A heading keeps whatever id the document gives it, apart from an empty one, which is dropped: a host should not look up its own elements by an id a document could also give a heading (prefer refs).
|
|
285
329
|
- **Host sanitizers**: a host that sanitizes the HTML before the renderer (as `@aiquants/markdown-explorer` does with DOMPurify) gets the intersection of both allow lists; DOMPurify keeps `class` and `id` by default, so on the page the rules above are the ones that apply.
|
|
286
330
|
- **URLs** (`href`, `src`, `cite`, `poster`, `data-embed-url`): `http:`, `https:`, `mailto:` and `tel:` in any letter case, and references without a scheme. `javascript:`, `data:` and every other scheme are dropped, however they are spelled (entities, spaces, tabs, control characters). The mdast `LinkNode` and `ImageNode`, link cards (their link, image and icon) and the table of contents' entries follow the same rule.
|
|
287
331
|
- **`style`** keeps only its last valid `text-align` declaration (the alignment of table cells); positioning, `url()` and every other declaration are dropped. An SVG `fill` that references anything (`url(…)`) is dropped.
|
|
288
332
|
|
|
333
|
+
### Untrusted text
|
|
334
|
+
|
|
335
|
+
`allowlist` names the allow list `MarkdownRenderer` judges the HTML by. `"document"`, the default, is the one above.
|
|
336
|
+
`"untrusted"` is for text whose author the reader cannot hold to account, such as a model's answer or another user's
|
|
337
|
+
comment: it drops what reaches outside the text, and the host renders the text's images and links itself.
|
|
338
|
+
|
|
339
|
+
```tsx
|
|
340
|
+
import { MarkdownRenderer, type MarkdownImageProps, type MarkdownLinkProps } from "@aiquants/markdown"
|
|
341
|
+
|
|
342
|
+
// Module constants, so every render passes the same components
|
|
343
|
+
const AnswerImage = ({ src, alt }: MarkdownImageProps) => <span>{alt || src}</span>
|
|
344
|
+
const AnswerLink = ({ href, attributes, children }: MarkdownLinkProps) =>
|
|
345
|
+
href.startsWith("#") ? (
|
|
346
|
+
<a href={href} {...attributes}>{children}</a>
|
|
347
|
+
) : (
|
|
348
|
+
<a href={href} target="_blank" rel="noopener noreferrer nofollow" {...attributes}>{children}</a>
|
|
349
|
+
)
|
|
350
|
+
|
|
351
|
+
<MarkdownRenderer
|
|
352
|
+
htmlContent={answer.htmlContent}
|
|
353
|
+
allowlist="untrusted"
|
|
354
|
+
idPrefix="m1-"
|
|
355
|
+
imageComponent={AnswerImage}
|
|
356
|
+
linkComponent={AnswerLink}
|
|
357
|
+
/>
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
- **Images**: no `img` of the text becomes an element.
|
|
361
|
+
Each goes to `imageComponent` with `MarkdownImageProps`: `src` (a safe URL that is not blank, else `undefined`), `external` (whether `src` names a scheme, in any letter case, or another host with `//`, so an absolute URL is external even when it names the page's own origin; `false` without `src`),
|
|
362
|
+
`alt` as written (`undefined` when none was written; an empty one is a decorative image's), `title`, `assetPath` (`data-asset-src`), `assetExists` (`false` only for `data-asset-exists="false"`, `undefined` when the converter did not check) and `insideLink` (the image sits inside a link, where no further link may go).
|
|
363
|
+
The component decides whether the image becomes a link that shows where it points, its text, or an image the host trusts.
|
|
364
|
+
- **Links**: every `a` with an `href` that is not empty goes to `linkComponent`, an external one with the kind `"external"` and the others with the kind the converter wrote (an unknown value as it is, `undefined` without one). The package renders no `a[href]` of the text itself, so how a link opens (a confirmation before leaving, a fragment inside the message, a document link) is the host's. An `a` without an `href`, one whose `href` the allow list dropped included, stays a plain anchor.
|
|
365
|
+
- **Names**: `idPrefix`, an ASCII letter followed by ASCII letters, digits, `-` and `_`, heads every id the text keeps and every URL to a fragment after its `#` (a link's `href`, a quotation's `cite` and an image's `src`, as `imageComponent` receives it): with `m1-`, `#intro` is `#m1-intro`, which `linkComponent` receives without the characters a URL parser ignores. Give each text of a page its own prefix, none the start of another (with `a-` and `a-b-`, the ids `b-c` and `c` of two texts would both be `a-b-c`) nor of an id the page uses.
|
|
366
|
+
- **Dropped**: every `iframe` and every embed marker (a paragraph's `data-embed-url` never becomes a placeholder). Media (`video`, `audio`, `source`) and the sectioning elements the converter never writes (`main`, `nav`, `header`, `footer`, `section`, `article`) are unwrapped, so their text stays. An `aside` keeps no `title`; `name`, `headers` and `hidden` are dropped on every element; a `role` survives only as the converter's footnotes write it (`doc-noteref`, `doc-backlink`, `doc-endnotes`), and `aria-hidden` is the only ARIA attribute kept.
|
|
367
|
+
- **Placement**: put each text inside sectioning content of its own, such as the message's `article`, so the `aside` the converter writes for a message makes no landmark of the page.
|
|
368
|
+
- **Combinations**: `imageComponent`, `linkComponent` and `idPrefix` are required. `imageSource`, `embeds` that enable a provider or link cards, and `iFrameAllowedDomains` that allow a host do not go with the untrusted list, whose text loads no image, frame, post or card on its own; `imageComponent` and `idPrefix` do not go with the document list. A wrong combination, an `idPrefix` of another shape, or another value of `allowlist` throws a `RangeError` at render.
|
|
369
|
+
|
|
289
370
|
### Embeds
|
|
290
371
|
|
|
291
|
-
Embeds are opt in. `MarkdownRenderer` and `MarkdownViewer` take `embeds={{ providers, linkCardEndpoint, linkCardSize }}` (type `MarkdownEmbeds` from `@aiquants/markdown/embeds`; `linkCardSize`
|
|
372
|
+
Embeds are opt in. `MarkdownRenderer` and `MarkdownViewer` take `embeds={{ providers, linkCardEndpoint, linkCardSize, frameSandbox }}` (type `MarkdownEmbeds` from `@aiquants/markdown/embeds`; `linkCardSize` and `frameSandbox` are optional); the default `NO_EMBEDS` renders every link alone in a paragraph as that paragraph. Pass the value from a module constant (the viewer also compares it by value). An unknown provider id, a bad endpoint, an unknown card size or a `frameSandbox` with another token throws a `RangeError` at render.
|
|
292
373
|
|
|
293
374
|
```tsx
|
|
294
375
|
import type { MarkdownEmbeds } from "@aiquants/markdown/embeds"
|
|
@@ -325,7 +406,11 @@ Every host must match exactly (look-alike hosts, user info, ports and URLs carry
|
|
|
325
406
|
The server HTML holds the link and a reserved box (`width: 100%` up to the provider's maximum, its aspect ratio or height, never a CSS `min-width`), hidden for readers without JavaScript. A frame whose box is narrower than the provider's minimum (YouTube 356 px, Shorts 200 px, X 250 px, Instagram 326 px, Threads 281 px, Bluesky 300 px, LinkedIn 251 px, niconico 229 px) shows the fallback instead, and mounts again when the pane widens. X follows the primary subtag of the page's `<html lang>`; X, Threads and Bluesky follow `theme`.
|
|
326
407
|
Frames that report their height (X, Instagram, Threads, Bluesky, Reddit, note) are sized through one `message` listener that accepts only the frame's own window from its exact provider origin.
|
|
327
408
|
|
|
328
|
-
**
|
|
409
|
+
**What a frame may do.** `frameSandbox` is the most any frame of the document may do, `DEFAULT_FRAME_SANDBOX` (`allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-presentation`) when absent. A provider frame keeps the tokens of its registry value that `frameSandbox` holds; an iframe written in a document keeps the tokens of its own `sandbox` that `frameSandbox` holds, or takes the whole of `frameSandbox` when it has none. So a host narrows every frame and never widens one, and an empty string is the strictest sandbox.
|
|
410
|
+
The value lists only `EMBED_FRAME_SANDBOX_TOKENS`: the tokens of the HTML standard without the `allow-top-navigation` family, which lets a frame move the window that shows it, and without `allow-storage-access-by-user-activation`. `isEmbedFrameSandbox` tells whether a value qualifies and `narrowFrameSandbox(own, widest)` narrows one, for a host's sanitizer.
|
|
411
|
+
|
|
412
|
+
**Link cards.** A card asks `GET <linkCardEndpoint>?url=<href>` (same-origin credentials, `redirect: "error"`) once an IntersectionObserver rooted at the viewer's scroller sees it, through a page-wide queue (two requests at once, the 256 most recent answers kept, one per endpoint and link, aborted when no card needs the answer). The endpoint resolves against the page's address (`linkCardRequestOf(endpoint, link, pageAddress)`), so it works on a scheme without an origin such as `wails://`; on a page that cannot be a base (`about:blank`, `blob:`) the link stays the paragraph.
|
|
413
|
+
`MarkdownViewer`'s `fetch` is the function a card asks with, the global `fetch` when absent: a host that answers the endpoint in the same page passes its own. It may change on any render: the document is not parsed again, a running request keeps the function it started with, and viewers sharing an endpoint share its answers.
|
|
329
414
|
It links to the written `href` (never `og:url`), takes the host name from the `href`, and shows the image and the icon only when the endpoint gives absolute `http(s)` URLs of at most 2048 characters (`LINK_CARD_URL_LIMIT`) that are not on the page's own host, whatever the scheme or port (a browser loads an `http:` image of an `https:` page over `https:`, and cookies ignore the port), with no referrer. The package asks no favicon service.
|
|
330
415
|
|
|
331
416
|
`linkCardSize` picks the size of every card:
|
|
@@ -349,8 +434,8 @@ The endpoint contract:
|
|
|
349
434
|
- `createLinkCardHandler` from `@aiquants/markdown/server` implements this contract (see [Link-card endpoint](#link-card-endpoint)).
|
|
350
435
|
|
|
351
436
|
**Iframes written in documents.** `iFrameAllowedDomains` lists the hostnames such an iframe may load from: the `src` must be `https:`, without a user name, a password or an explicit port, and its hostname must match an entry exactly. Every other iframe is removed (fail closed), including an iframe without `src` (`srcdoc`). An allowed iframe is rendered from validated values and keeps only `title`, `width`, `height`, `allow`, `allowfullscreen`, `sandbox`, `referrerpolicy`, `loading`, `frameborder` and `scrolling` (no `id` or `class`).
|
|
352
|
-
An iframe without a `title` gets `"<embeddedFrame>: <host>"` (for example `Embedded content: www.youtube.com`), marked with the built-in label's
|
|
353
|
-
`allow` keeps only the six shared frame features — `autoplay`, `clipboard-write`, `encrypted-media`, `fullscreen`, `picture-in-picture`, `web-share` — each without its allowlist (`camera; microphone; autoplay` becomes `autoplay`); `referrerpolicy` is kept only as `no-referrer`, `origin`, `same-origin`, `strict-origin` or `strict-origin-when-cross-origin`. Until it mounts, and for good when its origin is the page's, the iframe renders as `<span data-embed-frame="pending|refused">` holding a link to its `src`.
|
|
437
|
+
An iframe without a `title` gets `"<embeddedFrame>: <host>"` (for example `Embedded content: www.youtube.com`), marked with the label's language (the built-in label's own, or `labelsLang` for one you pass).
|
|
438
|
+
`allow` keeps only the six shared frame features — `autoplay`, `clipboard-write`, `encrypted-media`, `fullscreen`, `picture-in-picture`, `web-share` — each without its allowlist (`camera; microphone; autoplay` becomes `autoplay`); `sandbox` stays within `frameSandbox` (see what a frame may do, above); `referrerpolicy` is kept only as `no-referrer`, `origin`, `same-origin`, `strict-origin` or `strict-origin-when-cross-origin`. Until it mounts, and for good when its origin is the page's, the iframe renders as `<span data-embed-frame="pending|refused">` holding a link to its `src`.
|
|
354
439
|
An iframe inside a link never mounts and stays that text, without a nested link: interactive content may not sit inside an `<a>`, and activating the link would follow the author's URL instead of the frame.
|
|
355
440
|
An iframe plugin (`data-plugin-type="dify"`) receives the validated iframe as structured props, never as an HTML string. The Dify plugin acts only on messages its own frame's window posts from an allowed origin, and ignores a message that is not an object with a string `type`.
|
|
356
441
|
|
|
@@ -364,7 +449,9 @@ An iframe plugin (`data-plugin-type="dify"`) receives the validated iframe as st
|
|
|
364
449
|
|
|
365
450
|
### Link-card endpoint
|
|
366
451
|
|
|
367
|
-
`createLinkCardHandler(options)` from `@aiquants/markdown/server` (Node only) is the card endpoint as a standard handler, `(request: Request) => Promise<Response>`. It reads only the request's method and its `url` search parameter, never its path, so mount it on any path and pass that path as `embeds.linkCardEndpoint`. Create it once, at module scope: each handler owns its cache
|
|
452
|
+
`createLinkCardHandler(options)` from `@aiquants/markdown/server` (Node only) is the card endpoint as a standard handler, `(request: Request) => Promise<Response>`. It reads only the request's method and its `url` search parameter, never its path, so mount it on any path and pass that path as `embeds.linkCardEndpoint`. Create it once, at module scope: each handler owns its cache. The handler opens pages through the markdown service, over the socket `parseMarkdown` uses, so a host that converts needs no new process:
|
|
453
|
+
it reads `MARKDOWN_SOCKET_PATH` and starts the service as `parseMarkdown` does. The service holds the whole network policy, the same for every host, and this package holds the card: the URL's shape, the cache, the 2xx and HTML checks, the encoding and the head's metadata (see `packages/go/markdown-api/README.md`, Link Cards).
|
|
454
|
+
`htmlparser2`, which reads the head, is loaded by no client entry except `@aiquants/markdown/link-cards` (`@aiquants/markdown/embeds` stays free of React and Node).
|
|
368
455
|
|
|
369
456
|
A React Router resource route (`app/routes/api.link-card.ts`, for example):
|
|
370
457
|
|
|
@@ -391,6 +478,16 @@ export const handle = (request: Request): Promise<Response> =>
|
|
|
391
478
|
|
|
392
479
|
The handler can also be called from inside another loader, for example a data route that dispatches several operations: it answers the request it is given.
|
|
393
480
|
|
|
481
|
+
A host that reaches the service through a connect transport of its own builds the same endpoint from `@aiquants/markdown/link-cards`, which reads no Node built-in and no Node transport; the transport must speak the binary format, and in Node it is the one named under [Service client](#service-client):
|
|
482
|
+
|
|
483
|
+
```ts
|
|
484
|
+
import { createConnectPageFetch, createLinkCardHandlerCore } from "@aiquants/markdown/link-cards"
|
|
485
|
+
|
|
486
|
+
const linkCards = createLinkCardHandlerCore({ authorize: () => true, pageFetch: createConnectPageFetch(transport) })
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
`pageFetch` (`PageFetchPort`) is the network half, two calls: `open(url, signal)` answers a page's head and body stream or why it was skipped, `classify(urls, signal)` answers whether each URL may be loaded. The answers below are the same over either entry.
|
|
490
|
+
|
|
394
491
|
**Options.** `authorize: (request) => boolean | Promise<boolean>` is the only option, and it is required. Anything but `true` answers 401 before anything is fetched; a host that serves everyone passes `() => true`. It must only read the request — no cookie writes, no token refresh — because cards ask in the background and a request can still be in flight while the reader signs out. A rejection propagates to the host. `createLinkCardHandler` throws a `TypeError` when `authorize` is not a function and for any other option.
|
|
395
492
|
|
|
396
493
|
**Answers.** Every answer carries `X-Content-Type-Options: nosniff` and never `Set-Cookie`; a `HEAD` answer has the `GET` answer's status and headers and no body.
|
|
@@ -401,7 +498,7 @@ The handler can also be called from inside another loader, for example a data ro
|
|
|
401
498
|
| `authorize` does not return `true` | 401 | `{"error":"Unauthorized"}` | `no-store` |
|
|
402
499
|
| No or an empty `url` | 400 | `{"error":"Missing 'url' parameter"}` | `no-store` |
|
|
403
500
|
| A link that gets no card | 204 (with `X-Link-Card-Skip: <reason>`) | none | per reason, below |
|
|
404
|
-
|
|
|
501
|
+
| The service cannot be reached or does not answer within 30 s, or an unexpected exception | 500 | `{"error":"Internal Server Error"}` | `no-store` |
|
|
405
502
|
| A card | 200 | `{ title?, description?, site_name?, image?, icon? }` (`LinkCardResponseBody`) | `private, max-age=1800` |
|
|
406
503
|
|
|
407
504
|
The JSON answers are `application/json; charset=utf-8`. The reasons of a 204:
|
|
@@ -409,31 +506,31 @@ The JSON answers are `application/json; charset=utf-8`. The reasons of a 204:
|
|
|
409
506
|
| Reason | When | `Cache-Control` |
|
|
410
507
|
| --- | --- | --- |
|
|
411
508
|
| `private-network` | The host is internal by name or by IP literal, it resolves to or connects to a private or special-use address, or a redirect leads to such a host | `private, max-age=1800` |
|
|
412
|
-
| `forbidden-url` | The URL or a redirect target is not `http(s)`, carries a user name or password, or does not parse | `private, max-age=1800` |
|
|
413
|
-
| `unreachable` | A network error, a timeout, a non-OK answer of the linked site, too many redirects
|
|
509
|
+
| `forbidden-url` | The URL or a redirect target is not `http(s)`, carries a user name or password, or does not parse (a stray `%` in a path parses and is sent as `%25`; a `Location` only a URL parser repairs, such as a `\` before the query, does not) | `private, max-age=1800` |
|
|
510
|
+
| `unreachable` | A network error, a timeout, a non-OK answer of the linked site, too many redirects, an unparsable `Location` or a body that breaks off | `private, max-age=300` |
|
|
414
511
|
| `not-html` | The page's `Content-Type` is missing or not HTML | `private, max-age=300` |
|
|
415
512
|
|
|
416
|
-
**Internal addresses never become cards**, in any environment; there is no switch. Internal is decided by address, never by
|
|
513
|
+
**Internal addresses never become cards**, in any environment; there is no switch. Internal is decided by address and by a fixed list of internal names, never by who holds a domain:
|
|
417
514
|
|
|
418
515
|
- a loopback, private, link-local, CGNAT, multicast, documentation, benchmarking, discard-only or reserved IPv4 or IPv6 address (every IANA special-purpose range that is not globally reachable) written as the host, in every form the URL parser normalizes (`2130706433`, `0x7f.1`, `127.1`, `[::ffff:127.0.0.1]`, and the NAT64, 6to4, Teredo and IPv4-translated forms);
|
|
419
516
|
- an internal name: `localhost`, `*.localhost`, a single-label name, one without a dot (the server's DNS search list would complete it to an internal name), and names under `.local`, `.internal` and `.home.arpa`, with or without a trailing dot;
|
|
420
|
-
- a name that resolves to an internal address: every connection resolves through a lookup that refuses a name when any of its A or AAAA answers is private, and
|
|
517
|
+
- a name that resolves to an internal address: every connection resolves through a lookup that refuses a name when any of its A or AAAA answers is private, and the service checks the very address connected to, for `https` too, so DNS rebinding cannot slip past;
|
|
421
518
|
- every redirect hop, checked again before it is followed.
|
|
422
519
|
|
|
423
520
|
**What the card shows.** The title is the last `og:title`, falling back to the first `<title>` of the document's head when that `og:title` is blank; the description is the last `og:description` or `<meta name="description">`; the site name the last `og:site_name`; the image the last `og:image`; the icon the first `<link rel>` holding the token `icon` (no `/favicon.ico` is guessed). A later blank `<meta>` clears an earlier one.
|
|
424
521
|
Only the head is read: parsing stops at the first body content, skips the content of a `<noscript>`, `<template>` or `<noframes>` in the head as a browser with scripting does, and stops at an element nesting deeper than 256, after 4096 start tags and at a tag with more than 64 attributes, so a hostile page costs time and memory linear in the bytes read. Text is trimmed and cut at the card's limits (title 300, description 1000, site name 200 code points), so `linkCardMetadataOf` reads every body back unchanged.
|
|
425
|
-
The image and the icon are resolved against the first `<base href>` — itself resolved against the page's URL, as a browser does, and used when it is `http(s)` and at most 2048 characters — else against the page's URL after redirects, and kept only when they are at most 2048 characters (`LINK_CARD_URL_LIMIT`)
|
|
522
|
+
The image and the icon are resolved against the first `<base href>` — itself resolved against the page's URL, as a browser does, and used when it is `http(s)` and at most 2048 characters — else against the page's URL after redirects, and kept only when they are at most 2048 characters (`LINK_CARD_URL_LIMIT`), the URL check accepts them and the service classifies them as loadable by the rules above.
|
|
426
523
|
Only `text/html` and `application/xhtml+xml` answers are read, decoded by WHATWG encoding sniffing: a byte order mark, then the `charset` of `Content-Type`, then a `<meta charset>` or `<meta http-equiv="Content-Type">` in the first 1024 bytes, else UTF-8 (Shift_JIS, EUC-JP, ISO-2022-JP and every other label `TextDecoder` knows; an unknown label is ignored).
|
|
427
524
|
|
|
428
|
-
**Limits.** 5 s per page for the headers, the body and its parsing; 5 redirects, each followed by hand and checked again; 64 KiB of response headers; at most the first 8 MiB of the body, read as a stream and parsed as it arrives, yielding to the event loop between chunks, and the download stops once the head has been read.
|
|
429
|
-
DNS
|
|
430
|
-
Each handler caches cards per URL for 1 hour and skips as long as their `Cache-Control`, 1000 URLs at most; the key is the URL as the URL parser serializes it without its fragment, so spellings of one URL share one entry, and concurrent requests for one URL share one fetch.
|
|
525
|
+
**Limits.** The service's, one set for every host: 5 s per page for the headers, the body and its parsing; 5 redirects, each followed by hand and checked again; 64 KiB of response headers; at most the first 8 MiB of the body, read as a stream and parsed as it arrives, yielding to the event loop between chunks, and the download stops once the head has been read.
|
|
526
|
+
DNS is asked by the service's own resolver, which reads the hosts file and the system's resolver configuration: A and AAAA side by side, each question 2 s at most, each name server 1 s to answer, and the system's `attempts` deciding how often it tries; a name connects over IPv4 when it has an A record, else over IPv6.
|
|
527
|
+
Each handler caches cards per URL for 1 hour and skips as long as their `Cache-Control`, 1000 URLs at most; the key is the URL as the URL parser serializes it without its fragment, so spellings of one URL share one entry, and concurrent requests for one URL share one fetch. A call to the service ends after 30 s, a page's body included, the same as a conversion's default time (the service bounds a page's fetch at 5 s): a service that stopped answering costs the requests sharing that fetch one 500, which is not cached, and the next request fetches again.
|
|
431
528
|
|
|
432
|
-
**Logs.** The handler logs through the package's logger
|
|
529
|
+
**Logs.** Never with a URL's user name, password, query or fragment. The handler logs through the package's logger: a URL refused by its shape at info (one that is not `http(s)` by its scheme alone), a body that breaks off and unexpected exceptions at error. The service logs every skipped page and a body cut at the size limit on its standard error.
|
|
433
530
|
|
|
434
531
|
### Links
|
|
435
532
|
|
|
436
|
-
- A link is external when its `href` names a scheme in any case (`https:`, `HTTPS:`, `mailto:`) or another host (`//host/…`, `/\host/…`), whatever its `data-link-kind` says, and when `data-link-kind` is `external`. An external link opens in a new tab with `rel="noreferrer"` and is never handed to `linkComponent
|
|
533
|
+
- A link is external when its `href` names a scheme in any case (`https:`, `HTTPS:`, `mailto:`) or another host (`//host/…`, `/\host/…`), whatever its `data-link-kind` says, and when `data-link-kind` is `external`. An external link opens in a new tab with `rel="noreferrer"` and is never handed to `linkComponent`, except under the untrusted list, which hands every link with an `href` to it (see [Untrusted text](#untrusted-text)). The author's `target` and `rel` never survive.
|
|
437
534
|
- `linkComponent` receives `href`, `kind`, `docPath`, `docExists`, `className`, `children` and `attributes`: the link's `id`, `title`, `lang`, `dir`, `role`, `aria-*` and `data-footnote-*` (event handlers, `style` and `href`-like attributes never pass). Spread `attributes` onto the anchor you render so footnote references keep their `id` and `aria-describedby` and back-references keep their `aria-label`:
|
|
438
535
|
|
|
439
536
|
```tsx
|
|
@@ -446,6 +543,21 @@ const AppLink = ({ href, className, attributes, children }: MarkdownLinkProps) =
|
|
|
446
543
|
|
|
447
544
|
- Only a link that wraps an image or block content is laid out as a box (`inline-block`); a link around text stays inline, so a footnote reference inside `<sup>` keeps the height of its glyphs and shows its focus ring.
|
|
448
545
|
|
|
546
|
+
### Headings below a host's headings
|
|
547
|
+
|
|
548
|
+
A document shown below the host's own headings (a message in a conversation, a panel of a page) passes `topHeadingLevel`
|
|
549
|
+
to `MarkdownRenderer`: the level its `#` headings render at, an integer from 1 to 9, deeper headings following one level
|
|
550
|
+
per depth. Levels up to 6 render as `h1`–`h6`, deeper levels as a `div` with `role="heading"` and `aria-level`, and every
|
|
551
|
+
level stops at 9: the HTML standard's heading offset, which browsers do not all support yet, so the package renders the
|
|
552
|
+
levels itself.
|
|
553
|
+
|
|
554
|
+
- While it is given, every heading carries `data-aqmd-heading-depth`, its depth in the document, since the element no
|
|
555
|
+
longer tells the depth: style the headings by it (`[data-aqmd-heading-depth="1"]`).
|
|
556
|
+
- A `role` or an `aria-level` the author wrote on a raw HTML heading wins over the computed one, and a `role` the author
|
|
557
|
+
wrote takes the computed `aria-level` away too.
|
|
558
|
+
- Without it, headings render as the converter wrote them; a value that is not an integer from 1 to 9 throws a
|
|
559
|
+
`RangeError`. `MarkdownViewer` and `NodesRenderer` do not take it.
|
|
560
|
+
|
|
449
561
|
### Content column and alignment
|
|
450
562
|
|
|
451
563
|
`MarkdownViewer` lays the document out in one column, `[data-aqmd-content]`, inside the scroll container's padding:
|
|
@@ -454,12 +566,45 @@ const AppLink = ({ href, className, attributes, children }: MarkdownLinkProps) =
|
|
|
454
566
|
| --- | --- |
|
|
455
567
|
| `width` | The column's CSS `width`. Unset, the column is `100%` wide: the full width of the scroll container's track, whatever the content, so a short document and a diagram drawn at the column's width get the whole width |
|
|
456
568
|
| `maxWidth` | The column's CSS `max-width` (`"1200px"`, `"min(1200px, 100%)"` …). Unset, nothing caps the column beyond `width` |
|
|
457
|
-
| `
|
|
569
|
+
| `measure` | `"fill"` (the default) keeps the column as above; `"reading"` bounds the document by `min(40ic, 80ch)` in its own font whatever the page's font, inside the column, so a reader's line stays readable (WCAG 1.4.8) and `maxWidth` still caps it. It applies to markdown documents, not to plain text, and to horizontal writing: under vertical writing Firefox reads `40ic` as 0 when the first font holds no ideograph, which hides the document, so a host on vertical writing turns the section off (`showMeasure={false}`) |
|
|
570
|
+
| `align` | Places a column narrower than the track: `left` (`margin-inline: 0 auto`), `center` (`auto`) or `right` (`auto 0`), and the document under the `reading` measure inside the column the same way. The margins are logical, so `left` is the line's start and `right` its end, and on a right-to-left page they sit the other way round. It shows only when `width`, `maxWidth` or the `reading` measure makes the content narrower than the track |
|
|
458
571
|
|
|
459
|
-
The alignment button needs `onAlignChange`, `showAlign` (on by default) and a `width` or `
|
|
572
|
+
The alignment button needs `onAlignChange`, `showAlign` (on by default) and a `width`, a `maxWidth` or, for a document, the `reading` measure. Without any of them the column fills the track and no alignment can move it, so the viewer does not render the button, whatever `showAlign` says.
|
|
460
573
|
|
|
461
574
|
With the `GitHub` and `Zenn` styles of `DEFAULT_MARKDOWN_STYLES`, a wide table or a long code line scrolls inside its own box. Content with a fixed width wider than the column, such as an embedded `<iframe>` whose `width` attribute exceeds it, overflows the column, and so does any wide content under the `None` style, which loads no stylesheet; the scroll container then scrolls sideways.
|
|
462
575
|
|
|
576
|
+
### Reader's display options
|
|
577
|
+
|
|
578
|
+
The toolbar's display button opens one popover with up to three sections. The viewer keeps none of the values: a host passes each one, stores what the reader chooses and passes it back. The button shows while a document shows and any section does.
|
|
579
|
+
|
|
580
|
+
| Section | Value | Reader's choice | Shown when |
|
|
581
|
+
| --- | --- | --- | --- |
|
|
582
|
+
| Style | `style`, from `availableStyles` | `onStyleChange` | `showStyle` (on by default) |
|
|
583
|
+
| Width | `measure` (`ContentMeasure`: `fill`, `reading`) | `onMeasureChange` | `onMeasureChange` is given and `showMeasure` is on (the default) |
|
|
584
|
+
| Colours | `contentColors` (`ContentColors`: `default`, `sepia`, `dark-low-glare`, `high-contrast`) | `onContentColorsChange` | `onContentColorsChange` is given and `showContentColors` is on (the default) |
|
|
585
|
+
|
|
586
|
+
Each section lists its options as `aria-pressed` buttons of 44 px in a labelled group, and a choice closes an unpinned popover. A change of style, width or alignment, a host's own included, does not parse the document again and keeps the reader's place: the block nearest the scroller's top stays where it was (a host's `width` or `maxWidth`, like a resized pane, keeps none). The place is read just before the commit that brings the new value, however late the host passes it back, and kept for two frames after that commit, so nothing is held while a host takes its time.
|
|
587
|
+
The blocks are the children of `[data-aqmd-document]`, the renderer's root, and what lists, quotations, sections and open `details` hold, passing over anything not visible (plain text is one block, its `pre`); within any other long block the place is its top, so a reader deep inside one moves as the text above reflows. A reader's scroll, a click (where the jumps of the document and its table of contents start) or another document ends those frames, and a reader at the top of the document stays at the top.
|
|
588
|
+
A jump with no click (a script's `location.hash`, `history.back()`) that opens a closed section within those frames reads as a reflow. The place reads the block axis of the viewer's own scroller, so vertical writing and a page whose window scrolls keep none.
|
|
589
|
+
A `measure` or a `contentColors` that is not one of its values throws a `TypeError`; normalize a value read from outside with `toContentMeasure` and `toContentColors` (see [Settings without React](#settings-without-react)).
|
|
590
|
+
|
|
591
|
+
`contentColors` picks one of three colour pairs (WCAG 1.4.8); `default` keeps the document style's own colours and writes nothing:
|
|
592
|
+
|
|
593
|
+
| Pair | Scheme | Ground | Text | Lowest text contrast |
|
|
594
|
+
| --- | --- | --- | --- | --- |
|
|
595
|
+
| `sepia` | Light | `#f4ecd8` | `#2b2116` | 7.20 |
|
|
596
|
+
| `dark-low-glare` | Dark | `#1c1e22` | `#d4cfc6` | 7.21 |
|
|
597
|
+
| `high-contrast` | Light | `#ffffff` | `#000000` | 12.02 |
|
|
598
|
+
|
|
599
|
+
- **Contrast**: every text of the content, whatever the style or the host's theme, reaches at least 7:1 on the ground painted under it: the body, muted text, links and the titles of the alerts on the page, on raised boxes (a table's stripes, inline code, a `details`), on `<mark>` and on the `:::message` boxes. The glyph on a message's disc reaches at least 3:1, as a symbol must.
|
|
600
|
+
- **What takes the pair**: the GitHub and Zenn variables, the alerts, `:::message` and `:::details`, link cards (their shadow keeps the theme's), the box of an embed, the notice of a diagram being drawn, a missing image, the viewer's error display, the full-screen dialog of a block, a formula KaTeX cannot read, and the scroll container, so the margin around a narrowed column takes the ground too and the native scroll bar the pair's scheme.
|
|
601
|
+
- **What keeps the host's theme**: code blocks, whose ground and tokens hold 7:1 on their own (see [Code blocks](#code-blocks)), the controls of a block, a table's grid and a diagram's drawing. The toolbar and its popovers are the viewer's, not the document's.
|
|
602
|
+
- **Forced colours**: the whole sheet sits inside `@media not (forced-colors: active)`, so the operating system's colours win.
|
|
603
|
+
- **Cascade**: the rules sit outside every cascade layer and beat the unlayered rules of the display stylesheets by specificity, so a host imports `markdown.css` without `layer()`, as for the link cards.
|
|
604
|
+
- **Hooks**: `data-aqmd-colors="<pair>"` on `[data-aqmd-scroll-container]` and `[data-aqmd-content]` while a pair other than `default` is chosen. Under it, `[data-aqmd-content]` declares the roles as custom properties (`--aqmd-colors-text-<role>`, `--aqmd-colors-ground-<role>`, `--aqmd-colors-rule`, `--aqmd-colors-symbol-<kind>`). The boxes that take a pair carry `data-aqmd-embed-surface`, `data-aqmd-mermaid-loading`, `data-aqmd-missing-image` and `data-aqmd-error-display`.
|
|
605
|
+
|
|
606
|
+
A caption, `figcaption` and the Zenn style's `img ~ em`, keeps a line height of 1.5 in every style and pair, the least WCAG 1.4.8 takes for a block of text.
|
|
607
|
+
|
|
463
608
|
### Code blocks
|
|
464
609
|
|
|
465
610
|
A fenced code block is highlighted by Shiki with two themes at once, `solarized-light` and `github-dark-high-contrast`. A token carries no colour of its own: its `style` holds only the themes' custom properties (`--shiki-light` and `--shiki-dark`, with `--shiki-light-font-style`, `--shiki-dark-font-weight` and the like for the font style, weight and decoration), and the `<pre>` keeps the same properties. Neither the `<pre>` nor a line sets a background or a text colour.
|
|
@@ -475,9 +620,11 @@ The colours come from the display stylesheet that paints the block, in a block o
|
|
|
475
620
|
|
|
476
621
|
A block rendered without such a sheet shows plain inherited text: the components carry no fallback colour. Load `zenn-content.css` after `github-markdown.css`, as above.
|
|
477
622
|
|
|
478
|
-
- **Contrast**: every token reaches at least 7:1 (WCAG AAA) on its block and on the tinted lines of a diff, in None, GitHub and Zenn, light and dark (the lowest measured in a browser is 7.01 for None and GitHub in the light scheme, 8.16 in the dark one; 7.15 for Zenn in the light scheme, 7.19 in the dark one).
|
|
623
|
+
- **Contrast**: every token reaches at least 7:1 (WCAG AAA) on its block and on the tinted lines of a diff, in None, GitHub and Zenn, light and dark (the lowest measured in a browser is 7.01 for None and GitHub in the light scheme, 8.16 in the dark one; 7.15 for Zenn in the light scheme, 7.19 in the dark one). The ➕ and ➖ signs of a diff bring their own colours, `#005923` on `#b9f8cf` and `#880003` on `#ffc9c9` (7.09:1 and 7.06:1), the same in every style and scheme, so no token colour can reach them.
|
|
479
624
|
- **Palette**: a theme colour that falls below 7:1 on any of those backgrounds is replaced by one with the same hue and chroma (chroma is lowered only to stay inside sRGB), moved in lightness only as far as 7:1 needs. The tints keep the hue of a translucent green and red and take the luminance of the block, so a tint never lowers a token's contrast.
|
|
480
|
-
- **Hooks** are data attributes, not classes:
|
|
625
|
+
- **Hooks** are data attributes, not classes:
|
|
626
|
+
`data-aqmd-code-block` on the block's root, `data-aqmd-code-header` on the header row above the code, `data-aqmd-code-filename` on the file name's tab, `data-aqmd-code-copy` on the copy button (the copy button of a display-math block carries it too) with `data-aqmd-copy-outcome` (`idle`, `copied` or `failed`), `data-aqmd-copy-notice` on the button's status region, `data-aqmd-code-pending` on the plain `pre` that holds the code while the highlighting loads,
|
|
627
|
+
`data-aqmd-diff="add"` or `"remove"` on a changed line, which sets no inline background, and `data-aqmd-diff-sign="add"` or `"remove"` on its sign.
|
|
481
628
|
- **Copy button and file name**: `markdown.css` colours them (`#1f2937` on `#e5e7eb`, `#d1d5db` on hover; in the dark scheme, `.dark` or `[data-theme="dark"]` on an ancestor, `#f3f4f6` on `#374151`, `#4a5361` on hover), every pair at 7:1 or more. The copy button is an icon button of 44 × 44 px under every pointer, and keyboard focus draws on it the package's two-colour focus ring (`--aqmd-control-focus-inner` and `--aqmd-control-focus-outer`, set on the block's root).
|
|
482
629
|
- **Layout**: the copy button never covers the code. The block's root holds a header row and then the `pre`; the header is a flex row at least 2.75rem (44 px) tall that packs its items to its inline end, with the file name at its inline start (when the fence names one; its own margin takes the free space) and the copy button at its inline end. A copy's outcome changes neither the button's size nor its name, so it moves nothing. A block without a file name keeps the row with the button alone, a long file name wraps inside the row, and the block's outer
|
|
483
630
|
margin is `1rem 0` either way (the markup is below the list).
|
|
@@ -486,6 +633,8 @@ A block rendered without such a sheet shows plain inherited text: the components
|
|
|
486
633
|
- **Loading**: the root, with its source lines, and the header row render at once. Until Shiki's HTML is ready, the `pre` holds the code as plain text in the highlighted `pre`'s box (`margin: 0; padding: 0.8rem 0`, a keyboard scroll stop as Shiki's is), so the lines wrap and scroll as the highlighted ones will and the block keeps its height when they replace it.
|
|
487
634
|
- **Hydration**: a block the browser hydrates takes over the lines, box and keyboard scroll stop the server highlighted, as they stand, and does not wait for the browser's highlighting, so no update that reaches it before Shiki loads (a context above the document changing, say a panel group measuring its container right after hydration) turns it into plain text. The browser highlights only the blocks it renders itself and a block whose code, language or diff mode changes; it loads no grammar for a hydrated block. React compares neither those lines nor
|
|
488
635
|
the `pre`'s attributes, so the server and the browser must render the same code, as they must for the rest of the document. A block whose highlighting the server did not complete (`renderToString` does not wait for it) shows plain text and highlights in the browser.
|
|
636
|
+
- **Waiting for the closing fence**: `CodeNode`'s `deferHighlight` (and `MarkdownRenderer`'s `streaming`, for the code blocks the converter marked open; see [Text that grows](#text-that-grows)) keeps the code as plain text in the highlighted `pre`'s box, and Shiki does not run for it.
|
|
637
|
+
A block that waited keeps that `pre` for its life: when the wait ends it shows the same plain text while Shiki highlights the code, then puts Shiki's attributes and lines on the same `pre` with no Suspense boundary in between, so the `pre` keeps its focus and horizontal scroll, the block its height and the reader's selection in the lines its place; waiting again shows the plain text in the same `pre`. A server renders a waiting block as the plain `pre`, and the browser hydrates it as it stands.
|
|
489
638
|
- **Languages**: a fence's language is highlighted when Shiki knows it — one of its languages or their aliases
|
|
490
639
|
(`bundledLanguages`), or a plain one (`text`, `txt`, `plain`, `plaintext`, `ansi`). `svg` is highlighted as `xml`.
|
|
491
640
|
Every other language (`logql`, a misspelling, a language in capitals such as `SVG`) renders as plain text, so no fence
|
|
@@ -581,16 +730,43 @@ as written.
|
|
|
581
730
|
Every top-level block renders inside its own error boundary. A block whose rendering throws in the browser — a host's
|
|
582
731
|
`linkComponent` that fails, a component's bug — shows a short notice in its place (`[data-aqmd-block-failure]`: the
|
|
583
732
|
label `blockFailed`, the renderer's `blockFailedLabel`, above the block's text in a `<pre>`; the built-in English notice
|
|
584
|
-
is marked `lang="en"`, a supplied one carries no language), the other blocks render, and React reports the error as a
|
|
733
|
+
is marked `lang="en"`, a supplied one carries `labelsLang`, or no language without it), the other blocks render, and React reports the error as a
|
|
585
734
|
caught one (the root's `onCaughtError`, the console by default). The block renders again as soon as its content
|
|
586
735
|
changes. React's server rendering does not stop at error boundaries, so such a block still fails a server render.
|
|
587
736
|
|
|
737
|
+
### Text that grows
|
|
738
|
+
|
|
739
|
+
A host that renders a text while it is still being written (a model's answer as it streams) converts each state of the
|
|
740
|
+
text with `includeStreamingHints` and passes the result's `blockOffsets` along with its HTML:
|
|
741
|
+
|
|
742
|
+
```tsx
|
|
743
|
+
// result: one conversion of the text so far, with includeStreamingHints: true
|
|
744
|
+
<MarkdownRenderer
|
|
745
|
+
htmlContent={result.htmlContent}
|
|
746
|
+
blockOffsets={result.blockOffsets}
|
|
747
|
+
streaming={!finished} // the stream still writes the text
|
|
748
|
+
blockKeyEpoch={attempt} // changes when the text is replaced rather than extended
|
|
749
|
+
/>
|
|
750
|
+
```
|
|
751
|
+
|
|
752
|
+
- **Blocks**: with `blockOffsets`, the renderer cuts the HTML into its top-level blocks and parses and renders only the blocks whose HTML changed since the last committed render. An unchanged block keeps its elements, its formulas' reports and its count of images (KaTeX and Shiki do not run for it again), and a block holding an image renders again when the images before it changed (the document's first image loads eagerly).
|
|
753
|
+
A block whose HTML changed but stands where the last render had an unmatched block of the same root element takes that block's key, so a growing block keeps its components (focus, scroll, an open `details`). Without `blockOffsets` the whole document is parsed on every render.
|
|
754
|
+
- **Stable props**: the kept blocks are dropped whenever another prop that shapes the elements changes (the theme, labels, components, readers), so pass stable values; a labels object or a `linkComponent` made anew on every render drops them every time. `imageSource` and `spreadsheetEditor` may change on any render: the renderer holds a stable stand-in for each.
|
|
755
|
+
- **Unchanged parts**: inside a block that renders again, a closed code block's highlighting, the frame of a display formula and the copy buttons render again only when their values change.
|
|
756
|
+
- **Selection**: the reader's selection inside the document stays across these renders. A point inside a text React rewrote returns to its place, cut to the text's new length; a point between elements stays where the DOM moved it. An empty selection, one outside the document, one whose node left the document in the commit and one the commit did not move are left alone.
|
|
757
|
+
- **Replaced text**: `blockKeyEpoch`, a safe integer, tells the renderer that the text was replaced rather than extended (a stream that restarted, a conversation read again); change it together with the new text's HTML. A render whose epoch differs from the last committed render's hands a block its predecessor's key only when both have the same content, so no component of the replaced text passes to the new one.
|
|
758
|
+
- **Open code blocks**: while `streaming` is true, a code block the converter marked open (`data-open-code` on its `pre`) shows its code as plain text and Shiki does not run for it, as a later line can still close it or add code; a code block without the mark is highlighted at once. When the mark goes (the closing fence arrived) or `streaming` turns false, the block is highlighted in the same `pre` (see [Code blocks](#code-blocks)). A change of `streaming` renders again only the blocks that hold a marked code block.
|
|
759
|
+
- **Errors**: offsets that do not start at 0, do not increase, are not safe integers or point outside `htmlContent` (or none for HTML that holds a block), an epoch that is not a safe integer and `streaming` true without `blockOffsets` throw a `RangeError`.
|
|
760
|
+
|
|
588
761
|
### Mermaid diagrams
|
|
589
762
|
|
|
590
763
|
A fenced code block in the `mermaid` language renders as `MermaidDiagram`, a block that takes its containing block's width (its slot). The first child of the block's dialog (see [Full screen](#full-screen)) is a hidden measuring element, `[data-aqmd-mermaid-measure]` (no height, clipped, `visibility: hidden`, `aria-hidden`), present while the diagram loads, shows or fails; the component measures the slot's width with it (the window's width, less the dialog's padding, while full screen).
|
|
591
764
|
Each drawing gets its own drawing host, `[data-aqmd-mermaid-host]`: a hidden element (`visibility: hidden`, `aria-hidden`, absolutely positioned just outside the start edge, `contain: strict`) appended to the main document's `<body>`, with its width set to the measured width in px.
|
|
592
765
|
Mermaid draws in that element and the component shows the result in the slot, so a gantt chart, whose width Mermaid takes from where it is drawn, is exactly as wide as the slot. Because Mermaid looks its drawing up through the main document, the host lives in the main document's light DOM, and a diagram in a slot inside a shadow root is drawn the same way.
|
|
593
766
|
|
|
767
|
+
- **Loading Mermaid**: the library is imported, a chunk of its own, when the first diagram with text mounts, and initialized once for the page without its start-on-load scan, so a document without diagrams never loads it, nor does a diagram of white space alone.
|
|
768
|
+
A module that fails to load, Mermaid's own or one Mermaid loads to draw a diagram, is tried once more by itself 300 ms later without an error showing; the diagram shows its error when that attempt fails too or the failure is of another kind, and its retry button tries again with one more such attempt.
|
|
769
|
+
A failed setup (a library without `initialize`, or an `initialize` that throws) is shared by every later diagram for the page's life.
|
|
594
770
|
- Every diagram on the page hands its drawings to Mermaid through one lane, one at a time and in the order they were requested. A drawing that is stale when its turn comes (a newer drawing of the same diagram was requested, its text changed, or the component unmounted) never reaches Mermaid and gets no drawing host.
|
|
595
771
|
- The component removes a drawing host when Mermaid settles its drawing (shown, failed, or discarded as stale) and never earlier, also after the text changed or the component unmounted: Mermaid keeps drawing in the element it found, and in an element outside the document every measurement is 0, which gives a flowchart's labelled edges `translate(undefined, NaN)`. No host is left behind, not even the error drawing Mermaid leaves for a text it cannot parse.
|
|
596
772
|
- Nothing is drawn while the slot has no width (inside a closed `<details>` the browser does not lay out, or a hidden panel): the loading text stays until the slot gets a width. A drawing already under way when the slot loses its width finishes at the width it was given.
|
|
@@ -624,6 +800,11 @@ Mermaid draws in that element and the component shows the result in the slot, so
|
|
|
624
800
|
- **Colours and focus ring**: the controls, the menu items, the checked item, the error message and the retry button reach 7:1 against their surfaces in both schemes (dark when `.dark` or `[data-theme="dark"]` is on an ancestor). The focus ring of the frame, the toolbar controls and the retry button is a 2 px `#003abc` outline with a white 4 px halo, 9:1 apart, so some part of it stands out on any background (WCAG 2.4.13, 1.4.11); the menu items draw it inset. The ring's rules sit outside every cascade layer, so the controls' `shadow` utility cannot replace the halo.
|
|
625
801
|
- **Hooks**: `data-aqmd-mermaid` (the root, which carries the palette's CSS variables, and `data-aqmd-fullscreen` while full screen), `data-aqmd-fullscreen-dialog`, `data-aqmd-mermaid-frame`, `data-aqmd-mermaid-toolbar`, `data-aqmd-mermaid-control` (`mode`, `zoom-in`, `zoom-out`, `reset`, `pan-left`, `pan-up`, `pan-down`, `pan-right` or `fullscreen`), `data-aqmd-mermaid-menu`, `data-aqmd-mermaid-error` and `data-aqmd-mermaid-retry`. The component writes the drawing's natural aspect ratio on its `<svg>` as `--aqmd-mermaid-ratio`, which the full-screen layout reads.
|
|
626
802
|
|
|
803
|
+
`@aiquants/markdown/mermaid-frame` (`dist/mermaidFrame/frame.js`, with the licenses of the code inside it in `NOTICES.md`
|
|
804
|
+
beside it) is the script of a drawing place: one self-contained file, Mermaid without KaTeX, that a frame document loads
|
|
805
|
+
as a module script to draw the diagrams sent to it over a message port, with every key of Mermaid's configuration
|
|
806
|
+
locked. The components above draw diagrams in the page and do not load it.
|
|
807
|
+
|
|
627
808
|
### Spreadsheets
|
|
628
809
|
|
|
629
810
|
A fenced code block in the `spreadsheets` language renders as `SpreadsheetBlock`: its body is a TSV table drawn with
|
|
@@ -663,7 +844,7 @@ Total 17,600 MT
|
|
|
663
844
|
| `headings=N` | 0, 1 | 1 | 0 leaves out the column letters, the row numbers and their corner, in the grid and in the plain table (Excel's "headings"; `header=` is the table's own header rows) |
|
|
664
845
|
| `autofit=N` | 0, 1 | 0 | 1 fits every column to the widest text of all its rows (header rows in bold) when the grid loads, when the table or the options change, and when a web font of the cells' families finishes loading; a column without text keeps its width |
|
|
665
846
|
| `frame=N` | 0–3 | 0 | N from 1 draws a line N CSS px wide (at 100 %) just inside the outer edges of the table's body, the frame a printed table has (see the frame below); 0 draws none |
|
|
666
|
-
| `tapscroll=N` | 0, 1 | 0 | 1 shows the grid's tap-scroll circle on this table, 24 CSS px across
|
|
847
|
+
| `tapscroll=N` | 0, 1 | 0 | 1 shows the grid's tap-scroll circle on this table, in the look and at the size the host passes (24 CSS px across, WCAG 2.5.8's minimum target, when it passes none); 0 leaves it out, so a reader scrolling the page past a document's tables meets a circle only where its author asked for one (see the circle below) |
|
|
667
848
|
|
|
668
849
|
- **Options are strict**: words are `key=value` separated by white space, each key at most once, each value a decimal integer
|
|
669
850
|
without a sign or leading zeros. An unknown key, a repeated key, a malformed word, a value out of range or a `zoom` that is
|
|
@@ -727,17 +908,20 @@ Total 17,600 MT
|
|
|
727
908
|
- **The tap-scroll circle**: `spreadsheetTapScrollCircle` on `MarkdownRenderer` and `MarkdownViewer` gives the tables of a
|
|
728
909
|
document the look and the speeds of the grid's tap-scroll circle (the grid's `tapScrollCircleOptions`, a
|
|
729
910
|
`ScrollBarTapCircleOptions`, such as `@aiquants/virtualscroll`'s sample visual; the grid's own look when absent). A
|
|
730
|
-
document's table shows the circle only when its options say `tapscroll=1`,
|
|
731
|
-
|
|
732
|
-
|
|
911
|
+
document's table shows the circle only when its options say `tapscroll=1`, so the look's `enabled` is not read. The
|
|
912
|
+
look's `size` is the circle's diameter; without one it is 24 CSS px, the minimum target of WCAG 2.5.8 (AA): the circle
|
|
913
|
+
takes a press anywhere in its square box, only its look being round, so the criterion's 24 × 24 square lies within it.
|
|
914
|
+
A `size` that is not a whole number or lies under 24 throws a `RangeError` from the render, as a wrong `embeds` does,
|
|
915
|
+
whatever the document holds. A host
|
|
733
916
|
that renders `SpreadsheetBlock` itself to show one table (a file preview) passes the circle as `tapScrollCircle`, shown
|
|
734
917
|
as given (`tapScrollCircleShownBy`, `"host"` by default); `"options"` applies the document's rule (the tables
|
|
735
918
|
MarkdownRenderer and the mdast path's `CodeNode` draw use it — the mdast path has no prop for the look, so its tables
|
|
736
919
|
show the grid's own). Keep the circle's identity across renders: the viewer draws the document again when it changes,
|
|
737
|
-
and MarkdownRenderer draws every table's grid again. The circle is below 2.5.5's 44 px (AAA), the size of the
|
|
738
|
-
controls and of the grid's own circle, and that criterion's exceptions do not cover it: it floats over the
|
|
739
|
-
which are targets themselves, and the table's scroll bars are 12 px
|
|
740
|
-
table scrolls without it by a finger's drag, the wheel
|
|
920
|
+
and MarkdownRenderer draws every table's grid again. The 24 px circle is below 2.5.5's 44 px (AAA), the size of the
|
|
921
|
+
block's controls and of the grid's own circle, and that criterion's exceptions do not cover it: it floats over the
|
|
922
|
+
cells, which are targets themselves, and the table's scroll bars are 12 px, so a host that holds to AAA passes a `size`
|
|
923
|
+
of 44. The circle is an aid a writer opts into per table; the table scrolls without it by a finger's drag, the wheel
|
|
924
|
+
and the keys.
|
|
741
925
|
- **The scroll bars' controls**: `spreadsheetScrollBarControls` on `MarkdownRenderer` and `MarkdownViewer` gives the
|
|
742
926
|
tables of a document the controls of the grid's scroll bars (the grid's `scrollBarControls`, a
|
|
743
927
|
`SpreadsheetScrollBarControls` with `showArrowButtons`, `enableThumbDrag` and `enableTrackClick`; the grid's own bars
|
|
@@ -897,7 +1081,7 @@ and the SVG image block. Code blocks, formulas, other images and embeds have non
|
|
|
897
1081
|
|
|
898
1082
|
### Viewer toolbar
|
|
899
1083
|
|
|
900
|
-
`MarkdownViewer` shows its alignment,
|
|
1084
|
+
`MarkdownViewer` shows its alignment, display and table-of-contents buttons as one fixed row, in that visual and tab order, spaced in `rem` so they never overlap at large text sizes. Place the row with two package-scoped custom properties, both `0px` unless set:
|
|
901
1085
|
|
|
902
1086
|
| Property | Effect |
|
|
903
1087
|
| --- | --- |
|
|
@@ -917,11 +1101,14 @@ A viewer inside a containing block of its own (an element with `contain: layout
|
|
|
917
1101
|
Each button is a circle `--aqmd-toolbar-block-size` across: 11 spacing steps plus a 1 px border on each side, 46 px at the default step (`0.25rem`), a 44 px target inside the border. The package stylesheet defines the property on the scroll container and gives every `[data-aqmd-toolbar-button]` that border-box width and height with its icon centred, so the row is as tall as one button whatever
|
|
918
1102
|
the host's font, line height and box sizing. The step is the one the stylesheet's utilities take: `markdown.css` reads the host's `--spacing` (`0.25rem` when the page defines none), so a Tailwind host that changes it scales the buttons with it, and `markdown.standalone.css` writes the default theme's step in, as it does into its own utilities, and never reads a `--spacing` on the page.
|
|
919
1103
|
|
|
920
|
-
The scroll container (`[data-aqmd-scroll-container]`) publishes `--aqmd-toolbar-block-overlap`: the depth of its top band that the floating toolbar covers, `0px` at widths where the toolbar covers none of the content. The viewer already reserves it as top padding and `scroll-padding-block-start`, so the first line and fragment targets stay clear of the buttons; read it when you place your own content at the start of the container.
|
|
1104
|
+
The scroll container (`[data-aqmd-scroll-container]`) publishes `--aqmd-toolbar-block-overlap`: the depth of its top band that the floating toolbar covers, `0px` at widths where the toolbar covers none of the content. The viewer already reserves it as top padding and `scroll-padding-block-start`, so the first line and fragment targets stay clear of the buttons; read it when you place your own content at the start of the container.
|
|
1105
|
+
A change of the depth moves the content by the difference in Chromium and WebKit, whose scroll anchoring does not answer a change of padding; Firefox's does. After a change of style, width or alignment the viewer therefore keeps the reader's block for the two frames in which the depth that change brings is measured, and converts the distance to the container's own px, so a CSS `zoom` or a transform above the viewer keeps the block where it was; the viewer answers no other change of the depth, so a scroll in progress runs on.
|
|
1106
|
+
The depth is measured in the container's own CSS px and rounded up to a whole px, so a CSS `zoom` or a transform above the viewer gives the depth it has at 100 %.
|
|
921
1107
|
The value is measured again whenever the container, the content or the toolbar resizes, the window resizes, the alignment changes (the content moves sideways), anything scrolls (a toolbar fixed to the viewport stays put while the container moves; at most once per frame), and the two inset properties change (an invisible box inside the toolbar, `[data-aqmd-toolbar-inset-probe]`, takes its size from them). A container with no layout (under a `display: none` ancestor) is not measured: the band in force stays, so the content does not move when the container is shown.
|
|
922
1108
|
|
|
923
1109
|
Until the viewer has measured it (the server's markup and the first client render), the container carries no inline value and the package stylesheet supplies one: `0px`, unless the host opts in with `--aqmd-toolbar-reserve-before-measure: 1` on an ancestor.
|
|
924
|
-
Opted in, a container whose toolbar certainly covers the content's inline extent (`[data-aqmd-toolbar-over-content]`: the toolbar is shown and neither `width` nor `maxWidth` is given, so the column runs under it) reserves the toolbar's reach, `--aqmd-toolbar-block-reach`: `--aqmd-toolbar-inset-block-start` plus `--aqmd-toolbar-block-size`, rounded up to a whole px (with `round()`, in browsers that support it).
|
|
1110
|
+
Opted in, a container whose toolbar certainly covers the content's inline extent (`[data-aqmd-toolbar-over-content]`: the toolbar is shown and neither `width` nor `maxWidth` is given, so the column runs under it) reserves the toolbar's reach, `--aqmd-toolbar-block-reach`: `--aqmd-toolbar-inset-block-start` plus `--aqmd-toolbar-block-size`, rounded up to a whole px (with `round()`, in browsers that support it).
|
|
1111
|
+
The rounding starts 1/256 px below the exact sum, so a browser that computes the band in the px of a page zoom or a CSS `zoom` never lifts a whole sum by a px through floating-point error.
|
|
925
1112
|
The stylesheet registers a copy of the reach as a length, `--aqmd-toolbar-block-reach-px` (`@property`), which the viewer reads in the container's own px; no rule substitutes the copy, because Firefox applies a CSS `zoom` a second time to a registered length that `var()` substitutes. The viewer writes the reach in place of the measured depth whenever the toolbar's bottom lies within the reach's px (from 1 px above the reach to the reach), widened on each side by the snapping of the toolbar's inset and size,
|
|
926
1113
|
which layout applies before the viewer measures them: two layout units of 1/16 px each, the coarsest a browser lays a page out in (1/64 of a px of the page's zoom, at the smallest zoom, 25 %), divided by a CSS `zoom` below 1. So the document's first line stays where the server put it, for a toolbar whose containing block starts at the container's top, at any root font size and zoom. In a browser without `@property` the viewer writes the measured depth rounded up, which can move the first line by 1 px.
|
|
927
1114
|
Opt in only for such a layout (the viewer fills its own containing block, or the viewport, from its top); elsewhere the first line moves once, to the measured depth.
|
|
@@ -940,7 +1127,7 @@ The bound is the popover's border box (the popover is `box-sizing: border-box` w
|
|
|
940
1127
|
|
|
941
1128
|
An open, unpinned popover closes on Escape while the focus is inside its menu, returns the focus to its button and calls `preventDefault()` on that keydown, so an outer Escape handler can skip a key the viewer consumed. Escape is not consumed while no popover is open.
|
|
942
1129
|
It also closes on a pointer press outside its menu. A touch press that closes it consumes the click it produces (on the document's capture phase, within 800 ms and 16 px of the press), so the tap that dismisses the popover does not also follow a link or press a heading under the finger; a press that turns into a scroll produces no click, and once the browser cancels its pointer the next tap is not consumed; a press on the toolbar itself (another menu's button) is not consumed, and a mouse press's click goes through.
|
|
943
|
-
Under every pointer the toolbar's buttons, the popovers' pin buttons, the
|
|
1130
|
+
Under every pointer the toolbar's buttons, the popovers' pin buttons, the display and alignment items and the table of contents' entries are 44 px targets (WCAG 2.2 enhanced target size; a `TableOfContents` entry is padded above and below by half of what its line box lacks of 44 px, `max(0px, (2.75rem - 1lh) / 2)`, so it holds at any font size, and the entries stack edge to edge); a popover's heading and the table of contents' links keep 7:1 against the popover in both themes.
|
|
944
1131
|
|
|
945
1132
|
### Host scroll bar
|
|
946
1133
|
|
|
@@ -973,7 +1160,8 @@ The viewer adds the lane to the container's inline-end padding, outside `padding
|
|
|
973
1160
|
With a lane the container's padding is `padding-inline-start: <padding>px; padding-inline-end: calc(<padding>px + <lane>)`; without one it stays `padding-inline: <padding>px`.
|
|
974
1161
|
A string is written as given (white space around it removed), so a lane that the host varies with its own media queries, through a custom property, gives the same server markup on every device and no hydration difference. It takes one of two forms:
|
|
975
1162
|
|
|
976
|
-
- **A non-negative CSS length**: an unsigned integer or decimal, with an optional exponent, directly followed by a length unit in any ASCII case (`"54px"`, `"3.5rem"`, `"0.5EM"`, `"1e1px"`). The units are `px`, `cm`, `mm`, `q`, `in`, `pc`, `pt`, `em`, `rem`, `ex`, `rex`, `cap`, `rcap`, `ch`, `rch`, `ic`, `ric`, `lh`, `rlh`, `vw`, `vh`, `vi`, `vb`, `vmin`, `vmax`, `svw`, `svh`, `svi`, `svb`, `svmin`, `svmax`, `lvw`, `lvh`, `lvi`, `lvb`, `lvmin`, `lvmax`, `dvw`, `dvh`, `dvi`, `dvb`, `dvmin`, `dvmax`, `cqw`, `cqh`, `cqi`, `cqb`, `cqmin` and `cqmax`;
|
|
1163
|
+
- **A non-negative CSS length**: an unsigned integer or decimal, with an optional exponent, directly followed by a length unit in any ASCII case (`"54px"`, `"3.5rem"`, `"0.5EM"`, `"1e1px"`). The units are `px`, `cm`, `mm`, `q`, `in`, `pc`, `pt`, `em`, `rem`, `ex`, `rex`, `cap`, `rcap`, `ch`, `rch`, `ic`, `ric`, `lh`, `rlh`, `vw`, `vh`, `vi`, `vb`, `vmin`, `vmax`, `svw`, `svh`, `svi`, `svb`, `svmin`, `svmax`, `lvw`, `lvh`, `lvi`, `lvb`, `lvmin`, `lvmax`, `dvw`, `dvh`, `dvi`, `dvb`, `dvmin`, `dvmax`, `cqw`, `cqh`, `cqi`, `cqb`, `cqmin` and `cqmax`;
|
|
1164
|
+
a percentage is no lane, since the lane is a length.
|
|
977
1165
|
- **A custom property reference without a fallback**, `var(--name)`: the name is `--` followed by one or more of `A-Z`, `a-z`, `0-9`, `_` and `-`, and white space may stand inside the parentheses (`"var(--my-bar-lane)"`, `"var( --my-bar-lane )"`). The browser resolves it, so define the property as a length: an undefined property, or one that is not a length, leaves the inline-end padding at 0.
|
|
978
1166
|
|
|
979
1167
|
Any other string throws a `RangeError`, on the server and in the browser alike (the check is a fixed grammar and does not ask `CSS.supports`): an empty or white-space-only string, a bare number (`"54"`, which `calc()` cannot add to a length), a sign (`"-1rem"`, `"+1rem"`), white space before the unit (`"10 px"`), a percentage (`"50%"`), `calc()` or any other function, a fallback (`"var(--x, 1px)"`), two values (`"1px 2px"`) and any other character (`"10px;color:red"`).
|
|
@@ -1075,11 +1263,28 @@ const headingHref: MarkdownHeadingHrefResolver = (heading) => `/docs/guide.md#${
|
|
|
1075
1263
|
|
|
1076
1264
|
Every name and text the viewer draws comes from `labels` (`MarkdownViewerLabels`), including the table-of-contents and alignment controls and, through the `mermaid*` keys, the controls of each Mermaid diagram (`MermaidDiagram` takes `MermaidDiagramLabels` as `labels`) and, through the `spreadsheet*` keys, the labels of each spreadsheet block (`SpreadsheetBlock` takes `SpreadsheetBlockLabels` as `labels`), and, through the `svgImage*`, `codeBlock*` and `displayMath*` keys, those of the SVG image blocks, the code blocks and the display formulas
|
|
1077
1265
|
(`MarkdownRenderer` takes them as `svgImageLabels`, `codeBlockLabels` and `displayMathLabels`; `CodeNode` takes `CodeBlockLabels` as `labels`).
|
|
1078
|
-
|
|
1079
|
-
A
|
|
1266
|
+
`labelsLang` (BCP 47) names the language of the labels you pass: each one marks the element that bears it with that `lang`, written in its canonical form (`en-us` is `en-US`). `MarkdownViewer`, `MarkdownRenderer`, `MermaidDiagram`, `SpreadsheetBlock` and `CodeNode` take it, and it also marks the texts you pass in place of built-in ones: the viewer's `emptyMessage` and the renderer's `missingImageLabel` and `blockFailedLabel`.
|
|
1267
|
+
A string that is not a well-formed tag (`en_US`, an empty string) throws a `RangeError` during render, and a value that is not a string a `TypeError`. Without `labelsLang`, a label you pass carries no language of its own and is read in the language around it.
|
|
1268
|
+
A built-in label marks the element that bears it with its own language, whatever `labelsLang` says: the status texts and display controls are English (`lang="en"`), the table-of-contents, alignment and Mermaid menu controls are Japanese (`lang="ja"`), and the Mermaid zoom, pan and full-screen buttons, the diagram's frame name, its loading notice and its error texts are English. The embed labels (`embeddedVideo`, `embeddedPost`, `embeddedFrame`) and the labels of the SVG image blocks, the code blocks and the display formulas are English. `DEFAULT_MARKDOWN_VIEWER_LABELS`, `DEFAULT_MERMAID_DIAGRAM_LABELS`,
|
|
1080
1269
|
`DEFAULT_MARKDOWN_EMBED_LABELS`, `DEFAULT_SVG_IMAGE_LABELS`, `DEFAULT_CODE_BLOCK_LABELS` and `DEFAULT_DISPLAY_MATH_LABELS` hold the built-in texts.
|
|
1081
1270
|
|
|
1082
|
-
|
|
1271
|
+
`contentLang` (BCP 47) is the language of the document: the viewer writes it as `lang` on the content element, only while it shows a document, so its own controls and its loading, error and empty texts keep the labels' language. Absent, the content inherits the page's language.
|
|
1272
|
+
The controls of a block sit inside the content: a built-in label keeps its own `lang`, and a label you pass is read in `labelsLang`, or, without it, in `contentLang`. Pass `labelsLang` whenever you pass both labels and `contentLang`, so labels in your page's language are not read in the document's (WCAG 2.2 SC 3.1.2, Language of Parts).
|
|
1273
|
+
|
|
1274
|
+
The display popover's keys of `MarkdownViewerLabels`, all optional and all marked `lang="en"` when built in:
|
|
1275
|
+
|
|
1276
|
+
| Key | Names | Built-in text |
|
|
1277
|
+
| --- | --- | --- |
|
|
1278
|
+
| `styleTitle` | The popover's heading | Display |
|
|
1279
|
+
| `selectStyleAria` | The display button | Display options |
|
|
1280
|
+
| `pinStyleAria`, `unpinStyleAria` | The pin button | Pin display options / Unpin display options |
|
|
1281
|
+
| `styleSectionTitle`, `measureTitle`, `colorsTitle` | The sections' headings | Style / Width / Colors |
|
|
1282
|
+
| `measureFill`, `measureReading` | The width options | Full width / Reading width |
|
|
1283
|
+
| `colorsDefault`, `colorsSepia`, `colorsDarkLowGlare`, `colorsHighContrast` | The colour options | Document colors / Sepia / Dark, low glare / High contrast |
|
|
1284
|
+
|
|
1285
|
+
`missingImage` is the notice of an image that cannot be found (`missingImageLabel` on `MarkdownRenderer`; "Image not found", marked `lang="en"`).
|
|
1286
|
+
|
|
1287
|
+
The Mermaid keys of `MermaidDiagramLabels`, all optional (the viewer's key for each is `mermaid` followed by the key with a capital first letter: `panUp` is `mermaidPanUp`; `errorPrefix` alone is the viewer's own `errorPrefix`, one text for the viewer's error and the diagrams'):
|
|
1083
1288
|
|
|
1084
1289
|
| Key | Names | Built-in text | `lang` |
|
|
1085
1290
|
| --- | --- | --- | --- |
|
|
@@ -1093,11 +1298,15 @@ The Mermaid keys of `MermaidDiagramLabels`, all optional (the viewer's key for e
|
|
|
1093
1298
|
| `fullscreenDialog` | The block's dialog while full screen | Diagram (full screen) | `en` |
|
|
1094
1299
|
| `diagram` | The diagram's focusable frame, its toolbar and, outside full screen, the block's dialog | Diagram (arrow keys pan, + and - zoom, 0 resets) | `en` |
|
|
1095
1300
|
| `retry` | The retry button after a failed drawing | 再試行 | `ja` |
|
|
1301
|
+
| `loading` | The notice while a diagram is drawn | Loading diagram... | `en` |
|
|
1302
|
+
| `errorPrefix` | The text in front of the reason a diagram could not be drawn | Error: | `en` |
|
|
1303
|
+
| `initializationFailed`, `renderFailed` | The reason when Mermaid could not be set up, or a drawing failed, and the error says nothing itself (one that says something shows its own words) | Mermaid failed to initialize globally. / An unknown error occurred while rendering the diagram. | `en` |
|
|
1304
|
+
| `emptyDrawing` | The reason when Mermaid answers an empty drawing | Failed to render Mermaid diagram: SVG content is empty or invalid. | `en` |
|
|
1096
1305
|
|
|
1097
1306
|
The spreadsheet keys of `SpreadsheetBlockLabels`, all optional (the viewer's key for each is `spreadsheet` followed by the
|
|
1098
1307
|
key with a capital first letter: `zoomIn` is `spreadsheetZoomIn`). A block takes its built-in texts from the catalog its
|
|
1099
1308
|
locale picks, `SPREADSHEET_BLOCK_LABEL_CATALOGS.en` or `.ja` (each text marked with its own language); a text you pass
|
|
1100
|
-
replaces the entry of every locale and
|
|
1309
|
+
replaces the entry of every locale and carries `labelsLang` (without it, no language of its own). A text written as a template fills its `{name}`
|
|
1101
1310
|
placeholders, which `SPREADSHEET_BLOCK_LABEL_PLACEHOLDERS` lists per key; a replacement uses the same names, and a
|
|
1102
1311
|
placeholder without a value stays as written, so a misspelt one shows rather than vanishing.
|
|
1103
1312
|
|
|
@@ -1155,12 +1364,13 @@ The viewer's `blockFailed` (the renderer's `blockFailedLabel`; built in: "This b
|
|
|
1155
1364
|
|
|
1156
1365
|
`@aiquants/markdown/code-blocks` holds the code-block contract without loading React: `CODE_META_ATTRIBUTE`
|
|
1157
1366
|
(`data-code-meta`, the attribute the converter writes on a fenced block's `code` for the info string after the language,
|
|
1158
|
-
read as text only), `
|
|
1367
|
+
read as text only), `OPEN_CODE_ATTRIBUTE` (`data-open-code`, written empty on the `pre` of a code block that runs to
|
|
1368
|
+
the end of the text when a conversion asks for streaming hints), `SPREADSHEETS_LANGUAGE`, `parseSpreadsheetOptions` (the one reader of a table's options; an invalid
|
|
1159
1369
|
word throws `SpreadsheetOptionsError`, a `RangeError` whose `word` names it), `SPREADSHEET_OPTION_RULES` (each option's
|
|
1160
1370
|
field, range, the only values it takes inside the range — `steps`, `null` for any — and value when absent),
|
|
1161
1371
|
`SPREADSHEET_ZOOM_STEP_PERCENTS` (the percents `zoom=` takes: the grid's zoom steps as the toolbar shows them) and the
|
|
1162
1372
|
limits `DEFAULT_SPREADSHEET_VISIBLE_ROWS` (15), `MAX_SPREADSHEET_VISIBLE_ROWS` (1000), `MAX_SPREADSHEET_FROZEN_TRACKS`
|
|
1163
|
-
(128) and `MAX_SPREADSHEET_FRAME_WIDTH_PX` (3). A host's own sanitizer keeps `data-code-meta` on `code` with
|
|
1373
|
+
(128) and `MAX_SPREADSHEET_FRAME_WIDTH_PX` (3). A host's own sanitizer keeps `data-code-meta` on `code` and `data-open-code` on `pre` with these names.
|
|
1164
1374
|
It also holds the table block's label catalogs (`SPREADSHEET_BLOCK_LABEL_CATALOGS`) and the placeholders each label's
|
|
1165
1375
|
text takes (`SPREADSHEET_BLOCK_LABEL_PLACEHOLDERS`), so a host can derive its own label keys and texts from them.
|
|
1166
1376
|
|
|
@@ -1187,10 +1397,11 @@ converter built to WebAssembly, on hundreds of generated layouts and bodies.
|
|
|
1187
1397
|
import { CODE_META_ATTRIBUTE, parseSpreadsheetOptions, planFencedBodyEdit } from "@aiquants/markdown/code-blocks"
|
|
1188
1398
|
```
|
|
1189
1399
|
|
|
1190
|
-
`@aiquants/markdown/viewer-settings` exports the built-in document styles and the
|
|
1400
|
+
`@aiquants/markdown/viewer-settings` exports the built-in document styles, the alignments, the measures and the colour pairs without loading React, for modules that also run on the server (configuration, validation): `DEFAULT_MARKDOWN_STYLES`, `DEFAULT_MARKDOWN_STYLE` (`"Zenn"`, the name of the built-in style a host starts a reader on when neither the host nor the reader chose one;
|
|
1401
|
+
the viewer itself always shows the `style` it is given), `MarkdownStyleOption`, `ContentAlign`, `CONTENT_ALIGNS`, `DEFAULT_CONTENT_ALIGN`, `toContentAlign`, `ContentMeasure`, `CONTENT_MEASURES`, `DEFAULT_CONTENT_MEASURE` (`"fill"`), `toContentMeasure`, `ContentColors`, `CONTENT_COLORS`, `DEFAULT_CONTENT_COLORS` (`"default"`) and `toContentColors`. Each `to…` turns a value read from outside (a URL query, a stored preference) into a valid one, the default or a fallback you pass when it is not. `@aiquants/markdown` re-exports the same values.
|
|
1191
1402
|
|
|
1192
1403
|
```ts
|
|
1193
|
-
import { DEFAULT_MARKDOWN_STYLE, DEFAULT_MARKDOWN_STYLES, toContentAlign } from "@aiquants/markdown/viewer-settings"
|
|
1404
|
+
import { DEFAULT_MARKDOWN_STYLE, DEFAULT_MARKDOWN_STYLES, toContentAlign, toContentColors, toContentMeasure } from "@aiquants/markdown/viewer-settings"
|
|
1194
1405
|
```
|
|
1195
1406
|
|
|
1196
1407
|
## Extended Syntax
|