@aiquants/markdown 12.3.0 → 13.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +551 -76
- 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 +36 -3
- package/dist/components/MarkdownViewer.d.ts +11 -2
- package/dist/components/MermaidDiagram.d.ts +21 -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/blockNotice.d.ts +15 -0
- 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/fileSave.d.ts +1 -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/mermaidAccessibility.d.ts +11 -0
- package/dist/components/mermaidExport.d.ts +24 -0
- package/dist/components/mermaidLabels.d.ts +89 -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/spreadsheetClipboard.d.ts +1 -1
- package/dist/components/spreadsheetModel.d.ts +1 -0
- package/dist/components/svgRaster.d.ts +2 -2
- package/dist/components/viewerLabels.d.ts +13 -3
- 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-BfYlTVvN.js +6773 -0
- package/dist/extractHeadings-CZPJi4gM.cjs +12 -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 +6 -3
- package/dist/index.client.js +54 -46
- package/dist/index.js +54 -46
- 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/browserPaintView.d.ts +3 -0
- package/dist/mermaidFrame/cssCleaner.d.ts +29 -0
- package/dist/mermaidFrame/diagramPalette.d.ts +24 -0
- package/dist/mermaidFrame/diagramTheme.d.ts +7 -0
- package/dist/mermaidFrame/drawableTypes.d.ts +6 -0
- package/dist/mermaidFrame/drawer.d.ts +47 -0
- package/dist/mermaidFrame/frame.d.ts +1 -0
- package/dist/mermaidFrame/frame.js +3308 -0
- package/dist/mermaidFrame/insertion.d.ts +11 -0
- package/dist/mermaidFrame/katexInert.d.ts +4 -0
- package/dist/mermaidFrame/namespaces.d.ts +3 -0
- package/dist/mermaidFrame/paintCheck.d.ts +2 -0
- package/dist/mermaidFrame/paintContract.d.ts +3 -0
- package/dist/mermaidFrame/paintDiagram.d.ts +3 -0
- package/dist/mermaidFrame/paintMap.d.ts +103 -0
- package/dist/mermaidFrame/paintRules.d.ts +18 -0
- package/dist/mermaidFrame/protocol.d.ts +43 -0
- package/dist/mermaidFrame/serve.d.ts +19 -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 +31 -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
|
|
@@ -545,8 +694,10 @@ as written.
|
|
|
545
694
|
4096 × 4096 pixels of area and 32,767 pixels a side, and hands the clipboard the PNG as an `image/png`
|
|
546
695
|
`ClipboardItem` within the press, so a browser that only writes during a press (Safari) takes it too. The SVG is
|
|
547
696
|
drawn from a blob URL of the page's own origin, so the canvas stays readable whatever origin the image comes from,
|
|
548
|
-
and, as the image itself, loads nothing outside the file
|
|
549
|
-
|
|
697
|
+
and, as the image itself, loads nothing outside the file; a page whose content security policy limits `img-src`
|
|
698
|
+
(or, without one, `default-src`) must therefore list `blob:` there, or the browser refuses the blob URL. A file the
|
|
699
|
+
host cut, a read that fails, or a file the browser cannot draw copies nothing and says it could not copy, as does a
|
|
700
|
+
browser without `ClipboardItem`.
|
|
550
701
|
- With the whole source shown (`copy`, its outcomes `copied` and `copyFailed`) it writes the text exactly as read. A
|
|
551
702
|
source the host cut never offers Copy, so the clipboard never gets part of a file.
|
|
552
703
|
- Each press of Copy stops the copy before it, and leaving the block stops the one under way, so only the latest press
|
|
@@ -580,22 +731,62 @@ as written.
|
|
|
580
731
|
|
|
581
732
|
Every top-level block renders inside its own error boundary. A block whose rendering throws in the browser — a host's
|
|
582
733
|
`linkComponent` that fails, a component's bug — shows a short notice in its place (`[data-aqmd-block-failure]`: the
|
|
583
|
-
label `blockFailed`, the renderer's `blockFailedLabel`, above the block's text in a `<
|
|
584
|
-
|
|
734
|
+
label `blockFailed`, the renderer's `blockFailedLabel`, above the block's text in a `<code>` inside a `<pre>`, which a
|
|
735
|
+
display style colours as its code blocks and which wraps every line; the built-in English notice
|
|
736
|
+
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
737
|
caught one (the root's `onCaughtError`, the console by default). The block renders again as soon as its content
|
|
586
|
-
changes.
|
|
738
|
+
changes. Every text of the notice, the block's text among them, reaches 7:1 or more on the ground under it in the
|
|
739
|
+
None, GitHub and Zenn styles and both schemes, under every colour pair and without one. React's server rendering
|
|
740
|
+
does not stop at error boundaries, so such a block still fails a server render.
|
|
741
|
+
|
|
742
|
+
### Text that grows
|
|
743
|
+
|
|
744
|
+
A host that renders a text while it is still being written (a model's answer as it streams) converts each state of the
|
|
745
|
+
text with `includeStreamingHints` and passes the result's `blockOffsets` along with its HTML:
|
|
746
|
+
|
|
747
|
+
```tsx
|
|
748
|
+
// result: one conversion of the text so far, with includeStreamingHints: true
|
|
749
|
+
<MarkdownRenderer
|
|
750
|
+
htmlContent={result.htmlContent}
|
|
751
|
+
blockOffsets={result.blockOffsets}
|
|
752
|
+
streaming={!finished} // the stream still writes the text
|
|
753
|
+
truncated={finished && cutOff} // the text stopped before its end
|
|
754
|
+
blockKeyEpoch={attempt} // changes when the text is replaced rather than extended
|
|
755
|
+
/>
|
|
756
|
+
```
|
|
757
|
+
|
|
758
|
+
- **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).
|
|
759
|
+
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.
|
|
760
|
+
- **Stable props**: the kept blocks are dropped whenever another prop that shapes the elements changes (the theme, labels, components, readers, the drawing place of the diagrams), 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.
|
|
761
|
+
- **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.
|
|
762
|
+
- **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.
|
|
763
|
+
- **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.
|
|
764
|
+
- **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 or diagram.
|
|
765
|
+
- **Open diagrams**: while `streaming` is true, a Mermaid diagram the converter marked open is not drawn (Mermaid is not loaded for it) and shows its text under the `openStreaming` reason; it is drawn once the mark goes or `streaming` turns false (see **Held diagrams** in [Mermaid diagrams](#mermaid-diagrams)).
|
|
766
|
+
A text that stopped before its end (a stream that broke off, an answer cut at its length limit) takes `truncated`: a diagram marked open then shows its text under `openCut` instead of being drawn from a text whose closing line never came, while a code block so marked is highlighted. With neither, the text counts as complete and a diagram marked open is drawn as it stands. A change of `truncated` too renders again only the blocks that hold a marked code block or diagram.
|
|
767
|
+
- **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, `streaming` or `truncated` true without `blockOffsets`, and both true together throw a `RangeError`.
|
|
587
768
|
|
|
588
769
|
### Mermaid diagrams
|
|
589
770
|
|
|
590
771
|
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
|
-
|
|
772
|
+
Unless a host has the diagram drawn in a drawing place (see [Drawing place](#drawing-place)), 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
773
|
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
774
|
|
|
775
|
+
- **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.
|
|
776
|
+
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.
|
|
777
|
+
A failed setup (a library without `initialize`, or an `initialize` that throws) is shared by every later diagram for the page's life.
|
|
594
778
|
- 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
779
|
- 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
780
|
- 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.
|
|
597
781
|
- When the width of a slot showing a gantt chart changes (a splitter drag, a window resize), the chart is drawn again at the new width 200 ms after the last change, unless the slot then has no width or the width of the latest drawing. The shown chart stays until the new one replaces it, and the new one starts at the initial zoom and pan. Other diagram types take their size from their text and are never drawn again for a width change.
|
|
598
782
|
- A drawing that finishes after a newer one was requested, after the diagram's text changed or after the component unmounted is discarded.
|
|
783
|
+
- **Errors**: a diagram that cannot be shown shows in its place (`[data-aqmd-mermaid-error]`) `errorPrefix` and the reason, below them the diagram's text without its leading and trailing white space, as plain text in a `<code>` inside a `<pre>` (`[data-aqmd-mermaid-source]`, as wide as the box), and below that the retry button, which draws the diagram again.
|
|
784
|
+
A display style colours the text as its code blocks (Zenn's grounds every `<pre>` dark in both schemes and colours only the `<code>` in it), and every line wraps to the box's width, so the text never scrolls sideways and the error adds no control to reach.
|
|
785
|
+
- **Held diagrams**: a host holds a diagram back with `held` (`MermaidHeld`): `{ kind: "streaming" }` while a stream still writes its text, `{ kind: "cut" }` when the text stopped before its closing line, or `{ kind: "too-many-diagrams", limit }` past the document's limit of diagrams.
|
|
786
|
+
A held diagram is not drawn, in the page or in a drawing place alike (Mermaid is not loaded for it and the drawing place is not asked), and shows in its place (`[data-aqmd-mermaid-held]`, whose value is the kind) the hold's reason (`openStreaming`, `openCut`, or `tooManyDiagrams` with its `{limit}` filled) above the diagram's text, which shows as in the error, without `errorPrefix` and the retry button; once the hold goes the diagram is drawn.
|
|
787
|
+
The box takes the controls' border, surface and text, whose text reaches 7:1 on the surface in both schemes, as a hold is no error.
|
|
788
|
+
`MarkdownRenderer` holds its diagrams itself from `streaming`, `truncated` and `maxMermaidDiagrams`: the diagrams count in document order, a held one as well as a drawn one, and each past `maxMermaidDiagrams` (a positive safe integer) is held with the limit whatever mark it has, on either path; a block holding a diagram renders again when the diagrams before it changed, and a change of the limit drops the kept blocks. `MarkdownViewer` and `NodesRenderer` hold no diagram.
|
|
789
|
+
A hold that is not an object throws a `TypeError`, and one of another kind or with a limit that is not a positive safe integer a `RangeError`, as does a `maxMermaidDiagrams` that is not a positive safe integer.
|
|
599
790
|
- **Touch and pen**: the default mode, `both-shift`, is the same for every pointer, and Shift gates only the mouse. A finger or pen pans the drawing only while the drawing overflows its frame (zoomed in, or capped, see below); at fit it scrolls the page over the diagram as anywhere else. The component writes `touch-action` on the diagram's `<svg>` and on its frame to match, rewrites it whenever the zoom or pan changes, the mode changes or the frame resizes, and removes it (with the other styles Panzoom wrote) when it tears its Panzoom instance down:
|
|
600
791
|
|
|
601
792
|
| Mode | Drawing fits its frame | Drawing overflows its frame |
|
|
@@ -605,7 +796,8 @@ Mermaid draws in that element and the component shows the result in the slot, so
|
|
|
605
796
|
| `pan`, `pan-shift` | `auto` | `pinch-zoom` |
|
|
606
797
|
| `both`, `both-shift` | `pan-x pan-y` | `none` |
|
|
607
798
|
|
|
608
|
-
- **Frame and clipping**: the shown drawing sits in a frame, `[data-aqmd-mermaid-frame]` (it also keeps `data-testid="mermaid-diagram"`), that clips it with `overflow: clip` from the components' stylesheet (the component writes no inline `overflow`), and the `<svg>` is a block
|
|
799
|
+
- **Frame and clipping**: the shown drawing sits in a frame, `[data-aqmd-mermaid-frame]` (it also keeps `data-testid="mermaid-diagram"`), that clips it with `overflow: clip` and contains its paint with `contain: paint`, both from the components' stylesheet (the component writes no inline `overflow`), and the `<svg>` is a block (the frame's `<svg>` child, or for a drawing place's copy the part `drawing`, see **Insertion** below).
|
|
800
|
+
A zoomed drawing therefore never widens the frame or scrolls the document sideways, and the paint containment, which makes the frame the containing block of the drawing's positioned elements, clips even one positioned `fixed`, which overflow clipping alone leaves to the viewport (a diagram drawn in the page can position its own root `fixed` through Mermaid's `themeCSS`, and the transform of the zoom holds only the root's descendants). `data-aqmd-mermaid-overflowing` is `"true"` while the drawing overflows the frame and `"false"` otherwise.
|
|
609
801
|
- **Zoom bounds**: the zoom runs from the drawing as laid out in the frame (1×) to 200 % of the diagram's natural size (WCAG 1.4.4), the width at which one unit of the drawing is one CSS px, read from the drawing itself: the width of its `viewBox`, which the browser scales to the drawing's box; a drawing without a `viewBox` (Mermaid's `info`) is never scaled, so its layout is its natural size and it zooms up to 2×.
|
|
610
802
|
The fit is the drawing's laid-out width over its natural width, so the bound holds wherever the drawing is laid out (full screen lays a tall drawing out narrower than its frame). Only a drawing whose `viewBox` has no usable size (not four numbers with a positive width and height) shows an error and a retry button in its place.
|
|
611
803
|
A drawing of 1993.6 px natural width laid out 372 px wide zooms up to 10.72×; a diagram that already fits zooms up to 2×. The view is clamped on each axis like a scroll container: a drawing larger than the frame keeps covering it, a smaller one stays inside.
|
|
@@ -613,16 +805,208 @@ Mermaid draws in that element and the component shows the result in the slot, so
|
|
|
613
805
|
While a finger or pen pans or pinches the drawing, the frame cancels the default action of its `touchmove` events, so the browser starts no momentum scroll and the next tap on a control is never spent stopping one. That non-passive listener is bound only while the drawing overflows its frame: over a fitting diagram a finger scrolls without the browser waiting for the page's script.
|
|
614
806
|
- **Keyboard**: the frame takes focus (`tabindex="0"`, `role="group"`) and is named by the `diagram` label, which a hidden element carries with its own `lang`, so the drawing's text is not marked with it. On the frame itself, not on a link inside it and not with Ctrl, Meta or Alt held, the arrow keys pan the view by 25.9 % of the frame (only when the view can move; otherwise the page scrolls), `+` and `=` zoom in, `-` zooms out and `0` resets.
|
|
615
807
|
When an element inside the drawing takes the focus (a node's link, by Tab), the view pans by the least distance that brings the element's box inside the frame, because the clipping frame is no scroll container the browser could scroll to it.
|
|
808
|
+
- **Screen readers**: a diagram whose text gives it a title (`accTitle`) names the frame, the toolbar and the block's dialog by that title ahead of their own label (`diagram`, or `fullscreenDialog` for the dialog in full screen), so the label's key hints stay in the name, and one with a description (`accDescr`) gives the frame that description (`aria-describedby`).
|
|
809
|
+
Both are read from the shown drawing, in the page and in a drawing place alike: the text of the elements inside the drawing that its root names in `aria-labelledby` and `aria-describedby`, which Mermaid writes from them, with each run of white space collapsed. Hidden elements carry them without a `lang`, so they take the document's language.
|
|
810
|
+
The drawing's root keeps the role Mermaid gives it (`graphics-document document`), and its role description, which Mermaid writes as the type's code (`aria-roledescription="flowchart-v2"`), is the type's name from the `type…` labels instead (see [Labels and languages](#labels-and-languages)), rewritten in place when the labels change. A type without a label (one a later Mermaid adds) has no role description, so its code is never read out.
|
|
811
|
+
The drawing place's real-browser check (`check:mermaid-frame-browser`) checks through the component in Chromium, Firefox and WebKit, on both paths, that the frame, the toolbar and the dialog point at the title and the frame at the description, and that the root of every sample it draws takes its type's name, and reads the frame's computed name and description and the root's role description from Chromium's accessibility tree.
|
|
616
812
|
- **Pan buttons**: four buttons (`pan-left`, `pan-up`, `pan-down`, `pan-right`) lead the toolbar and are shown only while the drawing overflows its frame, so panning never needs a drag (WCAG 2.5.7); at fit they keep their slots hidden (`visibility: hidden`: not focusable, not exposed), so zooming never adds a toolbar row or moves the frame; each moves the view by the same step as the arrow keys.
|
|
617
813
|
- **Sizes**: under every pointer (a mouse, a pen or a finger) every control is 44 × 44 px and each menu item and the retry button at least 44 px tall (WCAG 2.2 enhanced target size). The toolbar is a wrapping row above the frame, aligned to the row's end, so the controls never cover the drawing.
|
|
618
|
-
The pan buttons come first in it, so the controls always shown (the mode menu, zoom in, zoom out, reset and the full-screen toggle) stay at the row's end while the hidden pan buttons keep their slots.
|
|
619
|
-
The pan buttons and the mode menu with the zoom and reset buttons are two groups that each wrap as a whole, followed by the full-screen toggle, so a narrow column puts each group on a row of its own instead of dropping one of a group's controls to the next row.
|
|
814
|
+
The pan buttons come first in it, so the controls always shown (the mode menu, zoom in, zoom out, reset, the Source toggle and the full-screen toggle) stay at the row's end while the hidden pan buttons keep their slots.
|
|
815
|
+
The pan buttons and the mode menu with the zoom and reset buttons are two groups that each wrap as a whole, followed by the Source toggle's group (with the Export menu and Copy diagram before the toggle while they show, see **Export** below, and Copy while the text shows) and the full-screen toggle, so a narrow column puts each group on a row of its own instead of dropping one of a group's controls to the next row.
|
|
620
816
|
The menu opens below its button within the toolbar's row and the viewport: at the button's start edge, else at its end edge, else moved inside the row as near the button as it allows and narrowed to the row when the row is narrower (`data-aqmd-control-menu`: `start`, `end` or `inside`), so it stays over the diagram.
|
|
621
|
-
- **Full screen**: the toolbar's last control shows the diagram over the whole window while it shows a drawing (see [Full screen](#full-screen)). The frame fills the free space below the toolbar without the coarse pointer's cap, and the drawing fits it whole in its natural shape, never past its natural width, at the frame's centre; the view (zoom and pan, kept within the bounds of the new layout) carries across. A diagram that starts loading again or
|
|
817
|
+
- **Full screen**: the toolbar's last control shows the diagram over the whole window while it shows a drawing (see [Full screen](#full-screen)). The frame fills the free space below the toolbar without the coarse pointer's cap, and the drawing fits it whole in its natural shape, never past its natural width, at the frame's centre; the view (zoom and pan, kept within the bounds of the new layout) carries across. A diagram that starts loading again, fails or is held back leaves full screen with its toolbar.
|
|
818
|
+
- **Source**: the Source toggle (`source`, with `aria-pressed`), between the drawing's controls and the full-screen toggle, shows the diagram's text without its leading and trailing white space in place of the drawing, in a `<pre>` (`[data-aqmd-mermaid-source]`, the text in its `<code>`, so a display style colours it as its code blocks) that takes the focus (`role="region"`, named by the `sourceRegion` label after the drawing's title when it has one) and scrolls. It wraps the text as written, is no taller than `--aqmd-viewport-cap` and fills the window below the toolbar in full screen.
|
|
819
|
+
The frame is hidden, not removed (`hidden`), so a second press shows the drawing with the view it had; meanwhile the drawing's controls (pan, mode, zoom and reset) leave the toolbar while their groups keep their slots, the Export menu and Copy diagram (see **Export** below) leave the toggle's group, the pressed toggle keeps the focus, and the arrow keys walk Copy, the toggle and the full-screen toggle. The root's `data-aqmd-mermaid-view` is `"diagram"` or `"source"` while a drawing shows, and absent otherwise.
|
|
820
|
+
While the text shows, a Copy button (`copy-source`) comes before the toggle: it writes the text to the clipboard, and the status line (`[data-aqmd-mermaid-notice]`, `role="status"`, empty until it tells something) tells `copiedSource` or `copySourceFailed` (a window without the asynchronous clipboard fails); only the latest press tells its outcome, and closing the text clears the line.
|
|
821
|
+
The choice is not remembered: each diagram opens with its drawing, keeps the choice while it is drawn again (a gantt chart that follows the slot's width is drawn in the hidden frame), and comes back to it after a failure or a hold once it is drawn.
|
|
822
|
+
- **Export**: a host whose diagrams a drawing place draws (see [Drawing place](#drawing-place)) lets a reader keep a diagram as an image file by passing a way to export it: `exporting` (`MermaidExporting`) on `MermaidDiagram`, or `mermaidExporting` (`MermaidDocumentExporting`) on `MarkdownRenderer`, which gives each diagram it renders its number in the document (`index`, from 1, a held diagram counting as well).
|
|
823
|
+
The way's `fileName` names one diagram's file from a `MermaidDiagramFile`: `index`, `accTitle` (the drawing's title, as it names the frame, or `null`) and `format` (`"svg"` or `"png"`); `pngScale`, a positive finite number, multiplies the export drawing's own size for the PNG, which is then scaled down in proportion to the largest canvas every browser draws (4096 × 4096 pixels, and at most 32,767 on a side).
|
|
824
|
+
While a drawing shows (not while it loads, after a failure, while it is held, for a diagram of white space alone, nor while the text shows), the Source toggle's group holds before the toggle the Export menu (`export`, named by `exportMenu`) and Copy diagram (`copy-diagram`): the menu holds Save as SVG (`save-svg`) and Save as PNG (`save-png`), and Copy as SVG (`copy-svg`) only in a browser whose `ClipboardItem.supports` says yes to `image/svg+xml`.
|
|
825
|
+
Each asks the drawer for the export form of the shown drawing (see **Export form** under [Drawing place](#drawing-place)): the request the drawing was drawn with, in the light scheme whatever `theme` says, so every file keeps the light ground. The SVG file is the finished export drawing's markup (`image/svg+xml`), and the PNG that drawing drawn as above.
|
|
826
|
+
The PNG is drawn from a blob URL of the page, as an SVG image's copy is (see [SVG images](#svg-images)), so a page whose content security policy limits `img-src` (or, without one, `default-src`) must list `blob:` there: without it Save as PNG and Copy diagram fail (`saveFailed`, `copyDiagramFailed`), while Save as SVG and Copy as SVG, which draw no image, still save and copy.
|
|
827
|
+
Copy diagram (a PNG) and Copy as SVG write one clipboard item within the press, before the drawer answers (Safari refuses a write begun after the press), holding the image and the diagram's text without its leading and trailing white space (`text/plain`); a window without the asynchronous clipboard (`navigator.clipboard.write` and `ClipboardItem`) fails the copy without asking the drawer.
|
|
828
|
+
A save calls `fileName` first: a name that is not a non-empty string, or a `fileName` that throws, fails the save without asking the drawer (a file without a name would take one the browser makes from its URL); the file then goes to the browser's download under that name, through a hidden link with `download` whose object URL is released on the next task.
|
|
829
|
+
The status line tells `copiedDiagram`, `saveStarted` (with `{name}`, the file's name) or, when the drawing place refuses to export the drawing, the notice of its reason with nothing on the console: `notExportableHtmlLabel` (a label Mermaid draws only as HTML), `notExportableUnsized` (a root without a usable `viewBox`) or `notExportableUnlikeText` (the export drawing's text differs from the shown drawing's), so a reader always learns that the diagram was not exported, and why.
|
|
830
|
+
A refusal for a reason the package does not know (as a host's own drawer may answer) and any other failure tell `copyDiagramFailed` or `saveFailed` and leave the error, or the name `fileName` answered, on the console. Only the latest press tells its outcome, and a later press or the diagram's removal stops a save whose file is not made yet.
|
|
831
|
+
`exporting` without `drawing`, and `mermaidExporting` without `mermaidDrawing` whatever the document holds, throw a `RangeError` during render, as do a `pngScale` that is not a positive finite number and an `index` that is not a positive safe integer; a way that is not an object, or whose `fileName` is not a function, throws a `TypeError`.
|
|
832
|
+
`MarkdownRenderer` hands its diagrams one stand-in of the way: it calls the `fileName` of the last committed render, and a way the host builds anew with the same `pngScale` on every render (an object and a closure, as while a stream writes the document) keeps the blocks it kept (see [Text that grows](#text-that-grows)), while a new `pngScale` drops them as its other props that shape the elements do.
|
|
833
|
+
The drawing place's real-browser check (`check:mermaid-frame-browser`) checks the export in Chromium, Firefox and WebKit: every sample it compares by pixel, and a flowchart whose labels break their lines with `<br>` alone, draws in the export form, in both schemes, with its labels as SVG text, the shown drawing's characters, its own size and its ground under everything,
|
|
834
|
+
except those the drawing place refuses as Mermaid 11.16.0 draws them, each for its reason (an event model's labels, drawn only as HTML, for `html-label`; the info diagram, whose root has no `viewBox`, for `unsized`; and the flowchart sample, whose bold, table, list and Font Awesome icon the export form writes out as characters, for `unlike-text`);
|
|
835
|
+
the package's PNGs of each take that size, show the ground wherever the drawing leaves the image clear, away from the edges of what it paints, and paint the text colour where the texts lie.
|
|
836
|
+
Through the component it checks that Save as SVG and Save as PNG download their files under the name `fileName` gives, that Copy diagram puts the PNG and the text on Chromium's clipboard, and that on a page whose policy limits `img-src` without `blob:` Save as PNG and Copy diagram fail while Save as SVG and Copy as SVG still save and copy.
|
|
622
837
|
- **Tall diagrams**: under a coarse pointer the frame is at most `calc(100svh - 2 * 2.75rem)` tall, so two 44 px bands of the page stay outside it wherever it sits and a finger can scroll the page past the diagram; the clipped drawing then overflows and pans by finger.
|
|
623
838
|
- **Touch menu**: under a coarse pointer the menu button is named by `interactionModeTouch` and the menu lists four items, `none`, `zoom`, `pan` and `both`, worded for touch (see [Labels and languages](#labels-and-languages)); the checked item is the touch counterpart of the mode in force (`pan-shift` shows `pan`, `both-shift` shows `both`), and choosing an item sets that mode. Escape closes a menu and returns the focus to its button.
|
|
624
|
-
- **Colours and focus ring**: the controls, the menu items, the checked item, the error message
|
|
625
|
-
|
|
839
|
+
- **Colours and focus ring**: the controls, the menu items, the checked item, the error message (with the diagram's text below it, which a display style colours as its code blocks: the None, GitHub and Zenn styles keep it at 7:1 too, under every colour pair and without one) and the retry button reach 7:1 against their surfaces in both schemes (dark when `.dark` or `[data-theme="dark"]` is on an ancestor).
|
|
840
|
+
The focus ring of the frame, the toolbar controls, the source region 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.
|
|
841
|
+
- **Hooks**: `data-aqmd-mermaid` (the root, which carries the palette's CSS variables, `data-aqmd-mermaid-view` while a drawing shows, 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`, `export`, `copy-diagram`, `copy-source`, `source` or `fullscreen`), `data-aqmd-mermaid-menu`, `data-aqmd-mermaid-error`, `data-aqmd-mermaid-held`,
|
|
842
|
+
`data-aqmd-mermaid-export-menu` (the Export menu), `data-aqmd-mermaid-export-item` (`save-svg`, `save-png` or `copy-svg`), `data-aqmd-mermaid-source` (the text of an error, a hold or the source view), `data-aqmd-mermaid-notice` and `data-aqmd-mermaid-retry`.
|
|
843
|
+
The component writes the drawing's natural aspect ratio on its `<svg>` as `--aqmd-mermaid-ratio`, which the full-screen layout reads.
|
|
844
|
+
|
|
845
|
+
#### Drawing place
|
|
846
|
+
|
|
847
|
+
`@aiquants/markdown/mermaid-frame` (`dist/mermaidFrame/frame.js`, with the licenses of the code inside it in `NOTICES.md`
|
|
848
|
+
beside it) is the script of a drawing place: one self-contained file, Mermaid without KaTeX, that a frame document loads
|
|
849
|
+
as a module script to draw the diagrams sent to it over a message port, with every key of Mermaid's configuration
|
|
850
|
+
locked: every top-level key of its type and the name of every key at every level of its default configuration, so
|
|
851
|
+
nothing a diagram writes (its `%%{init}%%` and `%%{wrap}%%` directives, its front matter's `config`) changes how it is
|
|
852
|
+
drawn, wherever it writes a key. A text Mermaid draws only as its error picture (the bare word `error`) fails as Mermaid's failure, as no
|
|
853
|
+
diagram, so the page shows it as it shows every text that is no diagram, and a diagram of a type the drawing place does
|
|
854
|
+
not draw fails, unpainted, as a type it does not draw (see **Types** in [Mermaid diagrams](#mermaid-diagrams)). It draws in the package's diagram palette for the request's colour scheme rather than Mermaid's: every colour
|
|
855
|
+
variable of Mermaid's `base` theme takes a role of the palette (the ground, the text, four surfaces, the line, 12 series
|
|
856
|
+
colours and the text on a series), as do the colours of C4's shapes, sankey's links and journey's first 12 actors, and
|
|
857
|
+
xychart and sankey label their values. In the frame, what Mermaid draws is then repainted in that palette, reading the
|
|
858
|
+
frame's browser for what lies under what: a palette colour keeps its place, any other fill or line moves to the palette
|
|
859
|
+
colour nearest it in OKLab of its kind (a grey to a neutral role, a hue to a coloured one) among those its use allows,
|
|
860
|
+
and a translucent fill is not painted and a translucent line is made opaque. Every line narrower than 1 CSS px at the
|
|
861
|
+
size the frame draws it is widened to 1 CSS px (a marker's content at the scale of the lines it sits on): a thinner one
|
|
862
|
+
only shows as pixels it covers less than half of, paler than its paint. A line of the ground's colour stays only as the
|
|
863
|
+
gap outlining an opaque fill, and otherwise moves to the nearest colour of its kind that stands out 3:1 on the ground
|
|
864
|
+
and on every surface. Every line and every marker's content then takes the first of its paint and the text on a series
|
|
865
|
+
that reaches 3:1 on everything under it, passing over what bears its paint (its own shape, a gap). Where neither does
|
|
866
|
+
and the line lies only on fills it does not stand out on, those fills move to the nearest ground or surface of their
|
|
867
|
+
kind and the lines are decided again; a line other than a marker's content that still has neither but stands out on the
|
|
868
|
+
ground gets a casing of the ground 1 px wider on each side, laid just before it. The pie's outer ring is not drawn.
|
|
869
|
+
Every text takes the first text role that reaches 7:1 on everything under it, read down the middle of each character and
|
|
870
|
+
on both sides of every edge that crosses it, on a backing of the ground where none does or where it lies on a picture
|
|
871
|
+
(behind an SVG text, 1 CSS px wider on each side than its box, so the edges of its glyphs stay on the backing), and a
|
|
872
|
+
decoration line is drawn in its element's text colour, or, for an element holding no text of its own, in the colour of
|
|
873
|
+
the first text inside it (an SVG group around the HTML of a `foreignObject` among them). A
|
|
874
|
+
text that a later shape paints over, down the middle of a character or where its glyphs sit (a thin line between two
|
|
875
|
+
characters), is moved above it first, and gradients (as their first stop's colour), filters, patterns, opacity, blend
|
|
876
|
+
modes, shadows and the colours of the diagram's sheets are removed. The repainted drawing holds
|
|
877
|
+
its paints only in `style` attributes (`fill`, `stroke`, `color` and `background-color`, each a palette colour, `none`
|
|
878
|
+
or `transparent`, and `text-decoration` with its line and style only), and no colour, translucency or effect in a sheet
|
|
879
|
+
or a presentation attribute. A drawing that cannot be repainted fails as the drawing place's own failure.
|
|
880
|
+
|
|
881
|
+
A host has the components draw their diagrams in a drawing place by passing one: `drawing` (`MermaidDrawing`) on
|
|
882
|
+
`MermaidDiagram`, or `mermaidDrawing` on `MarkdownRenderer`, which passes it with its own `theme` to every diagram it
|
|
883
|
+
renders. A `MermaidDrawing` holds the drawer, which `createMermaidDrawer` returns (or a host's function that hands each
|
|
884
|
+
request on to one), and the two limits every request carries, each a positive safe integer: `maxChars`, the most UTF-16
|
|
885
|
+
code units of a diagram's text, and `maxEdges`, the most edges of a flowchart. Without a drawing place a diagram is drawn
|
|
886
|
+
in the page as above, and nothing loads the drawing place's script.
|
|
887
|
+
|
|
888
|
+
```tsx
|
|
889
|
+
import frameScriptUrl from "@aiquants/markdown/mermaid-frame?url" // with Vite: the URL the bundler emits for the script
|
|
890
|
+
import { createMermaidDrawer, MarkdownRenderer, type MermaidDrawing } from "@aiquants/markdown"
|
|
891
|
+
|
|
892
|
+
// One drawer for the page, made in the browser: createMermaidDrawer throws outside a window
|
|
893
|
+
let pageDrawing: MermaidDrawing | undefined
|
|
894
|
+
const drawingOfPage = (): MermaidDrawing => {
|
|
895
|
+
pageDrawing ??= {
|
|
896
|
+
// fontStylesheetUrls: the stylesheets that declare the page's web fonts, if it uses any
|
|
897
|
+
drawer: createMermaidDrawer({ frameScriptUrl, fontStylesheetUrls: [] }),
|
|
898
|
+
maxChars: 50_000,
|
|
899
|
+
maxEdges: 500,
|
|
900
|
+
}
|
|
901
|
+
return pageDrawing
|
|
902
|
+
}
|
|
903
|
+
|
|
904
|
+
// In a component rendered in the browser
|
|
905
|
+
<MarkdownRenderer htmlContent={htmlContent} theme="dark" mermaidDrawing={drawingOfPage()} />
|
|
906
|
+
```
|
|
907
|
+
|
|
908
|
+
- **The drawer**: `createMermaidDrawer({ frameScriptUrl, fontStylesheetUrls })` makes the function that draws one
|
|
909
|
+
diagram (`MermaidDrawer`); make one per page, in the browser (outside a window it throws a `TypeError`).
|
|
910
|
+
`frameScriptUrl` is the URL of `@aiquants/markdown/mermaid-frame` as the host's bundler emits it, and
|
|
911
|
+
`fontStylesheetUrls` lists the stylesheets that declare the faces of the fonts the page's slots use (empty when the
|
|
912
|
+
page uses no web font), so the frame measures each label in the face the page shows it in. Each must be an `https:`
|
|
913
|
+
or `http:` URL of the page's origin, since the frame's content security policy takes scripts, stylesheets and fonts
|
|
914
|
+
from that origin only: one that is empty or does not parse throws a `TypeError`, and any other a `RangeError`, as
|
|
915
|
+
does a page whose origin has an IPv6 address, which no content security policy takes as a source. The font files the
|
|
916
|
+
sheets name must be of the page's origin too: the drawer does not read the sheets, the frame's policy refuses a font
|
|
917
|
+
file of any other origin, and Mermaid then measures the labels in the next font of the family rather than in the face
|
|
918
|
+
the page shows them in (the frame logs the face that did not load to the console).
|
|
919
|
+
- **The frame**: the drawer makes its frame at the first diagram, a `srcdoc` frame of the page's origin under its own
|
|
920
|
+
content security policy (scripts, stylesheets and fonts of the page's origin, inline styles and `data:` images,
|
|
921
|
+
nothing else), out of sight, focus and the accessibility tree, and draws the diagrams there one at a time in the order
|
|
922
|
+
they were requested. The frame also runs under the page's own policy, so its script must be one the page's
|
|
923
|
+
`script-src` takes: a page whose policy names no `script-src` (only `base-uri`, `object-src`, `frame-src` and
|
|
924
|
+
`frame-ancestors`, say) draws, and neither `frame-src` nor `frame-ancestors` refuses the frame, while on a page whose
|
|
925
|
+
`script-src` takes only a nonce the script never runs and every diagram fails as the drawing place's failure.
|
|
926
|
+
The frame's styles come under the page's policy too, as do those of the copies the page shows (Mermaid writes
|
|
927
|
+
`<style>` elements and `style` attributes, and the cleaning keeps the ones it allows), so the page's `style-src` (or,
|
|
928
|
+
without one, its `default-src`) must take `'unsafe-inline'`: on a page whose policy does not, the frame measures the
|
|
929
|
+
labels in other boxes, the copies lose their styles and show other pixels, and a drawing whose painting falls off the
|
|
930
|
+
diagram palette without them fails as the drawing place's failure.
|
|
931
|
+
A frame that loads without listening (its script did not load or threw) fails the diagrams sent to it and is removed;
|
|
932
|
+
one that loads again (moved in the page) fails the diagrams it held and is connected anew; one that leaves the page
|
|
933
|
+
(removed, or the body replaced) fails them at once, and one that left unseen (the root element replaced) at the next
|
|
934
|
+
diagram. The next diagram makes a new frame, and a diagram already shown stays, as it is a copy in the page.
|
|
935
|
+
- **Requests**: each drawing requests the diagram's text without its leading and trailing white space, `theme`
|
|
936
|
+
(`"light"` by default; unread without a drawing place), the shown form (`form: "shown"`; see **Export form** below),
|
|
937
|
+
the slot's width, the measuring element's computed `font-family`, the `lang` written on the slot or its nearest
|
|
938
|
+
ancestor that has one, as written and also across a shadow root to its host (empty when none has), and the two limits.
|
|
939
|
+
The page's Mermaid is neither imported nor set up for such a diagram, and its drawings take none of the lane, the
|
|
940
|
+
drawing hosts and the retry by itself above. It still waits for its slot's width, and a gantt chart, which the
|
|
941
|
+
`aria-roledescription` of the cleaned drawing's root names (the shown copy's root takes the type's name instead), is
|
|
942
|
+
drawn again when that width changes.
|
|
943
|
+
- **Insertion**: each insertion shows its own copy of the cleaned drawing, imported into the page's document: every id
|
|
944
|
+
of the copy takes the insertion's prefix (`aqmd-mmd-`, 16 random hexadecimal digits and `-`) and every reference
|
|
945
|
+
follows it, so no two insertions share a name, nor an insertion and the page, and a reference to an id the diagram
|
|
946
|
+
does not hold is dropped. The page keeps the ids that start with `aqmd-mmd-` for these copies: a host gives no id and
|
|
947
|
+
no id prefix of its own that start with it. Every class of the drawing starts with `aqmd-mmd-` too, so no class rule
|
|
948
|
+
of the page styles it. The copy sits in the open shadow root of the frame's only child, `[data-aqmd-mermaid-drawing]`
|
|
949
|
+
(a new one for each insertion, which pan and zoom move), so no rule of the page reaches it either, not even one for
|
|
950
|
+
the elements of a label's HTML, such as a display style's margins of a table or a list, which would make the label
|
|
951
|
+
overflow the box the drawing place measured; only inherited properties pass in. The page reaches the copy's `<svg>`
|
|
952
|
+
through its part names: `drawing`, and also `scalable` when it has a `viewBox`
|
|
953
|
+
(`[data-aqmd-mermaid-drawing]::part(drawing)`); nothing inside the copy has a part name. The frame shows the copy on
|
|
954
|
+
the diagram palette's ground of the scheme the drawing was painted for, whatever the page's scheme, so every text and
|
|
955
|
+
line stands on the ground its contrast was reached on (a diagram drawn in the page keeps the frame's white ground,
|
|
956
|
+
light grey under a dark ancestor).
|
|
957
|
+
- **Types**: the drawing place draws the types of diagram in `MERMAID_DRAWABLE_TYPES` (with its type
|
|
958
|
+
`MermaidDrawableType`): each entry holds Mermaid's name of the type (`type`, as Mermaid's detection and the drawn
|
|
959
|
+
root's `aria-roledescription` give it) and the word a writer writes first on the diagram's first line to draw it
|
|
960
|
+
(`header`), in the order Mermaid registers and tries its detectors; the list and its entries are frozen. It holds every
|
|
961
|
+
type Mermaid 11.16.0 registers that the drawing place's configuration reaches but four: `flowchart-elk`, which needs a
|
|
962
|
+
layout loader the drawing place does not register, and three that leave a value or a name nowhere but in a colour,
|
|
963
|
+
`treemap` (it hides the names and values of cells too small to hold them), `radar` (its series differ only in colour)
|
|
964
|
+
and `journey` (its actors on each task differ only in colour). The drawing place refuses a diagram of any other type
|
|
965
|
+
once Mermaid has drawn it, by Mermaid's own detection, as `{ kind: "unlisted-type", type }` with Mermaid's name of the
|
|
966
|
+
type, before painting it; a diagram drawn in the page, without `drawing`, draws every type the page's Mermaid draws.
|
|
967
|
+
A host can tell its writers by the headers which types its diagrams may take.
|
|
968
|
+
- **Failures**: a diagram the drawing place did not draw shows why (see **Errors** above): a text over `maxChars` shows
|
|
969
|
+
`tooLarge` and a flowchart over `maxEdges` shows `tooManyEdges`, each filled with the failure's numbers, and a diagram
|
|
970
|
+
of a type the drawing place does not draw shows `unlistedType` (see
|
|
971
|
+
[Labels and languages](#labels-and-languages)); Mermaid's refusal, the drawing place's own failure and a refusal to
|
|
972
|
+
export (which the drawer gives only to the export form, though a host's drawer may give it to any request) show their
|
|
973
|
+
words (`renderFailed` when they say nothing); a drawer that rejects the request (a `TypeError` or a `RangeError` for
|
|
974
|
+
an invalid one, such as a limit that is not a positive safe integer) or throws shows the error's words; and an answer
|
|
975
|
+
that holds no cleaned drawing shows `renderFailed`. The retry button asks the drawer again. An answer or a refusal
|
|
976
|
+
that arrives after a newer drawing was requested, after the text, `drawing` or `theme` changed or after the component
|
|
977
|
+
unmounted is discarded.
|
|
978
|
+
- **Changes**: the fields of `drawing` and `theme` take effect each on its own, so a `MermaidDrawing` made anew with
|
|
979
|
+
the same fields on every render draws nothing again, and a change of any of them draws the diagram again; a `drawer`
|
|
980
|
+
that is not a function throws a `TypeError` during render. `MarkdownRenderer` takes `mermaidDrawing` as it takes its
|
|
981
|
+
other props that shape the elements (see [Text that grows](#text-that-grows)): a new value drops the blocks it kept,
|
|
982
|
+
so pass a stable one.
|
|
983
|
+
- **Export form**: a host that keeps a diagram as an image file asks its drawer for the export form (`form: "export"`),
|
|
984
|
+
in either scheme and with the other fields as above; the components ask for the shown form to show a diagram, and
|
|
985
|
+
for the export form in the light scheme when a reader exports it (see **Export** in
|
|
986
|
+
[Mermaid diagrams](#mermaid-diagrams)), and any other `form` is a `RangeError`.
|
|
987
|
+
The drawing place then draws every label Mermaid can as SVG text, with `htmlLabels` off at the top
|
|
988
|
+
level and for flowcharts, which no diagram turns back on, as not every reader of an image file draws the HTML of a
|
|
989
|
+
`foreignObject`. The answer goes through the cleaning and the palette check of a shown one and is then finished as an
|
|
990
|
+
image file keeps it: the root's `width` and `height` become the width and the height of its `viewBox` and its style
|
|
991
|
+
loses `max-width`, so the file has a size of its own rather than the slot's (`width="100%"`), and a rectangle of the
|
|
992
|
+
diagram palette's ground for the scheme, covering the `viewBox`, is laid under everything the diagram draws, after the
|
|
993
|
+
root's leading `<title>` and `<desc>`, so the image keeps the ground its contrast was reached on. A drawing that still
|
|
994
|
+
holds a `foreignObject` (a label Mermaid draws only as HTML) or whose root has no `viewBox` of a positive width and
|
|
995
|
+
height fails as not exportable (`{ kind: "not-exportable", reason, message }`, a `MermaidDrawFailure` whose `reason`,
|
|
996
|
+
a `MermaidNotExportableReason`, is `"html-label"` or `"unsized"`), and one whose painting falls off the palette fails
|
|
997
|
+
first as the drawing place's failure, as in the shown form; either failure is the outcome at once. Otherwise the
|
|
998
|
+
drawer compares the export drawing with the same request drawn in the shown form, which it asks for right after the
|
|
999
|
+
export form and before any later request (an export request costs the frame two drawings): the characters of each,
|
|
1000
|
+
their text and CDATA outside `style`, `title` and `desc` (of an SVG `switch`, only those of its first element child,
|
|
1001
|
+
the one it draws, so a label written twice, as HTML and as a `text` to fall back on, counts once) with white
|
|
1002
|
+
space aside, in sorted order, so neither where a label breaks its lines (`<br>` in the shown form, the lines of a
|
|
1003
|
+
`text` in the export form) nor the order the labels are written in counts. An export whose characters differ, as when a label holds formatting or an icon the export form
|
|
1004
|
+
writes out as characters, fails as not exportable for `"unlike-text"` rather than make a file whose text says
|
|
1005
|
+
something else than the diagram shown, and a failure of the shown drawing is the outcome as it is. A host that tells
|
|
1006
|
+
its readers the outcome can thus always say that a diagram was not exported, and why. The finished drawing holds no
|
|
1007
|
+
font face (the cleaning drops every at-rule), so wherever the image is read or drawn its labels take the faces of
|
|
1008
|
+
their family found there: with web fonts in the slots, the image may show other faces than the frame measured the
|
|
1009
|
+
labels in, and a label may then overflow its box. A host that keeps drawings keys them by the form as well.
|
|
626
1010
|
|
|
627
1011
|
### Spreadsheets
|
|
628
1012
|
|
|
@@ -663,7 +1047,7 @@ Total 17,600 MT
|
|
|
663
1047
|
| `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
1048
|
| `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
1049
|
| `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
|
|
1050
|
+
| `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
1051
|
|
|
668
1052
|
- **Options are strict**: words are `key=value` separated by white space, each key at most once, each value a decimal integer
|
|
669
1053
|
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 +1111,20 @@ Total 17,600 MT
|
|
|
727
1111
|
- **The tap-scroll circle**: `spreadsheetTapScrollCircle` on `MarkdownRenderer` and `MarkdownViewer` gives the tables of a
|
|
728
1112
|
document the look and the speeds of the grid's tap-scroll circle (the grid's `tapScrollCircleOptions`, a
|
|
729
1113
|
`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
|
-
|
|
1114
|
+
document's table shows the circle only when its options say `tapscroll=1`, so the look's `enabled` is not read. The
|
|
1115
|
+
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
|
|
1116
|
+
takes a press anywhere in its square box, only its look being round, so the criterion's 24 × 24 square lies within it.
|
|
1117
|
+
A `size` that is not a whole number or lies under 24 throws a `RangeError` from the render, as a wrong `embeds` does,
|
|
1118
|
+
whatever the document holds. A host
|
|
733
1119
|
that renders `SpreadsheetBlock` itself to show one table (a file preview) passes the circle as `tapScrollCircle`, shown
|
|
734
1120
|
as given (`tapScrollCircleShownBy`, `"host"` by default); `"options"` applies the document's rule (the tables
|
|
735
1121
|
MarkdownRenderer and the mdast path's `CodeNode` draw use it — the mdast path has no prop for the look, so its tables
|
|
736
1122
|
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
|
|
1123
|
+
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
|
|
1124
|
+
block's controls and of the grid's own circle, and that criterion's exceptions do not cover it: it floats over the
|
|
1125
|
+
cells, which are targets themselves, and the table's scroll bars are 12 px, so a host that holds to AAA passes a `size`
|
|
1126
|
+
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
|
|
1127
|
+
and the keys.
|
|
741
1128
|
- **The scroll bars' controls**: `spreadsheetScrollBarControls` on `MarkdownRenderer` and `MarkdownViewer` gives the
|
|
742
1129
|
tables of a document the controls of the grid's scroll bars (the grid's `scrollBarControls`, a
|
|
743
1130
|
`SpreadsheetScrollBarControls` with `showArrowButtons`, `enableThumbDrag` and `enableTrackClick`; the grid's own bars
|
|
@@ -897,7 +1284,7 @@ and the SVG image block. Code blocks, formulas, other images and embeds have non
|
|
|
897
1284
|
|
|
898
1285
|
### Viewer toolbar
|
|
899
1286
|
|
|
900
|
-
`MarkdownViewer` shows its alignment,
|
|
1287
|
+
`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
1288
|
|
|
902
1289
|
| Property | Effect |
|
|
903
1290
|
| --- | --- |
|
|
@@ -917,11 +1304,14 @@ A viewer inside a containing block of its own (an element with `contain: layout
|
|
|
917
1304
|
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
1305
|
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
1306
|
|
|
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.
|
|
1307
|
+
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.
|
|
1308
|
+
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.
|
|
1309
|
+
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
1310
|
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
1311
|
|
|
923
1312
|
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).
|
|
1313
|
+
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).
|
|
1314
|
+
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
1315
|
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
1316
|
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
1317
|
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 +1330,7 @@ The bound is the popover's border box (the popover is `box-sizing: border-box` w
|
|
|
940
1330
|
|
|
941
1331
|
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
1332
|
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
|
|
1333
|
+
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
1334
|
|
|
945
1335
|
### Host scroll bar
|
|
946
1336
|
|
|
@@ -973,7 +1363,8 @@ The viewer adds the lane to the container's inline-end padding, outside `padding
|
|
|
973
1363
|
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
1364
|
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
1365
|
|
|
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`;
|
|
1366
|
+
- **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`;
|
|
1367
|
+
a percentage is no lane, since the lane is a length.
|
|
977
1368
|
- **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
1369
|
|
|
979
1370
|
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 +1466,30 @@ const headingHref: MarkdownHeadingHrefResolver = (heading) => `/docs/guide.md#${
|
|
|
1075
1466
|
|
|
1076
1467
|
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
1468
|
(`MarkdownRenderer` takes them as `svgImageLabels`, `codeBlockLabels` and `displayMathLabels`; `CodeNode` takes `CodeBlockLabels` as `labels`).
|
|
1078
|
-
|
|
1079
|
-
A
|
|
1469
|
+
`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`.
|
|
1470
|
+
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.
|
|
1471
|
+
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
1472
|
`DEFAULT_MARKDOWN_EMBED_LABELS`, `DEFAULT_SVG_IMAGE_LABELS`, `DEFAULT_CODE_BLOCK_LABELS` and `DEFAULT_DISPLAY_MATH_LABELS` hold the built-in texts.
|
|
1081
1473
|
|
|
1082
|
-
|
|
1474
|
+
`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.
|
|
1475
|
+
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).
|
|
1476
|
+
|
|
1477
|
+
The display popover's keys of `MarkdownViewerLabels`, all optional and all marked `lang="en"` when built in:
|
|
1478
|
+
|
|
1479
|
+
| Key | Names | Built-in text |
|
|
1480
|
+
| --- | --- | --- |
|
|
1481
|
+
| `styleTitle` | The popover's heading | Display |
|
|
1482
|
+
| `selectStyleAria` | The display button | Display options |
|
|
1483
|
+
| `pinStyleAria`, `unpinStyleAria` | The pin button | Pin display options / Unpin display options |
|
|
1484
|
+
| `styleSectionTitle`, `measureTitle`, `colorsTitle` | The sections' headings | Style / Width / Colors |
|
|
1485
|
+
| `measureFill`, `measureReading` | The width options | Full width / Reading width |
|
|
1486
|
+
| `colorsDefault`, `colorsSepia`, `colorsDarkLowGlare`, `colorsHighContrast` | The colour options | Document colors / Sepia / Dark, low glare / High contrast |
|
|
1487
|
+
|
|
1488
|
+
`missingImage` is the notice of an image that cannot be found (`missingImageLabel` on `MarkdownRenderer`; "Image not found", marked `lang="en"`).
|
|
1489
|
+
|
|
1490
|
+
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'; `tooLarge`, `tooManyEdges` and `unlistedType`, which only a diagram drawn in a drawing place shows, have no viewer key, as the viewer draws its diagrams in the page, and neither have the twelve labels of the export (`exportMenu` to `notExportableUnlikeText` in the table), for the same reason;
|
|
1491
|
+
nor have `openStreaming`, `openCut` and `tooManyDiagrams`, which only a held diagram shows, as the viewer holds none).
|
|
1492
|
+
A text written as a template fills its `{name}` placeholders with the failure's numbers, the hold's limit, or the saved file's name; a replacement uses the same names, and a placeholder without a value stays as written:
|
|
1083
1493
|
|
|
1084
1494
|
| Key | Names | Built-in text | `lang` |
|
|
1085
1495
|
| --- | --- | --- | --- |
|
|
@@ -1092,12 +1502,75 @@ The Mermaid keys of `MermaidDiagramLabels`, all optional (the viewer's key for e
|
|
|
1092
1502
|
| `fullscreen`, `exitFullscreen` | The full-screen toggle, by the way it goes | View full screen / Exit full screen | `en` |
|
|
1093
1503
|
| `fullscreenDialog` | The block's dialog while full screen | Diagram (full screen) | `en` |
|
|
1094
1504
|
| `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` |
|
|
1505
|
+
| `source` | The Source toggle, which shows the diagram's text in place of the drawing and back | Source | `en` |
|
|
1506
|
+
| `sourceRegion` | The focusable region that shows the text, after the drawing's title when it has one | Diagram source | `en` |
|
|
1507
|
+
| `copySource` | The Copy button, shown while the text shows | Copy the source | `en` |
|
|
1508
|
+
| `copiedSource`, `copySourceFailed` | The status line's notice once the text is copied, or when it could not be | Copied the source. / Could not copy the source. | `en` |
|
|
1509
|
+
| `exportMenu` | The Export menu's button, shown while a drawing shows that the host exports (`exporting`) | Export | `en` |
|
|
1510
|
+
| `saveSvg`, `savePng`, `copySvg` | The Export menu's items (`copySvg` only where the clipboard takes SVG) | Save as SVG / Save as PNG / Copy as SVG | `en` |
|
|
1511
|
+
| `copyDiagram` | The Copy diagram button after the Export menu, which copies the drawing as a PNG with the diagram's text | Copy the diagram | `en` |
|
|
1512
|
+
| `copiedDiagram`, `copyDiagramFailed` | The status line's notice once the diagram is copied, or when it could not be | Copied the diagram. / Could not copy the diagram. | `en` |
|
|
1513
|
+
| `saveStarted`, `saveFailed` | The status line's notice once the file's download starts (`{name}`, the file's name), or when the file could not be saved | Started saving {name}. / Could not save the diagram. | `en` |
|
|
1514
|
+
| `notExportableHtmlLabel` | The status line's notice when the drawing place refuses to export the drawing because a label Mermaid draws only as HTML would be missing from the image (`html-label`) | This diagram cannot be copied or saved as an image: some of its labels are drawn as HTML, which not every image viewer shows. | `en` |
|
|
1515
|
+
| `notExportableUnsized` | The status line's notice when the drawing place refuses to export the drawing because its root has no usable `viewBox` to take the image's size from (`unsized`) | This diagram cannot be copied or saved as an image: it has no size of its own to draw the image at. | `en` |
|
|
1516
|
+
| `notExportableUnlikeText` | The status line's notice when the drawing place refuses to export the drawing because its text would differ from the shown diagram's (`unlike-text`) | This diagram cannot be copied or saved as an image: the image's text would differ from the diagram shown, as when a label holds formatting or an icon. | `en` |
|
|
1095
1517
|
| `retry` | The retry button after a failed drawing | 再試行 | `ja` |
|
|
1518
|
+
| `loading` | The notice while a diagram is drawn | Loading diagram... | `en` |
|
|
1519
|
+
| `errorPrefix` | The text in front of the reason a diagram could not be drawn | Error: | `en` |
|
|
1520
|
+
| `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` |
|
|
1521
|
+
| `emptyDrawing` | The reason when Mermaid answers an empty drawing | Failed to render Mermaid diagram: SVG content is empty or invalid. | `en` |
|
|
1522
|
+
| `tooLarge` | The reason when a diagram's text is longer than the drawing place's `maxChars` (`{length}`, the text's UTF-16 length, and `{limit}`) | The diagram's source is too long ({length} characters; the limit is {limit}). | `en` |
|
|
1523
|
+
| `tooManyEdges` | The reason when a flowchart has more edges than the drawing place's `maxEdges` (`{limit}`) | The diagram has too many edges (the limit is {limit}). | `en` |
|
|
1524
|
+
| `unlistedType` | The reason when the drawing place does not draw the diagram's type (not one of `MERMAID_DRAWABLE_TYPES`; no placeholder) | The diagram is not drawn: its type is not one of the types drawn here. | `en` |
|
|
1525
|
+
| `openStreaming` | The reason of a diagram held while a stream still writes its text (`MarkdownRenderer`'s `streaming`) | The diagram is drawn once its text is complete. | `en` |
|
|
1526
|
+
| `openCut` | The reason of a diagram held because the text stopped before its closing line (`MarkdownRenderer`'s `truncated`) | The diagram is not drawn: the text was cut off before its closing line. | `en` |
|
|
1527
|
+
| `tooManyDiagrams` | The reason of a diagram held past the document's limit (`MarkdownRenderer`'s `maxMermaidDiagrams`; `{limit}`) | The diagram is not drawn: the document draws only its first {limit} diagrams. | `en` |
|
|
1528
|
+
| `typeC4` … `typeRailroad` (the table below) | The role description of a drawn diagram's root, by the diagram's type | C4 diagram … Railroad diagram | `en` |
|
|
1529
|
+
|
|
1530
|
+
The type names (`type…`) name the types Mermaid 11.16 detects, as below (38 types under 31 names); a type
|
|
1531
|
+
without a name has no role description. A drawn diagram's root takes the name as its role description
|
|
1532
|
+
(`aria-roledescription`), an attribute that cannot carry a language of its own: a screen reader reads it in the
|
|
1533
|
+
language the diagram inherits (the document's), whatever the name's built-in `lang`, so a host passes the type names
|
|
1534
|
+
in the document's language.
|
|
1535
|
+
|
|
1536
|
+
| Key | Mermaid's types | Built-in text |
|
|
1537
|
+
| --- | --- | --- |
|
|
1538
|
+
| `typeC4` | `c4` | C4 diagram |
|
|
1539
|
+
| `typeFlowchart` | `flowchart`, `flowchart-v2`, `flowchart-elk` | Flowchart |
|
|
1540
|
+
| `typeSwimlane` | `swimlane` | Swimlane diagram |
|
|
1541
|
+
| `typeEntityRelationship` | `er` | Entity relationship diagram |
|
|
1542
|
+
| `typeGitGraph` | `gitGraph` | Git graph |
|
|
1543
|
+
| `typeGantt` | `gantt` | Gantt chart |
|
|
1544
|
+
| `typeInfo` | `info` | Mermaid information |
|
|
1545
|
+
| `typePie` | `pie` | Pie chart |
|
|
1546
|
+
| `typeQuadrantChart` | `quadrantChart` | Quadrant chart |
|
|
1547
|
+
| `typeXyChart` | `xychart` | XY chart |
|
|
1548
|
+
| `typeRequirement` | `requirement` | Requirement diagram |
|
|
1549
|
+
| `typeSequence` | `sequence` | Sequence diagram |
|
|
1550
|
+
| `typeClass` | `class`, `classDiagram` | Class diagram |
|
|
1551
|
+
| `typeState` | `state`, `stateDiagram` | State diagram |
|
|
1552
|
+
| `typeJourney` | `journey` | User journey |
|
|
1553
|
+
| `typeTimeline` | `timeline` | Timeline |
|
|
1554
|
+
| `typeMindmap` | `mindmap` | Mind map |
|
|
1555
|
+
| `typeKanban` | `kanban` | Kanban board |
|
|
1556
|
+
| `typeSankey` | `sankey` | Sankey diagram |
|
|
1557
|
+
| `typePacket` | `packet` | Packet diagram |
|
|
1558
|
+
| `typeRadar` | `radar` | Radar chart |
|
|
1559
|
+
| `typeBlock` | `block` | Block diagram |
|
|
1560
|
+
| `typeTreeView` | `treeView` | Tree view |
|
|
1561
|
+
| `typeArchitecture` | `architecture` | Architecture diagram |
|
|
1562
|
+
| `typeEventModeling` | `eventmodeling` | Event modeling diagram |
|
|
1563
|
+
| `typeIshikawa` | `ishikawa` | Ishikawa diagram |
|
|
1564
|
+
| `typeVenn` | `venn` | Venn diagram |
|
|
1565
|
+
| `typeTreemap` | `treemap` | Treemap |
|
|
1566
|
+
| `typeWardley` | `wardley` | Wardley map |
|
|
1567
|
+
| `typeCynefin` | `cynefin` | Cynefin diagram |
|
|
1568
|
+
| `typeRailroad` | `railroad`, `railroadEbnf`, `railroadAbnf`, `railroadPeg` | Railroad diagram |
|
|
1096
1569
|
|
|
1097
1570
|
The spreadsheet keys of `SpreadsheetBlockLabels`, all optional (the viewer's key for each is `spreadsheet` followed by the
|
|
1098
1571
|
key with a capital first letter: `zoomIn` is `spreadsheetZoomIn`). A block takes its built-in texts from the catalog its
|
|
1099
1572
|
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
|
|
1573
|
+
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
1574
|
placeholders, which `SPREADSHEET_BLOCK_LABEL_PLACEHOLDERS` lists per key; a replacement uses the same names, and a
|
|
1102
1575
|
placeholder without a value stays as written, so a misspelt one shows rather than vanishing.
|
|
1103
1576
|
|
|
@@ -1155,12 +1628,13 @@ The viewer's `blockFailed` (the renderer's `blockFailedLabel`; built in: "This b
|
|
|
1155
1628
|
|
|
1156
1629
|
`@aiquants/markdown/code-blocks` holds the code-block contract without loading React: `CODE_META_ATTRIBUTE`
|
|
1157
1630
|
(`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), `
|
|
1631
|
+
read as text only), `OPEN_CODE_ATTRIBUTE` (`data-open-code`, written empty on the `pre` of a code block that runs to
|
|
1632
|
+
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
1633
|
word throws `SpreadsheetOptionsError`, a `RangeError` whose `word` names it), `SPREADSHEET_OPTION_RULES` (each option's
|
|
1160
1634
|
field, range, the only values it takes inside the range — `steps`, `null` for any — and value when absent),
|
|
1161
1635
|
`SPREADSHEET_ZOOM_STEP_PERCENTS` (the percents `zoom=` takes: the grid's zoom steps as the toolbar shows them) and the
|
|
1162
1636
|
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
|
|
1637
|
+
(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
1638
|
It also holds the table block's label catalogs (`SPREADSHEET_BLOCK_LABEL_CATALOGS`) and the placeholders each label's
|
|
1165
1639
|
text takes (`SPREADSHEET_BLOCK_LABEL_PLACEHOLDERS`), so a host can derive its own label keys and texts from them.
|
|
1166
1640
|
|
|
@@ -1187,10 +1661,11 @@ converter built to WebAssembly, on hundreds of generated layouts and bodies.
|
|
|
1187
1661
|
import { CODE_META_ATTRIBUTE, parseSpreadsheetOptions, planFencedBodyEdit } from "@aiquants/markdown/code-blocks"
|
|
1188
1662
|
```
|
|
1189
1663
|
|
|
1190
|
-
`@aiquants/markdown/viewer-settings` exports the built-in document styles and the
|
|
1664
|
+
`@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;
|
|
1665
|
+
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
1666
|
|
|
1192
1667
|
```ts
|
|
1193
|
-
import { DEFAULT_MARKDOWN_STYLE, DEFAULT_MARKDOWN_STYLES, toContentAlign } from "@aiquants/markdown/viewer-settings"
|
|
1668
|
+
import { DEFAULT_MARKDOWN_STYLE, DEFAULT_MARKDOWN_STYLES, toContentAlign, toContentColors, toContentMeasure } from "@aiquants/markdown/viewer-settings"
|
|
1194
1669
|
```
|
|
1195
1670
|
|
|
1196
1671
|
## Extended Syntax
|