product-doc 0.0.0-stage → 0.13.2
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/LICENSE +21 -0
- package/README.md +566 -2
- package/bin.js +6 -0
- package/guide.md +251 -0
- package/lib/annotations.d.ts +44 -0
- package/lib/annotations.js +65 -0
- package/lib/changes.d.ts +96 -0
- package/lib/changes.js +111 -0
- package/lib/cli.d.ts +1 -0
- package/lib/cli.js +217 -0
- package/lib/codeNotes.d.ts +38 -0
- package/lib/codeNotes.js +113 -0
- package/lib/definitions.d.ts +23 -0
- package/lib/definitions.js +298 -0
- package/lib/diagramAnnotations.d.ts +7 -0
- package/lib/diagramAnnotations.js +27 -0
- package/lib/errors.d.ts +44 -0
- package/lib/errors.js +71 -0
- package/lib/extractDocument.d.ts +3 -0
- package/lib/extractDocument.js +22 -0
- package/lib/gist/route.d.ts +26 -0
- package/lib/gist/route.js +124 -0
- package/lib/git.d.ts +33 -0
- package/lib/git.js +474 -0
- package/lib/github/route.d.ts +28 -0
- package/lib/github/route.js +128 -0
- package/lib/index.d.ts +10 -0
- package/lib/index.js +7 -0
- package/lib/invokeCwd.d.ts +1 -0
- package/lib/invokeCwd.js +9 -0
- package/lib/media.d.ts +5 -0
- package/lib/media.js +9 -0
- package/lib/mermaid.d.ts +6 -0
- package/lib/mermaid.js +20 -0
- package/lib/mermaidTheme.d.ts +17 -0
- package/lib/mermaidTheme.js +28 -0
- package/lib/packageVersion.d.ts +1 -0
- package/lib/packageVersion.js +3 -0
- package/lib/parseFence.d.ts +76 -0
- package/lib/parseFence.js +137 -0
- package/lib/parseViewer.d.ts +74 -0
- package/lib/parseViewer.js +490 -0
- package/lib/readSpec.d.ts +25 -0
- package/lib/readSpec.js +62 -0
- package/lib/registry.d.ts +11 -0
- package/lib/registry.js +82 -0
- package/lib/serve.d.ts +70 -0
- package/lib/serve.js +756 -0
- package/lib/services.d.ts +107 -0
- package/lib/services.js +310 -0
- package/lib/share.d.ts +15 -0
- package/lib/share.js +153 -0
- package/lib/spec.d.ts +39 -0
- package/lib/spec.js +95 -0
- package/lib/telemetry.d.ts +6 -0
- package/lib/telemetry.js +109 -0
- package/lib/update.d.ts +43 -0
- package/lib/update.js +237 -0
- package/package.json +79 -4
- package/viewer-dist/assets/abap-CLvhMVsD.js +1 -0
- package/viewer-dist/assets/actionscript-3-Cs6JJXT5.js +1 -0
- package/viewer-dist/assets/ada-X3Y2mlq2.js +1 -0
- package/viewer-dist/assets/ahk-DwADkxyd.js +1 -0
- package/viewer-dist/assets/ahk2-_6rzW9BS.js +1 -0
- package/viewer-dist/assets/andromeeda-BJLMrMlp.js +1 -0
- package/viewer-dist/assets/andromeeda-vGVdxbeo.js +1 -0
- package/viewer-dist/assets/angular-html-BswFT_28.js +1 -0
- package/viewer-dist/assets/angular-html-Cwa-lTMy.js +1 -0
- package/viewer-dist/assets/angular-ts-DOMhGxLQ.js +1 -0
- package/viewer-dist/assets/apache-U0d_L8uA.js +1 -0
- package/viewer-dist/assets/apex-KFGFyKwG.js +1 -0
- package/viewer-dist/assets/apl-Dio8Ke0X.js +1 -0
- package/viewer-dist/assets/appendItems-BRdTC5zu.js +3 -0
- package/viewer-dist/assets/applescript-CCn79oCD.js +1 -0
- package/viewer-dist/assets/ara-4CJ0cIlV.js +1 -0
- package/viewer-dist/assets/asciidoc-SCjQUq34.js +1 -0
- package/viewer-dist/assets/asm-Cmm7eHzH.js +1 -0
- package/viewer-dist/assets/astro-CN6YWUG3.js +1 -0
- package/viewer-dist/assets/aurora-x-BCChoRpm.js +1 -0
- package/viewer-dist/assets/aurora-x-CDeNXAV0.js +1 -0
- package/viewer-dist/assets/awk-BWXHIvNe.js +1 -0
- package/viewer-dist/assets/ayu-dark-DluEY0Gj.js +1 -0
- package/viewer-dist/assets/ayu-dark-DzFZPuMV.js +1 -0
- package/viewer-dist/assets/ayu-light-C3h-C4tm.js +1 -0
- package/viewer-dist/assets/ayu-light-DSkcX_XD.js +1 -0
- package/viewer-dist/assets/ayu-mirage-Bqwy1Gya.js +1 -0
- package/viewer-dist/assets/ayu-mirage-DSve0zuE.js +1 -0
- package/viewer-dist/assets/ballerina-B7ZEbQpA.js +1 -0
- package/viewer-dist/assets/bat-Di-EdOIU.js +1 -0
- package/viewer-dist/assets/bat-HFWzIrao.js +1 -0
- package/viewer-dist/assets/beancount-C2IN4Vk8.js +1 -0
- package/viewer-dist/assets/berry-DKpUyyne.js +1 -0
- package/viewer-dist/assets/bibtex-CimSBJhw.js +1 -0
- package/viewer-dist/assets/bibtex-Conh3HYz.js +1 -0
- package/viewer-dist/assets/bicep-CUHmPFLl.js +1 -0
- package/viewer-dist/assets/bird2-CYIUgYqB.js +1 -0
- package/viewer-dist/assets/blade-BrDpNfUX.js +1 -0
- package/viewer-dist/assets/bsl-gRq8cI6V.js +1 -0
- package/viewer-dist/assets/c-DWGmR78Y.js +1 -0
- package/viewer-dist/assets/c-SSSlmE39.js +1 -0
- package/viewer-dist/assets/c3-D0apG41V.js +1 -0
- package/viewer-dist/assets/cadence-CQ2zXKGN.js +1 -0
- package/viewer-dist/assets/cairo-D66nqRlU.js +1 -0
- package/viewer-dist/assets/catppuccin-frappe-C9Q5zVZY.js +1 -0
- package/viewer-dist/assets/catppuccin-frappe-DbLkF0J2.js +1 -0
- package/viewer-dist/assets/catppuccin-latte-CtsyrtPq.js +1 -0
- package/viewer-dist/assets/catppuccin-latte-b6208YQK.js +1 -0
- package/viewer-dist/assets/catppuccin-macchiato-CNNBbV1L.js +1 -0
- package/viewer-dist/assets/catppuccin-macchiato-R8nAf1vR.js +1 -0
- package/viewer-dist/assets/catppuccin-mocha-DHkNF0Mp.js +1 -0
- package/viewer-dist/assets/catppuccin-mocha-DjuaAJKi.js +1 -0
- package/viewer-dist/assets/chapel-C1sUNn9S.js +1 -0
- package/viewer-dist/assets/clarity-CtfBBspg.js +1 -0
- package/viewer-dist/assets/clojure-BrC3BItl.js +1 -0
- package/viewer-dist/assets/clojure-zIjcJonk.js +1 -0
- package/viewer-dist/assets/cmake-BRht3inD.js +1 -0
- package/viewer-dist/assets/cmake-T_kMSWuN.js +1 -0
- package/viewer-dist/assets/cobol-BvqUwMCV.js +1 -0
- package/viewer-dist/assets/codeowners-C8r90Shi.js +1 -0
- package/viewer-dist/assets/codeql-oeQT6MSM.js +1 -0
- package/viewer-dist/assets/coffee-BSYIIMkB.js +1 -0
- package/viewer-dist/assets/coffee-drHG6SJT.js +1 -0
- package/viewer-dist/assets/commit-mono-latin-400-italic-BXinMwCi.woff +0 -0
- package/viewer-dist/assets/commit-mono-latin-400-italic-DjSHLl2N.woff2 +0 -0
- package/viewer-dist/assets/commit-mono-latin-400-normal-s0S3qwFW.woff +0 -0
- package/viewer-dist/assets/commit-mono-latin-400-normal-wzhe4RuD.woff2 +0 -0
- package/viewer-dist/assets/common-lisp-Cv5bFMCO.js +1 -0
- package/viewer-dist/assets/constants-CmGPilXJ.js +1 -0
- package/viewer-dist/assets/coq-CGaSfhwR.js +1 -0
- package/viewer-dist/assets/core-A38CGsfQ.js +4 -0
- package/viewer-dist/assets/core-B86SFyc0.js +1 -0
- package/viewer-dist/assets/cpp-BDT6bThX.js +1 -0
- package/viewer-dist/assets/cpp-CcLCVKG_.js +1 -0
- package/viewer-dist/assets/crystal-D0XIDmeW.js +1 -0
- package/viewer-dist/assets/csharp-B3DbjJyj.js +1 -0
- package/viewer-dist/assets/csharp-DtuFCOLR.js +1 -0
- package/viewer-dist/assets/css-BGIxQoYs.js +1 -0
- package/viewer-dist/assets/css-DUjzNfgv.js +1 -0
- package/viewer-dist/assets/csv-B_R7vXwK.js +1 -0
- package/viewer-dist/assets/csv-D6mwZ2PH.js +1 -0
- package/viewer-dist/assets/cue-CE9AQfxI.js +1 -0
- package/viewer-dist/assets/cypher-ClKdZ_lG.js +1 -0
- package/viewer-dist/assets/d-qD-0Kul2.js +1 -0
- package/viewer-dist/assets/dark-plus-BVZ_4wTZ.js +1 -0
- package/viewer-dist/assets/dark-plus-Cs2F2srj.js +1 -0
- package/viewer-dist/assets/dart-B8JJT_EX.js +1 -0
- package/viewer-dist/assets/dart-_dH3dQdM.js +1 -0
- package/viewer-dist/assets/dax-BkyTk9wS.js +1 -0
- package/viewer-dist/assets/desktop-Dlh5hvp9.js +1 -0
- package/viewer-dist/assets/diff-B0S3HUPm.js +1 -0
- package/viewer-dist/assets/diff-CR4ZX0DC.js +1 -0
- package/viewer-dist/assets/docker-B3DZKTds.js +1 -0
- package/viewer-dist/assets/docker-CAzcIhYn.js +1 -0
- package/viewer-dist/assets/dotenv-CuH5my32.js +1 -0
- package/viewer-dist/assets/dracula-BHWKrbxM.js +1 -0
- package/viewer-dist/assets/dracula-BoZgXveB.js +1 -0
- package/viewer-dist/assets/dracula-soft-5eyTD99u.js +1 -0
- package/viewer-dist/assets/dracula-soft-D-Kgh5gw.js +1 -0
- package/viewer-dist/assets/dream-maker-DW3nJb8Q.js +1 -0
- package/viewer-dist/assets/edge-B_SBzXGF.js +1 -0
- package/viewer-dist/assets/elixir-B0EKSUNS.js +1 -0
- package/viewer-dist/assets/elixir-BL8v4QDr.js +1 -0
- package/viewer-dist/assets/elk.bundled-CVOErv1M.js +24 -0
- package/viewer-dist/assets/elm-CC1TmzeR.js +1 -0
- package/viewer-dist/assets/emacs-lisp-DR2vtWaj.js +1 -0
- package/viewer-dist/assets/engine-javascript-BopS6peh.js +141 -0
- package/viewer-dist/assets/engine-oniguruma-BO8SA_1o.js +1 -0
- package/viewer-dist/assets/erb-CHbMJpQy.js +1 -0
- package/viewer-dist/assets/erlang-CCXss5H6.js +1 -0
- package/viewer-dist/assets/erlang-DAWODyxE.js +1 -0
- package/viewer-dist/assets/everforest-dark-Y6tr-2zD.js +1 -0
- package/viewer-dist/assets/everforest-dark-sB-x3p7T.js +1 -0
- package/viewer-dist/assets/everforest-light-CA0Ol4Qu.js +1 -0
- package/viewer-dist/assets/everforest-light-Df2xbC6M.js +1 -0
- package/viewer-dist/assets/fennel-DQxkIbk2.js +1 -0
- package/viewer-dist/assets/fish-BJitypiv.js +1 -0
- package/viewer-dist/assets/fluent-C03EYrpw.js +1 -0
- package/viewer-dist/assets/formatCSSVariablePrefix-KRh9vnZf.js +1 -0
- package/viewer-dist/assets/fortran-fixed-form-1cK5gXa1.js +1 -0
- package/viewer-dist/assets/fortran-free-form-9zh5t3u2.js +1 -0
- package/viewer-dist/assets/fortran-free-form-uHOymLAb.js +1 -0
- package/viewer-dist/assets/fsharp-C37UASp4.js +1 -0
- package/viewer-dist/assets/fsharp-D8ZPuVlk.js +1 -0
- package/viewer-dist/assets/gdresource-LxjHb83i.js +1 -0
- package/viewer-dist/assets/gdscript-C2iVvkL_.js +1 -0
- package/viewer-dist/assets/gdscript-DJFPOtzS.js +1 -0
- package/viewer-dist/assets/gdshader-BpaOOKdG.js +1 -0
- package/viewer-dist/assets/gdshader-kiBtQlv1.js +1 -0
- package/viewer-dist/assets/genie-CV2tkWYe.js +1 -0
- package/viewer-dist/assets/gherkin-DExj1W_8.js +1 -0
- package/viewer-dist/assets/git-commit-BAuDFD-1.js +1 -0
- package/viewer-dist/assets/git-commit-rNeRxB9Y.js +1 -0
- package/viewer-dist/assets/git-rebase-Bh7mDoAc.js +1 -0
- package/viewer-dist/assets/git-rebase-Cpv8mbcu.js +1 -0
- package/viewer-dist/assets/github-dark-C-LZuMrd.js +1 -0
- package/viewer-dist/assets/github-dark-C895GGrm.js +1 -0
- package/viewer-dist/assets/github-dark-default-DXG-b-1a.js +1 -0
- package/viewer-dist/assets/github-dark-default-adAWTKmX.js +1 -0
- package/viewer-dist/assets/github-dark-dimmed-Bx1FflLF.js +1 -0
- package/viewer-dist/assets/github-dark-dimmed-jPx1V1fR.js +1 -0
- package/viewer-dist/assets/github-dark-high-contrast-B_tTalzw.js +1 -0
- package/viewer-dist/assets/github-dark-high-contrast-UN5YjL_Z.js +1 -0
- package/viewer-dist/assets/github-light-B4HDwToD.js +1 -0
- package/viewer-dist/assets/github-light-EUqPIrTm.js +1 -0
- package/viewer-dist/assets/github-light-default-BXViO-2h.js +1 -0
- package/viewer-dist/assets/github-light-default-CfC59JYV.js +1 -0
- package/viewer-dist/assets/github-light-high-contrast-B68TUdTA.js +1 -0
- package/viewer-dist/assets/github-light-high-contrast-C3edEHcK.js +1 -0
- package/viewer-dist/assets/gleam-CSRkHgEL.js +1 -0
- package/viewer-dist/assets/glimmer-js-CIdbWayl.js +1 -0
- package/viewer-dist/assets/glimmer-ts-B16xCo2k.js +1 -0
- package/viewer-dist/assets/glsl-CaPTrB3a.js +1 -0
- package/viewer-dist/assets/glsl-ThNHWs2E.js +1 -0
- package/viewer-dist/assets/gn-CAXYAgV-.js +1 -0
- package/viewer-dist/assets/gnuplot-7GGW24-e.js +1 -0
- package/viewer-dist/assets/go-BrE3Phef.js +1 -0
- package/viewer-dist/assets/go-CFMhVTkq.js +1 -0
- package/viewer-dist/assets/graphql-DAzSVzvB.js +1 -0
- package/viewer-dist/assets/graphql-DEIChqxY.js +1 -0
- package/viewer-dist/assets/groovy-D_Q3n-An.js +1 -0
- package/viewer-dist/assets/groovy-Dj7WCBJM.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-hard-BdGOuxq8.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-hard-C820rvS2.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-medium-BPjhmG05.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-medium-CmygtSMi.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-soft-BJH4XuY9.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-soft-MrdJrrXF.js +1 -0
- package/viewer-dist/assets/gruvbox-light-hard-BC_s9l72.js +1 -0
- package/viewer-dist/assets/gruvbox-light-hard-BkSILF4E.js +1 -0
- package/viewer-dist/assets/gruvbox-light-medium-BAWPOn9u.js +1 -0
- package/viewer-dist/assets/gruvbox-light-medium-DiZUfgdz.js +1 -0
- package/viewer-dist/assets/gruvbox-light-soft-BSMLrYjP.js +1 -0
- package/viewer-dist/assets/gruvbox-light-soft-CRCTnbIj.js +1 -0
- package/viewer-dist/assets/hack-C30D-q0p.js +1 -0
- package/viewer-dist/assets/haml-C1zHJAQt.js +1 -0
- package/viewer-dist/assets/haml-mwfMQlUs.js +1 -0
- package/viewer-dist/assets/handlebars-CEZndQNl.js +1 -0
- package/viewer-dist/assets/handlebars-g-3gLrXt.js +1 -0
- package/viewer-dist/assets/haskell-D8IpX4py.js +1 -0
- package/viewer-dist/assets/haxe-CD8O8Ul0.js +1 -0
- package/viewer-dist/assets/haxe-j5FdAS1V.js +1 -0
- package/viewer-dist/assets/hcl-Dh228itO.js +1 -0
- package/viewer-dist/assets/highlights-B57wCzB5.js +3 -0
- package/viewer-dist/assets/hjson-CxZEssPk.js +1 -0
- package/viewer-dist/assets/hlsl-C3sg_olF.js +1 -0
- package/viewer-dist/assets/hlsl-ajL2FB-w.js +1 -0
- package/viewer-dist/assets/horizon-CE9ld1lL.js +1 -0
- package/viewer-dist/assets/horizon-DUI96lQn.js +1 -0
- package/viewer-dist/assets/horizon-bright-COxh1lHf.js +1 -0
- package/viewer-dist/assets/horizon-bright-DSNQnXHK.js +1 -0
- package/viewer-dist/assets/houston-CsvMBhTu.js +1 -0
- package/viewer-dist/assets/houston-DduE73P7.js +1 -0
- package/viewer-dist/assets/html-DSw1lh5G.js +1 -0
- package/viewer-dist/assets/html-WQKKblVZ.js +1 -0
- package/viewer-dist/assets/html-derivative-CjJKezcp.js +1 -0
- package/viewer-dist/assets/html-derivative-DyzJkWO6.js +1 -0
- package/viewer-dist/assets/http-BjrBtiM6.js +1 -0
- package/viewer-dist/assets/hurl-B4P9s9G3.js +1 -0
- package/viewer-dist/assets/hxml-DPF7XkXa.js +1 -0
- package/viewer-dist/assets/hy-CZbG8q4J.js +1 -0
- package/viewer-dist/assets/imba-DsUTQ-LC.js +1 -0
- package/viewer-dist/assets/index-B0ZrAosS.css +1 -0
- package/viewer-dist/assets/index-CVKGwJkR.js +255 -0
- package/viewer-dist/assets/ini-0B7NLFlx.js +1 -0
- package/viewer-dist/assets/ini-DxURaTxO.js +1 -0
- package/viewer-dist/assets/java-BtIQNnN0.js +1 -0
- package/viewer-dist/assets/java-DxlWrXwe.js +1 -0
- package/viewer-dist/assets/javascript-BzbQS41l.js +1 -0
- package/viewer-dist/assets/javascript-Yelw-5ZN.js +1 -0
- package/viewer-dist/assets/jinja-dRcm23Ea.js +1 -0
- package/viewer-dist/assets/jison-D3aJooqo.js +1 -0
- package/viewer-dist/assets/json-B88Oqtu5.js +1 -0
- package/viewer-dist/assets/json-CaljABEy.js +1 -0
- package/viewer-dist/assets/json5-BR5RXkoi.js +1 -0
- package/viewer-dist/assets/jsonc-CTI_jrid.js +1 -0
- package/viewer-dist/assets/jsonc-dcnCvL0G.js +1 -0
- package/viewer-dist/assets/jsonl-CmCQp5Yx.js +1 -0
- package/viewer-dist/assets/jsonnet-CJTPZ8u_.js +1 -0
- package/viewer-dist/assets/jssm-DXw9l8Rf.js +1 -0
- package/viewer-dist/assets/jsx-D3KKoC5L.js +1 -0
- package/viewer-dist/assets/jsx-hEbJ82HF.js +1 -0
- package/viewer-dist/assets/julia-BCOw4cyx.js +1 -0
- package/viewer-dist/assets/julia-hqywDEUR.js +1 -0
- package/viewer-dist/assets/just-Br47BmIC.js +1 -0
- package/viewer-dist/assets/kanagawa-dragon-BHDhSKDf.js +1 -0
- package/viewer-dist/assets/kanagawa-dragon-Bozd7klA.js +1 -0
- package/viewer-dist/assets/kanagawa-lotus-BmuOG9ZW.js +1 -0
- package/viewer-dist/assets/kanagawa-lotus-NJjGXXql.js +1 -0
- package/viewer-dist/assets/kanagawa-wave-BML5mF2J.js +1 -0
- package/viewer-dist/assets/kanagawa-wave-DsGe2Uqk.js +1 -0
- package/viewer-dist/assets/kdl-CsD5j6eV.js +1 -0
- package/viewer-dist/assets/kotlin-DhhofPvG.js +1 -0
- package/viewer-dist/assets/kusto-C7mF5XQf.js +1 -0
- package/viewer-dist/assets/langs-JgP7EaER.js +2 -0
- package/viewer-dist/assets/laserwave-C_8bwKvT.js +1 -0
- package/viewer-dist/assets/laserwave-DYV0fvJ_.js +1 -0
- package/viewer-dist/assets/latex-B_Ztlc7G.js +1 -0
- package/viewer-dist/assets/latex-Djh9Fg1h.js +1 -0
- package/viewer-dist/assets/lean-CewbzKMR.js +1 -0
- package/viewer-dist/assets/less-B64L-FWb.js +1 -0
- package/viewer-dist/assets/less-GWsDhusf.js +1 -0
- package/viewer-dist/assets/lib-IuaA1a0_.js +9 -0
- package/viewer-dist/assets/light-plus-DVQuIRkW.js +1 -0
- package/viewer-dist/assets/light-plus-FTnIShls.js +1 -0
- package/viewer-dist/assets/liquid-CQNtsgCr.js +1 -0
- package/viewer-dist/assets/llvm-DqHOMS-s.js +1 -0
- package/viewer-dist/assets/loader-D4gJynmd.js +1 -0
- package/viewer-dist/assets/log-BvtJ4bSl.js +1 -0
- package/viewer-dist/assets/log-DSUv6hjM.js +1 -0
- package/viewer-dist/assets/logo-Cluzi2Zq.js +1 -0
- package/viewer-dist/assets/lua-BJObVtAx.js +1 -0
- package/viewer-dist/assets/lua-DjuecEsk.js +1 -0
- package/viewer-dist/assets/luau-VGWVLoqX.js +1 -0
- package/viewer-dist/assets/make-BLT6fICl.js +1 -0
- package/viewer-dist/assets/make-URElk0GJ.js +1 -0
- package/viewer-dist/assets/markdown-CboqBxpY.js +1 -0
- package/viewer-dist/assets/markdown-Cla8Gbs6.js +1 -0
- package/viewer-dist/assets/marko-DPS0EkZ1.js +1 -0
- package/viewer-dist/assets/material-theme-Bm3Qr25_.js +1 -0
- package/viewer-dist/assets/material-theme-IcIb8QNx.js +1 -0
- package/viewer-dist/assets/material-theme-darker-2IIEA8gg.js +1 -0
- package/viewer-dist/assets/material-theme-darker-B_f2vxdL.js +1 -0
- package/viewer-dist/assets/material-theme-lighter-CR2Q-4Hp.js +1 -0
- package/viewer-dist/assets/material-theme-lighter-uhdI0v04.js +1 -0
- package/viewer-dist/assets/material-theme-ocean-BX6hAJ_y.js +1 -0
- package/viewer-dist/assets/material-theme-ocean-CHQ94UKr.js +1 -0
- package/viewer-dist/assets/material-theme-palenight-B5W6OYN7.js +1 -0
- package/viewer-dist/assets/material-theme-palenight-B6DWAotd.js +1 -0
- package/viewer-dist/assets/matlab-D7qyCx1q.js +1 -0
- package/viewer-dist/assets/mdc-C6srEd4p.js +1 -0
- package/viewer-dist/assets/mdx-DQZ5AkYe.js +1 -0
- package/viewer-dist/assets/mermaid-BxpfTIzt.js +1 -0
- package/viewer-dist/assets/min-dark-BSWPekZh.js +1 -0
- package/viewer-dist/assets/min-dark-DECtZcqS.js +1 -0
- package/viewer-dist/assets/min-light-DDpmG2fV.js +1 -0
- package/viewer-dist/assets/min-light-qRIVcaqf.js +1 -0
- package/viewer-dist/assets/mipsasm-BMqwQI7S.js +1 -0
- package/viewer-dist/assets/mojo-fg40_ntQ.js +1 -0
- package/viewer-dist/assets/monokai-BscAjiQZ.js +1 -0
- package/viewer-dist/assets/monokai-CLmrJ-8t.js +1 -0
- package/viewer-dist/assets/moonbit-D9W784E_.js +1 -0
- package/viewer-dist/assets/move-BYnGhZoM.js +1 -0
- package/viewer-dist/assets/narrat-_X_XdTYD.js +1 -0
- package/viewer-dist/assets/nextflow-groovy-1acFxZ7Y.js +1 -0
- package/viewer-dist/assets/nextflow-groovy-C770ykRh.js +1 -0
- package/viewer-dist/assets/nextflow-uA5IJerx.js +1 -0
- package/viewer-dist/assets/nginx-BxRBJ-Af.js +1 -0
- package/viewer-dist/assets/night-owl-DhmEMT88.js +1 -0
- package/viewer-dist/assets/night-owl-eR4AsyAP.js +1 -0
- package/viewer-dist/assets/night-owl-light-C74n5ti-.js +1 -0
- package/viewer-dist/assets/night-owl-light-eJ-hLW7d.js +1 -0
- package/viewer-dist/assets/nim-Dr8hIC6Y.js +1 -0
- package/viewer-dist/assets/nim-ZjzS1dcU.js +1 -0
- package/viewer-dist/assets/nix-IvuFDN5E.js +1 -0
- package/viewer-dist/assets/nord-Cb4Vim4T.js +1 -0
- package/viewer-dist/assets/nord-D4wy7NEP.js +1 -0
- package/viewer-dist/assets/nsis-CjNLYCLg.js +1 -0
- package/viewer-dist/assets/nushell--0fT3PI1.js +1 -0
- package/viewer-dist/assets/objective-c-DMLMCfZd.js +1 -0
- package/viewer-dist/assets/objective-c-D_ECFp-D.js +1 -0
- package/viewer-dist/assets/objective-cpp-BsSzOQcm.js +1 -0
- package/viewer-dist/assets/ocaml-D6dNsUd0.js +1 -0
- package/viewer-dist/assets/ocaml-oSZO9LTw.js +1 -0
- package/viewer-dist/assets/odin-B1RWQWA5.js +1 -0
- package/viewer-dist/assets/one-dark-pro-28TLzoS8.js +1 -0
- package/viewer-dist/assets/one-dark-pro-C6YyR8OD.js +1 -0
- package/viewer-dist/assets/one-light-C0UY_Fh7.js +1 -0
- package/viewer-dist/assets/one-light-D7Lr4KcI.js +1 -0
- package/viewer-dist/assets/openscad-BUDT5pXO.js +1 -0
- package/viewer-dist/assets/org-B3Y3gBCc.js +1 -0
- package/viewer-dist/assets/pascal-4ZHwLPI5.js +1 -0
- package/viewer-dist/assets/perl-Di9CLCS0.js +1 -0
- package/viewer-dist/assets/perl-sgZsTtaf.js +1 -0
- package/viewer-dist/assets/php-D9QpVhjP.js +1 -0
- package/viewer-dist/assets/php-DXPvgw5o.js +1 -0
- package/viewer-dist/assets/pierre-dark-CpLgRqie.js +1 -0
- package/viewer-dist/assets/pierre-dark-fPlffE7i.js +1 -0
- package/viewer-dist/assets/pierre-dark-protanopia-deuteranopia-B35FxJx-.js +1 -0
- package/viewer-dist/assets/pierre-dark-protanopia-deuteranopia-BmjibgrW.js +1 -0
- package/viewer-dist/assets/pierre-dark-soft-Cng2SYKc.js +1 -0
- package/viewer-dist/assets/pierre-dark-soft-kZQmAZld.js +1 -0
- package/viewer-dist/assets/pierre-dark-tritanopia-CpjhbsIL.js +1 -0
- package/viewer-dist/assets/pierre-dark-tritanopia-DneQ5i7L.js +1 -0
- package/viewer-dist/assets/pierre-dark-vibrant-BUK9Y-N_.js +1 -0
- package/viewer-dist/assets/pierre-dark-vibrant-CpQYzh95.js +1 -0
- package/viewer-dist/assets/pierre-light-BvcXQJIj.js +1 -0
- package/viewer-dist/assets/pierre-light-CoaEpmwp.js +1 -0
- package/viewer-dist/assets/pierre-light-protanopia-deuteranopia-0fSaH845.js +1 -0
- package/viewer-dist/assets/pierre-light-protanopia-deuteranopia-Cd5nk0bp.js +1 -0
- package/viewer-dist/assets/pierre-light-soft-BvU23vks.js +1 -0
- package/viewer-dist/assets/pierre-light-soft-lWLdNTOI.js +1 -0
- package/viewer-dist/assets/pierre-light-tritanopia-BSHccQzI.js +1 -0
- package/viewer-dist/assets/pierre-light-tritanopia-CEbqgOJL.js +1 -0
- package/viewer-dist/assets/pierre-light-vibrant-BgMZEwQI.js +1 -0
- package/viewer-dist/assets/pierre-light-vibrant-D80Fkn33.js +1 -0
- package/viewer-dist/assets/pkl-ot-7Btpt.js +1 -0
- package/viewer-dist/assets/plastic-B2V_PDVk.js +1 -0
- package/viewer-dist/assets/plastic-DQwYfKfQ.js +1 -0
- package/viewer-dist/assets/plsql-DGHpHOYJ.js +1 -0
- package/viewer-dist/assets/po-BiJDBrnU.js +1 -0
- package/viewer-dist/assets/poimandres-DB9-pI6r.js +1 -0
- package/viewer-dist/assets/poimandres-DRFjx7u4.js +1 -0
- package/viewer-dist/assets/polar-C7UOKdEL.js +1 -0
- package/viewer-dist/assets/postcss-D_Wz94rJ.js +1 -0
- package/viewer-dist/assets/postcss-e3XvZOFQ.js +1 -0
- package/viewer-dist/assets/powerquery-DNMTfnFr.js +1 -0
- package/viewer-dist/assets/powershell-CItYMEtV.js +1 -0
- package/viewer-dist/assets/powershell-DyPZnz5v.js +1 -0
- package/viewer-dist/assets/preload-helper-BZ1Pz5am.js +1 -0
- package/viewer-dist/assets/prisma-DMgNhnYS.js +1 -0
- package/viewer-dist/assets/prolog-iXnhIJG7.js +1 -0
- package/viewer-dist/assets/proto-DB4EqR-F.js +1 -0
- package/viewer-dist/assets/pug-BlofpNpK.js +1 -0
- package/viewer-dist/assets/pug-nGRwXpob.js +1 -0
- package/viewer-dist/assets/puppet-CDv2pdJW.js +1 -0
- package/viewer-dist/assets/purescript-9MfHhQsQ.js +1 -0
- package/viewer-dist/assets/python-CzFU0dpx.js +1 -0
- package/viewer-dist/assets/python-ORI17Sev.js +1 -0
- package/viewer-dist/assets/qml-BxleM7bJ.js +1 -0
- package/viewer-dist/assets/qmldir-DCQb3MpD.js +1 -0
- package/viewer-dist/assets/qss-Fe1Jh2GI.js +1 -0
- package/viewer-dist/assets/r-DWzjseEo.js +1 -0
- package/viewer-dist/assets/r-Dr1JUpHl.js +1 -0
- package/viewer-dist/assets/racket-DcIDlBhZ.js +1 -0
- package/viewer-dist/assets/raku-B6hKIqfP.js +1 -0
- package/viewer-dist/assets/raku-BtFKomnU.js +1 -0
- package/viewer-dist/assets/razor-UAq-8THt.js +1 -0
- package/viewer-dist/assets/rbs-C0MpOrj4.js +1 -0
- package/viewer-dist/assets/red-CYlAq2b0.js +1 -0
- package/viewer-dist/assets/red-CqYzoXtd.js +1 -0
- package/viewer-dist/assets/reg-CRGYupPL.js +1 -0
- package/viewer-dist/assets/regexp-B4pBNbU3.js +1 -0
- package/viewer-dist/assets/regexp-BWpGejPw.js +1 -0
- package/viewer-dist/assets/rel-BtDbiS_P.js +1 -0
- package/viewer-dist/assets/riscv-Ckw8ddFX.js +1 -0
- package/viewer-dist/assets/rolldown-runtime-Dd_uD5pT.js +1 -0
- package/viewer-dist/assets/ron-VUp2lXgN.js +1 -0
- package/viewer-dist/assets/rose-pine-C3zjVKxG.js +1 -0
- package/viewer-dist/assets/rose-pine-aMsaMD1D.js +1 -0
- package/viewer-dist/assets/rose-pine-dawn-8PwUyIlP.js +1 -0
- package/viewer-dist/assets/rose-pine-dawn-C72QYfqa.js +1 -0
- package/viewer-dist/assets/rose-pine-moon-CSM8ewhO.js +1 -0
- package/viewer-dist/assets/rose-pine-moon-DO-qXg-I.js +1 -0
- package/viewer-dist/assets/rosmsg-CAekHB0j.js +1 -0
- package/viewer-dist/assets/rst-DT-C-5fA.js +1 -0
- package/viewer-dist/assets/ruby-B6sU6EpJ.js +1 -0
- package/viewer-dist/assets/ruby-BwIxDKXu.js +1 -0
- package/viewer-dist/assets/rust-DBZE5Si3.js +1 -0
- package/viewer-dist/assets/rust-tUOVui2B.js +1 -0
- package/viewer-dist/assets/sas-BowjnAvi.js +1 -0
- package/viewer-dist/assets/sass-DXrisJhu.js +1 -0
- package/viewer-dist/assets/scala-Dcd77NNm.js +1 -0
- package/viewer-dist/assets/scala-o2NiCLJc.js +1 -0
- package/viewer-dist/assets/scheme-DQCgrYNe.js +1 -0
- package/viewer-dist/assets/scss-CWs8DVSa.js +1 -0
- package/viewer-dist/assets/scss-Dec6wfVg.js +1 -0
- package/viewer-dist/assets/sdbl-CpzYUp7e.js +1 -0
- package/viewer-dist/assets/sdbl-DFPhMlBm.js +1 -0
- package/viewer-dist/assets/shaderlab-DY7g_Ava.js +1 -0
- package/viewer-dist/assets/shellscript-BiGZg9Om.js +1 -0
- package/viewer-dist/assets/shellscript-CqHdAlCp.js +1 -0
- package/viewer-dist/assets/shellsession-DDrivR0a.js +1 -0
- package/viewer-dist/assets/shiki-BYYByAlk.js +2 -0
- package/viewer-dist/assets/slack-dark-DnToyrRv.js +1 -0
- package/viewer-dist/assets/slack-dark-Dtzi51su.js +1 -0
- package/viewer-dist/assets/slack-ochin-B2OO5cIa.js +1 -0
- package/viewer-dist/assets/slack-ochin-Bb7oPExa.js +1 -0
- package/viewer-dist/assets/smalltalk-BHpQb5nM.js +1 -0
- package/viewer-dist/assets/smithy-Dgaz7aur.js +1 -0
- package/viewer-dist/assets/snazzy-light-4G7pJPwS.js +1 -0
- package/viewer-dist/assets/snazzy-light-DXgiwzKu.js +1 -0
- package/viewer-dist/assets/solarized-dark-BKOT3ICq.js +1 -0
- package/viewer-dist/assets/solarized-dark-b97czJOk.js +1 -0
- package/viewer-dist/assets/solarized-light--Lk5pOfE.js +1 -0
- package/viewer-dist/assets/solarized-light-DFPxpIYQ.js +1 -0
- package/viewer-dist/assets/solidity-Bj7E1mRn.js +1 -0
- package/viewer-dist/assets/soy-CUUUw2U6.js +1 -0
- package/viewer-dist/assets/sparql-Dy5Sx-zJ.js +1 -0
- package/viewer-dist/assets/splunk-BC2Px7Mm.js +1 -0
- package/viewer-dist/assets/sql-BOsskAmu.js +1 -0
- package/viewer-dist/assets/sql-CNu3Or2W.js +1 -0
- package/viewer-dist/assets/ssh-config-BgfXC-Er.js +1 -0
- package/viewer-dist/assets/stata-Dj4sbAEx.js +1 -0
- package/viewer-dist/assets/stream-tokenizer-a_hv0fYK.js +4 -0
- package/viewer-dist/assets/stylus-BOYZFyl7.js +1 -0
- package/viewer-dist/assets/stylus-LiTfbrWi.js +1 -0
- package/viewer-dist/assets/surrealql-NoXzmj18.js +1 -0
- package/viewer-dist/assets/svelte-BaCIHHWd.js +1 -0
- package/viewer-dist/assets/swift-CpxeRS9H.js +1 -0
- package/viewer-dist/assets/swift-DQ24oLw9.js +1 -0
- package/viewer-dist/assets/synthwave-84-BJJFg-sc.js +1 -0
- package/viewer-dist/assets/synthwave-84-nFMaYfgc.js +1 -0
- package/viewer-dist/assets/system-verilog-CIGW6CHD.js +1 -0
- package/viewer-dist/assets/system-verilog-Dp2k_mze.js +1 -0
- package/viewer-dist/assets/systemd-BxMlprV5.js +1 -0
- package/viewer-dist/assets/talonscript-CohzipZa.js +1 -0
- package/viewer-dist/assets/tasl-DMoTqEGO.js +1 -0
- package/viewer-dist/assets/tcl-CZd0xW_V.js +1 -0
- package/viewer-dist/assets/templ-BfgLc4ra.js +1 -0
- package/viewer-dist/assets/terraform-DswuEJGm.js +1 -0
- package/viewer-dist/assets/tex-C9L8xJex.js +1 -0
- package/viewer-dist/assets/tex-CeakZqzU.js +1 -0
- package/viewer-dist/assets/themes-DP0gt5jG.js +2 -0
- package/viewer-dist/assets/tokyo-night-DvpptEDd.js +1 -0
- package/viewer-dist/assets/tokyo-night-oM2G3aXe.js +1 -0
- package/viewer-dist/assets/toml-CcmNWLt0.js +1 -0
- package/viewer-dist/assets/ts-tags-DLz2GTd3.js +1 -0
- package/viewer-dist/assets/tsv-sltzmVWM.js +1 -0
- package/viewer-dist/assets/tsx-5f3ulCja.js +1 -0
- package/viewer-dist/assets/tsx-BOvsFOI6.js +1 -0
- package/viewer-dist/assets/turtle-B2uMLKuz.js +1 -0
- package/viewer-dist/assets/turtle-CcN57yC0.js +1 -0
- package/viewer-dist/assets/twig-BuizuR2K.js +1 -0
- package/viewer-dist/assets/twig-p9meEoSL.js +1 -0
- package/viewer-dist/assets/typescript-Utq2Cl8c.js +1 -0
- package/viewer-dist/assets/typescript-j_1H8WHN.js +1 -0
- package/viewer-dist/assets/typespec-BGhR2SqG.js +1 -0
- package/viewer-dist/assets/typst-qZ7a-KdK.js +1 -0
- package/viewer-dist/assets/unwrapDefault-ByDmBtHB.js +1 -0
- package/viewer-dist/assets/v-DBj4K9d_.js +1 -0
- package/viewer-dist/assets/vala-zf12oZj6.js +1 -0
- package/viewer-dist/assets/vb-3nVziYZS.js +1 -0
- package/viewer-dist/assets/vb-Dcr14nCw.js +1 -0
- package/viewer-dist/assets/verilog-DUw2aqD4.js +1 -0
- package/viewer-dist/assets/verilog-kL8Dwv27.js +1 -0
- package/viewer-dist/assets/vesper-C1rBZbON.js +1 -0
- package/viewer-dist/assets/vesper-DdrHHSXu.js +1 -0
- package/viewer-dist/assets/vhdl-BroJfC0k.js +1 -0
- package/viewer-dist/assets/viml-DvXPmvsu.js +1 -0
- package/viewer-dist/assets/vitesse-black-Sqvrs2Sw.js +1 -0
- package/viewer-dist/assets/vitesse-black-fwtXNY1n.js +1 -0
- package/viewer-dist/assets/vitesse-dark-BWf_ZQtP.js +1 -0
- package/viewer-dist/assets/vitesse-dark-BZCL-v6S.js +1 -0
- package/viewer-dist/assets/vitesse-light-Cqenv4Qv.js +1 -0
- package/viewer-dist/assets/vitesse-light-VbXTXTou.js +1 -0
- package/viewer-dist/assets/vue-html-CGMs_6qn.js +1 -0
- package/viewer-dist/assets/vue-qH43U_rv.js +1 -0
- package/viewer-dist/assets/vue-vine-6XI2pIvQ.js +1 -0
- package/viewer-dist/assets/vyper-CgoNMtux.js +1 -0
- package/viewer-dist/assets/wasm-BnjxR4X6.js +1 -0
- package/viewer-dist/assets/wasm-ByWQv1Qj.js +1 -0
- package/viewer-dist/assets/wenyan-C8pVoKbM.js +1 -0
- package/viewer-dist/assets/wgsl-BsKzXJz4.js +1 -0
- package/viewer-dist/assets/wikitext-ClFFjSW2.js +1 -0
- package/viewer-dist/assets/wit-DdvCle-K.js +1 -0
- package/viewer-dist/assets/wolfram-DLL8P-h_.js +1 -0
- package/viewer-dist/assets/xml-CoDIzWF0.js +1 -0
- package/viewer-dist/assets/xml-WY0zc4PG.js +1 -0
- package/viewer-dist/assets/xsl-ChYNfH-b.js +1 -0
- package/viewer-dist/assets/xsl-Czhm44Ae.js +1 -0
- package/viewer-dist/assets/yaml-CxbubiML.js +1 -0
- package/viewer-dist/assets/yaml-DijMHRDA.js +1 -0
- package/viewer-dist/assets/zenscript-BnlCZFoB.js +1 -0
- package/viewer-dist/assets/zig-B7sSDI6F.js +1 -0
- package/viewer-dist/assets/zig-VWdiCTxG.js +1 -0
- package/viewer-dist/index.html +77 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tanishq Kancharla
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,567 @@
|
|
|
1
|
-
#
|
|
1
|
+
# productdoc
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Understand the system, decide what to build, and review what changed.** Productdoc turns your coding agent's findings into visual documents, with diagrams, media, and source links behind the reasoning.
|
|
4
|
+
|
|
5
|
+
Use it to explain an existing workflow, plan future work, or review a change. Documents start with the reader's question and familiar UI or involved services—not automatically with code. Plans keep one small, independent or commit-sized change per page.
|
|
6
|
+
|
|
7
|
+
## Try it
|
|
8
|
+
|
|
9
|
+
**Release status:** the renamed package is prepared in this checkout, not yet published. The commands below describe the release candidate. From this checkout, use `npm run cli -- guide` or `npm run cli -- serve <directory>` until publication; do not expect a public npm install to work yet.
|
|
10
|
+
|
|
11
|
+
Install the skill after the package is released:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npx skills add tanishqkancharla/diffmap --skill generate-product-doc
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Then ask your agent to explain an existing system, plan work, or review changes:
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
Use generate-product-doc to explain how this app handles sign-in, including what happens when the session expires.
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The skill is a short pointer: your agent loads the full instructions from `npx product-doc guide`, so they stay version-matched to the viewer. When the stub itself changes, update it with `npx skills update generate-product-doc`.
|
|
24
|
+
|
|
25
|
+
The skill keeps documents in `.diffmap/specs/<name>/`. Productdoc is open source and MIT licensed. Documents are served locally by default; [sharing as an unlisted gist](#share-a-spec-with-a-link-experimental) still uses diffmap.dev until productdoc.dev supports those links.
|
|
26
|
+
|
|
27
|
+
### Migrating from Diffmap
|
|
28
|
+
|
|
29
|
+
Productdoc is the standalone successor to Diffmap, expanding beyond diff review. The npm package is `product-doc`, its executable is `product-doc`, and its website will be **productdoc.dev**. The GitHub repository keeps its current URL.
|
|
30
|
+
|
|
31
|
+
Both skills coexist temporarily. Existing published Diffmap packages, the legacy skill, and the live site are unchanged by these local edits; users will be invited to migrate later. Keep existing documents and paths rather than copying them. No legacy binary alias or automatic installation migration is added.
|
|
32
|
+
|
|
33
|
+
[The original Diffmap launch video](https://x.com/tanishqk/status/2116212881125691850) shows the review workflow this builds on.
|
|
34
|
+
|
|
35
|
+
## See the main ideas
|
|
36
|
+
|
|
37
|
+
Your agent picks the best diagram for each idea, and each part of a diagram links to its code. [diffmap.dev](https://diffmap.dev) walks through each one on an example pull request.
|
|
38
|
+
|
|
39
|
+
### Service diagrams
|
|
40
|
+
|
|
41
|
+
A service diagram shows each service and its state. Each step shows one event and the state that the event changes, so you do not have to remember the state. Press **Play** to step through it. See [Animated service diagrams](#animated-service-diagrams) for the syntax.
|
|
42
|
+
|
|
43
|
+

|
|
44
|
+
|
|
45
|
+
### Diagram and call stack diffs
|
|
46
|
+
|
|
47
|
+
A Mermaid or service diagram can show a change in one picture: red parts exist only today, and green parts are new. In a service diagram diff, each value shows today's state crossed out next to the new state. Call stacks show a change the same way, with `+` rows for new code and `-` rows for code the change removes. See [Diagram diffs](#diagram-diffs).
|
|
48
|
+
|
|
49
|
+

|
|
50
|
+
|
|
51
|
+
### Phases and commits
|
|
52
|
+
|
|
53
|
+
A spec is a directory with a cover page and one page per phase. The agent writes the plan in phases, each small enough to be one commit. When a phase is done, the spec shows a card for its commit with the files to review, most important first. Click a file to open its diff. Every link in the phase then points at that commit, so it keeps showing the code from that commit after the file changes.
|
|
54
|
+
|
|
55
|
+

|
|
56
|
+
|
|
57
|
+
### Comments
|
|
58
|
+
|
|
59
|
+
Highlight text on the page and press **Comment** to leave a note beside it.
|
|
60
|
+
In a diff, file excerpt, or the Diff panel, hover a line and press the **+**
|
|
61
|
+
in the gutter, or drag it across several lines, to comment under those lines.
|
|
62
|
+
Comments save in your browser (localStorage, per page) and survive reloads.
|
|
63
|
+
**Copy comments** in the top right copies them all as a numbered Markdown list,
|
|
64
|
+
each with its location and the quoted text or lines, ready to paste to an
|
|
65
|
+
agent. ⌘/Ctrl-Enter saves a comment and Escape cancels it.
|
|
66
|
+
|
|
67
|
+

|
|
68
|
+
|
|
69
|
+
## Run the viewer
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
npx product-doc serve .diffmap/specs/<name>/
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Bare `npx product-doc .diffmap/specs/<name>/` is the same as `serve`. A spec is always a directory; `serve`, `validate`, and `share` reject a single Markdown file and say where to move it.
|
|
76
|
+
|
|
77
|
+
Options:
|
|
78
|
+
|
|
79
|
+
- `--port <n>` — pin a listen port (default: a free port)
|
|
80
|
+
- `--root <dir>` — workspace root for file excerpts (default the directory you ran the command from)
|
|
81
|
+
|
|
82
|
+
**Close server** in the top right stops the server. Hosted gist and GitHub viewers have no local server, so they omit this control.
|
|
83
|
+
|
|
84
|
+
The server also stops after 24 hours without a page or source request.
|
|
85
|
+
Loading or refreshing the page resets the timer; background health checks and
|
|
86
|
+
the live-reload connection do not keep it alive.
|
|
87
|
+
|
|
88
|
+
Check a spec without starting a server or publishing anything:
|
|
89
|
+
|
|
90
|
+
```sh
|
|
91
|
+
npx product-doc validate .diffmap/specs/<name>/
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`validate` uses the viewer's parser to check every page's Markdown, diagrams, and
|
|
95
|
+
annotations, and the spec's page names. It exits 0 with `valid: true` and the
|
|
96
|
+
pages in order on success, and 1 with the error, naming the page, on failure.
|
|
97
|
+
Use `--json` for machine-readable output. It does not resolve source files or
|
|
98
|
+
Git commits. Run it after edits, including when reusing an already-running viewer.
|
|
99
|
+
After updating productdoc itself, restart existing viewers so they use the new parser.
|
|
100
|
+
|
|
101
|
+
List every running viewer, including viewers using custom ports:
|
|
102
|
+
|
|
103
|
+
```sh
|
|
104
|
+
npx product-doc list
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Update a global install to the latest `product-doc` on npm. `product-doc --update` does the same thing:
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
product-doc update
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
If you are already on the latest version, it says so and exits. Otherwise it runs the global install for the package manager that installed productdoc (`npm install --global`, `pnpm add --global`, or `bun add --global`) and prints the old and new versions. Under `npx`, or when it cannot tell how productdoc was installed, it prints the command to run instead of installing anything.
|
|
114
|
+
|
|
115
|
+
Request a page with `Accept: text/markdown` to read its current source file
|
|
116
|
+
instead of the rendered HTML. Use the URL printed by `serve`, with the page's
|
|
117
|
+
slug for any page but the cover:
|
|
118
|
+
|
|
119
|
+
```sh
|
|
120
|
+
curl -H 'Accept: text/markdown' http://127.0.0.1:<port>/write-through
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## Spec layout
|
|
124
|
+
|
|
125
|
+
A spec is a directory of Markdown pages:
|
|
126
|
+
|
|
127
|
+
```text
|
|
128
|
+
.diffmap/specs/sessions-in-postgres/
|
|
129
|
+
README.md the cover, at /
|
|
130
|
+
01-sessions-table.md at /sessions-table
|
|
131
|
+
02-write-through.md at /write-through
|
|
132
|
+
media/ images and videos the pages show
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
- `README.md` is the cover. Its first `#` heading is the spec's title.
|
|
136
|
+
- Every other `.md` or `.mdx` file needs a number prefix, which sets its place:
|
|
137
|
+
`2-` comes before `10-`. The rest of the name, the slug, is the page's URL,
|
|
138
|
+
so renumbering pages keeps their links and comments. Two pages cannot share a
|
|
139
|
+
slug, and `validate` and `serve` reject a page without a number.
|
|
140
|
+
- The viewer shows one page at a time, with the spec's pages and the current
|
|
141
|
+
page's headings in the left gutter, and links to the previous and next page
|
|
142
|
+
at the bottom. A page's first heading is its title in that list.
|
|
143
|
+
- A relative link to a page file, such as `[Phase 2](02-write-through.md#tests)`,
|
|
144
|
+
opens that page, in productdoc and on GitHub.
|
|
145
|
+
- Each page keeps its own comments and Diff panel, which opens the page's first
|
|
146
|
+
`changes` card. **Copy comments** copies the comments from every page,
|
|
147
|
+
under each page's title.
|
|
148
|
+
- `serve` reloads a page when its file changes, and every page when you add,
|
|
149
|
+
remove, or retitle one.
|
|
150
|
+
|
|
151
|
+
Run `npx product-doc fixtures/sessions-in-postgres` for an example.
|
|
152
|
+
|
|
153
|
+
## Share a spec with a link (experimental)
|
|
154
|
+
|
|
155
|
+
Share an unlisted gist and print a `diffmap.dev` link (requires [`gh`](https://cli.github.com/) logged in). Does not start a local server:
|
|
156
|
+
|
|
157
|
+
```sh
|
|
158
|
+
npx product-doc share .diffmap/specs/<name>/
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
A spec's pages share one gist. Hosted viewer: `https://diffmap.dev/g/<gistId>` for the cover, and `/<slug>` after it for a page (`#heading` is the table of contents). Gists shared before specs were directories still open, one file at a time. The page fetches the gist in the browser from `api.github.com`. Gists are unlisted, not private.
|
|
162
|
+
|
|
163
|
+
A spec committed to a GitHub pull request also opens at `https://diffmap.dev/<owner>/<repo>/pull/<n>/.diffmap/specs/<name>/`, which pins to the pull request's head commit and opens the spec's cover. Its pages keep their file names in the URL, as in `…/commit/<sha>/.diffmap/specs/<name>/02-write-through.md`, since a pinned commit never renames them.
|
|
164
|
+
|
|
165
|
+
## Library
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
import { startServer, parseFence, parseViewerDocument } from "product-doc";
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
`parseViewerDocument` turns markdown into the page document with [md4x](https://github.com/unjs/md4x). `startServer` listens. The guide that `product-doc guide` prints owns document shape; the viewer does not.
|
|
172
|
+
|
|
173
|
+
## Fences
|
|
174
|
+
|
|
175
|
+
| Fence info string | Viewer |
|
|
176
|
+
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
177
|
+
| `mermaid` | Beautiful Mermaid |
|
|
178
|
+
| `services` | Animated service diagram you can play or step through |
|
|
179
|
+
| `mermaid diff` or `services diff` | The same diagram with [added and removed parts marked](#diagram-diffs) |
|
|
180
|
+
| `callstack` or `diff` containing `└──` / `├──` | Interactive stack rows, no file header |
|
|
181
|
+
| `diff` or `diff:path` with a file path | Pierre patch with Pierre’s file header |
|
|
182
|
+
| `diff` with no path | Pierre patch, no file header |
|
|
183
|
+
| `changes` with a commit, range, or empty body | Files changed card with a Review button; empty means uncommitted changes |
|
|
184
|
+
| `start:end:path` | Pierre file excerpt with Pierre’s file header |
|
|
185
|
+
| `html` | Trusted HTML from this file. productdoc does not sanitize it. Only use it for local files you wrote. |
|
|
186
|
+
| other langs | Highlighted code with optional [titles, highlights, and notes](#highlight-lines-and-add-notes) |
|
|
187
|
+
|
|
188
|
+
Fences keep whitespace. Use them for mermaid, call stacks, and diffs.
|
|
189
|
+
|
|
190
|
+
### Highlight lines and add notes
|
|
191
|
+
|
|
192
|
+
In a code fence, `{2,4-6}` after the language highlights those lines. Comment
|
|
193
|
+
lines at the bottom of the fence add notes that show on hover or keyboard focus:
|
|
194
|
+
|
|
195
|
+
````md
|
|
196
|
+
```ts {2-3}
|
|
197
|
+
function requestHandler(record: RecordInput) {
|
|
198
|
+
const error = validateInput(record);
|
|
199
|
+
if (error) return error;
|
|
200
|
+
return existingService(record);
|
|
201
|
+
}
|
|
202
|
+
// [!note L2 validateInput] Returns an error when `name` is blank, otherwise undefined.
|
|
203
|
+
// [!note L3] Early return, so storage never sees an invalid record.
|
|
204
|
+
```
|
|
205
|
+
````
|
|
206
|
+
|
|
207
|
+
- `[!note L3]` or `[!note L3-L5]` notes a line range, shown as a blue snippet highlight.
|
|
208
|
+
- `[!note L3 save]` or `[!note L3-L5 save]` notes the first whole-word
|
|
209
|
+
occurrence of `save` on each specified line, shown with a dotted underline.
|
|
210
|
+
- `[!note save]` applies fence-wide, matching the first whole-word occurrence
|
|
211
|
+
on each line. A scoped note takes precedence over a fence-wide note for the
|
|
212
|
+
same match. Matching is textual, not semantic symbol resolution.
|
|
213
|
+
- Start note lines with `//`, `#`, or `--`. The viewer removes them, so line
|
|
214
|
+
numbers count only the code above. Backticks in a note render as code.
|
|
215
|
+
- A symbol that does not appear within its scope, overlapping line notes, or a line number
|
|
216
|
+
outside the fence is a parse error. A note line above other code stays code.
|
|
217
|
+
|
|
218
|
+
Add `[Title]` after the language to show a title above the code, as in
|
|
219
|
+
` ```ts [src/request.ts] {2-3} `. Call stacks and `mermaid` fences take a
|
|
220
|
+
title the same way, as in ` ```mermaid diff [Request flow] `, or
|
|
221
|
+
`::callstack{title="Request flow"}` and `::mermaid{title="Request flow"}` in
|
|
222
|
+
MDC. A `services` fence uses its [start caption](#animated-service-diagrams)
|
|
223
|
+
instead.
|
|
224
|
+
|
|
225
|
+
Call stacks take the same highlights and notes, counting rows from the first.
|
|
226
|
+
Write their notes with `#`. A symbol note matches the row text you see, not
|
|
227
|
+
hidden references. Inside a linked row, symbol notes show on hover only; the
|
|
228
|
+
row itself keeps keyboard focus.
|
|
229
|
+
|
|
230
|
+
Run `npx product-doc fixtures/code-notes` for an example.
|
|
231
|
+
|
|
232
|
+
## MDC
|
|
233
|
+
|
|
234
|
+
md4x Comark components map to the same views:
|
|
235
|
+
|
|
236
|
+
```md
|
|
237
|
+
::mermaid
|
|
238
|
+
flowchart TD
|
|
239
|
+
A --> B
|
|
240
|
+
::
|
|
241
|
+
|
|
242
|
+
::callstack
|
|
243
|
+
startServer
|
|
244
|
+
+└── createViteServer
|
|
245
|
+
::
|
|
246
|
+
|
|
247
|
+
::diff{path="src/cli.ts"}
|
|
248
|
+
--- a/src/cli.ts
|
|
249
|
+
+++ b/src/cli.ts
|
|
250
|
+
::
|
|
251
|
+
|
|
252
|
+
::file{path="src/cli.ts" start="1" end="20"}
|
|
253
|
+
::
|
|
254
|
+
|
|
255
|
+
::changes{rev="a1b2c3d"}
|
|
256
|
+
::
|
|
257
|
+
|
|
258
|
+
::html
|
|
259
|
+
<aside>Note.</aside>
|
|
260
|
+
::
|
|
261
|
+
|
|
262
|
+
::details{summary="How it works"}
|
|
263
|
+
Folded content: prose, lists, and any fence above.
|
|
264
|
+
::
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
`::details` folds its content under the `summary` label until the reader opens it.
|
|
268
|
+
`.md` and `.mdx` are both markdown. Curly braces in prose are plain text.
|
|
269
|
+
|
|
270
|
+
## Images, videos, and galleries
|
|
271
|
+
|
|
272
|
+
Show screenshots and recordings with Markdown image syntax. Paths are relative
|
|
273
|
+
to the spec file.
|
|
274
|
+
|
|
275
|
+
```md
|
|
276
|
+

|
|
277
|
+

|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
A `.mp4`, `.webm`, `.mov`, `.m4v`, or `.ogv` file renders as a video player;
|
|
281
|
+
anything else is an image. On its own line, it shows centered in a card, with
|
|
282
|
+
its alt text as the title row. A title, as in ``, shows on
|
|
283
|
+
hover.
|
|
284
|
+
|
|
285
|
+
Group related images and videos in a gallery, with the layout after `:::gallery`:
|
|
286
|
+
|
|
287
|
+
```md
|
|
288
|
+
:::gallery side-by-side
|
|
289
|
+

|
|
290
|
+

|
|
291
|
+
:::
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
- `side-by-side` puts every item in one row, to compare before and after or one
|
|
295
|
+
page at several widths.
|
|
296
|
+
- `grid` wraps items into rows, to scan states or variants.
|
|
297
|
+
- `carousel` shows one item at a time with Previous and Next (← and →), to step
|
|
298
|
+
through a flow. Add a title after the layout, as in
|
|
299
|
+
`:::gallery carousel [Saving a record]`; it stays in the title row while the
|
|
300
|
+
current item's label changes below it.
|
|
301
|
+
|
|
302
|
+
Each item's alt text is its visible label. A gallery holds only images and
|
|
303
|
+
videos, and `::gallery{layout="grid"}` works too. The syntax matches galleries
|
|
304
|
+
in Amp threads.
|
|
305
|
+
|
|
306
|
+
`serve` loads media from beside the spec, and a spec on a GitHub pull request
|
|
307
|
+
loads it from the same commit. `share` fails when a spec uses local media,
|
|
308
|
+
because a gist holds only text files; link media by https URL to share it.
|
|
309
|
+
|
|
310
|
+
Run `npx product-doc fixtures/media` for an example.
|
|
311
|
+
|
|
312
|
+
## Link call stacks to source changes
|
|
313
|
+
|
|
314
|
+
Append a reference to a call stack line to link it. Paths are relative to `--root`.
|
|
315
|
+
|
|
316
|
+
- `[[path/to/file.ts#symbolName]]` links a TypeScript or JavaScript declaration,
|
|
317
|
+
including qualified names such as `[[src/store.ts#Store.save]]`. Ambiguous
|
|
318
|
+
names show the qualified names you can use instead.
|
|
319
|
+
- `[[path/to/file]]` links a whole file and `[[path/to/file#L12-L30]]` a line
|
|
320
|
+
range. These work with any language.
|
|
321
|
+
- `[[<sha>:path/to/file#L12-L30]]` or `[[<sha>:path/to/file]]` links a change
|
|
322
|
+
in a commit. `<sha>` is a 7–40 character lowercase commit SHA, or a range
|
|
323
|
+
`<sha>..<sha>`.
|
|
324
|
+
|
|
325
|
+
```callstack
|
|
326
|
+
shareMarkdownFile [[src/share.ts#shareMarkdownFile]]
|
|
327
|
+
+└── gistViewerUrl # print the diffmap.dev link [[d14ae1a:src/share.ts#L55-L59]]
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
A reference without a commit opens the Diff panel on uncommitted changes
|
|
331
|
+
(working tree against HEAD), focused on that file or range. If the file has no
|
|
332
|
+
uncommitted changes, the panel shows the current file.
|
|
333
|
+
|
|
334
|
+
A commit reference opens the Diff panel on every file changed in that commit or
|
|
335
|
+
range, with a sticky header per file, scrolled to the linked file and lines.
|
|
336
|
+
Line numbers are the file's lines after the commit. The file must be changed in
|
|
337
|
+
that commit and the range must fit the new file; `serve` and `share` run git and
|
|
338
|
+
fail at startup otherwise. Deleted lines cannot be referenced, and a commit
|
|
339
|
+
cannot be combined with `#symbol`.
|
|
340
|
+
|
|
341
|
+
Multiple references on one stack line are allowed. The references are hidden in
|
|
342
|
+
the rendered stack, and linked rows support mouse clicks and keyboard activation.
|
|
343
|
+
|
|
344
|
+
A `changes` fence shows a commit's files as a card. Each row shows the file name
|
|
345
|
+
and +N −M. **Review** opens the Diff panel on all files; a row scrolls to that
|
|
346
|
+
file without expanding its unchanged lines.
|
|
347
|
+
An empty body (or `working`) means uncommitted changes.
|
|
348
|
+
|
|
349
|
+
Lines after the rev list the files to review, in order. The card shows those
|
|
350
|
+
first and folds the rest under a dimmed **N other files** row that expands and
|
|
351
|
+
collapses. Review opens the Diff panel in the same order. With no list, the card
|
|
352
|
+
shows every file.
|
|
353
|
+
|
|
354
|
+
List files a reviewer can skip after an `ignore:` line. They fold away with the
|
|
355
|
+
rest; with nothing to review, the card says no files are marked as important. When a commit's fence lists files, `serve` prints a warning naming each
|
|
356
|
+
changed file that is in neither list, so no file is left out by accident.
|
|
357
|
+
`serve` and `share` fail if a listed file is not changed in that commit.
|
|
358
|
+
|
|
359
|
+
````md
|
|
360
|
+
```changes
|
|
361
|
+
a1b2c3d
|
|
362
|
+
src/request.ts
|
|
363
|
+
src/validate.ts
|
|
364
|
+
|
|
365
|
+
ignore:
|
|
366
|
+
package-lock.json
|
|
367
|
+
```
|
|
368
|
+
````
|
|
369
|
+
|
|
370
|
+
References open in one shared panel beside the walkthrough. Selecting a stack
|
|
371
|
+
line or diagram element highlights it and scrolls the panel to the linked code
|
|
372
|
+
range. When a target has several references, buttons above the source viewer
|
|
373
|
+
select among them. On narrow windows the source panel sits below the walkthrough.
|
|
374
|
+
Documents without references keep the single-panel layout.
|
|
375
|
+
|
|
376
|
+
Malformed references produce a parse error.
|
|
377
|
+
|
|
378
|
+
On a GitHub-hosted spec, commit diffs come from the GitHub API. It returns patch
|
|
379
|
+
hunks only, so only lines near changes are reachable, and the Diff button opens
|
|
380
|
+
the pull request's full diff.
|
|
381
|
+
|
|
382
|
+
A shared gist is a snapshot taken when you run `product-doc share`. It saves every
|
|
383
|
+
referenced commit and every `changes` card, including uncommitted ones, to
|
|
384
|
+
`diffmap-changes.json`. It saves the current contents of every file that a file
|
|
385
|
+
excerpt or a reference without a commit reads to `diffmap-files.json`. In the
|
|
386
|
+
gist, those references open the saved file; symbols resolve to their first
|
|
387
|
+
matching line, and Cmd-click definitions only work in a local viewer. Commit
|
|
388
|
+
your work and point references at the commit before sharing, so the gist shows
|
|
389
|
+
the diff instead of a bare file.
|
|
390
|
+
|
|
391
|
+
Cmd-click (or Ctrl-click) a TypeScript or JavaScript symbol in the source panel
|
|
392
|
+
to open its definition. Use Back to retrace navigation and return to the reference.
|
|
393
|
+
Resolution uses the workspace's TypeScript configuration and current files.
|
|
394
|
+
|
|
395
|
+
Run `npx product-doc fixtures/annotations` for an example
|
|
396
|
+
with commit references, multiple files, and unchanged context.
|
|
397
|
+
|
|
398
|
+
## Animated service diagrams
|
|
399
|
+
|
|
400
|
+
A `services` fence shows services, their state, and the events they send each
|
|
401
|
+
other, then replays those events step by step. Readers press **Play**, step with
|
|
402
|
+
the arrow buttons or ← and →, or click the progress bar to jump to a step.
|
|
403
|
+
|
|
404
|
+
````md
|
|
405
|
+
```services
|
|
406
|
+
service Browser "login page"
|
|
407
|
+
state cookie = none
|
|
408
|
+
service API "HTTP server" [[src/api.ts]]
|
|
409
|
+
> Receives every request and routes it to a service.
|
|
410
|
+
service Auth
|
|
411
|
+
state attempts = 0
|
|
412
|
+
> Failures since the last success. Five locks the account.
|
|
413
|
+
|
|
414
|
+
start "Alice logs in"
|
|
415
|
+
> The API checks her password with Auth, then sets a session cookie.
|
|
416
|
+
step "The browser submits the form"
|
|
417
|
+
Browser -> API: POST /login
|
|
418
|
+
step "The API asks Auth to verify"
|
|
419
|
+
API -> Auth: verify(alice) [[src/api.ts#login]]
|
|
420
|
+
> Sends the username and the password from the form.
|
|
421
|
+
Auth.attempts = 1
|
|
422
|
+
> Counted before the check, so a crash still counts as a failure.
|
|
423
|
+
step "The API sets the session cookie"
|
|
424
|
+
API -> Browser: 200 Set-Cookie
|
|
425
|
+
Browser.cookie = sid=s_81f
|
|
426
|
+
```
|
|
427
|
+
````
|
|
428
|
+
|
|
429
|
+
- `service <Name> "label"` declares a service. Indent a `service` line under
|
|
430
|
+
another to nest it. Names are unique within the diagram.
|
|
431
|
+
- `state <key> = <value>` declares a value and its initial state. Indent it under
|
|
432
|
+
its service.
|
|
433
|
+
- `start "caption"` at column 0, before the first step, titles the whole
|
|
434
|
+
diagram, such as `start "Alice logs in"`. It stays in the title row while the
|
|
435
|
+
reader steps. A `>` line under it gives an overview of the whole process,
|
|
436
|
+
shown under the title until the first step. A `services` fence takes no
|
|
437
|
+
`[Title]`; the start caption is its title.
|
|
438
|
+
- `step "caption"` starts a step at column 0. The caption is required: a
|
|
439
|
+
sentence that says what happens, shown under the title row above the
|
|
440
|
+
controls. Indented lines
|
|
441
|
+
under it are `From -> To: label` events and `Service.key = value` updates.
|
|
442
|
+
A step's events travel one after another, in the order written, and the
|
|
443
|
+
updates land when the last one arrives.
|
|
444
|
+
- A `>` line adds text to the line above it. Indent it further than that line;
|
|
445
|
+
consecutive `>` lines join.
|
|
446
|
+
- Under a service or state, it is a description: the name gets a dotted
|
|
447
|
+
underline and the text shows in a tooltip on hover or focus.
|
|
448
|
+
- Under `start` or a step, it explains the caption and shows under it.
|
|
449
|
+
- Under an event or update, it is a note for that step. Notes appear in a
|
|
450
|
+
column beside the diagram once the step's events land, each joined by a
|
|
451
|
+
line to its event label or state row.
|
|
452
|
+
- Under a service name on its own line in a step, it is a note on that
|
|
453
|
+
service for the step, joined by a line to the service box.
|
|
454
|
+
- `%%` starts a comment line.
|
|
455
|
+
- Append `[[reference]]` to a `service` line or an event to link it to source.
|
|
456
|
+
|
|
457
|
+
Services must be declared before the first step, and updates may only change
|
|
458
|
+
declared state. [ELK](https://eclipse.dev/elk/) lays the services out left to
|
|
459
|
+
right, or top to bottom when that fits the column better, and routes one
|
|
460
|
+
connection between each pair of services that talk. A request and its reply
|
|
461
|
+
share that connection. Indentation is significant, so `services` has no MDC form.
|
|
462
|
+
See [the runnable examples](fixtures/services/README.md).
|
|
463
|
+
|
|
464
|
+
## Diagram diffs
|
|
465
|
+
|
|
466
|
+
Add `diff` after `mermaid` or `services` to show a change in one diagram.
|
|
467
|
+
Start every line with `-` for Today only, `+` for Proposed only, or a space
|
|
468
|
+
for both, as in a call stack diff. Indentation starts after that column.
|
|
469
|
+
|
|
470
|
+
````md
|
|
471
|
+
```mermaid diff
|
|
472
|
+
flowchart LR
|
|
473
|
+
Client --> Handler
|
|
474
|
+
- Handler --> Service
|
|
475
|
+
+ Handler --> Validate
|
|
476
|
+
+ Validate --> Service
|
|
477
|
+
```
|
|
478
|
+
````
|
|
479
|
+
|
|
480
|
+
productdoc draws every line once, so both versions share one layout. Nodes,
|
|
481
|
+
edges, sequence participants, and messages that only Today has are red and
|
|
482
|
+
dashed; those only Proposed has are green. A node whose label differs between
|
|
483
|
+
the versions is amber and shows its Proposed label. Each version must also be
|
|
484
|
+
a valid diagram on its own. To relabel a node, declare it on its own line
|
|
485
|
+
(`- B[Old]`, `+ B[New]`) so its edges are not drawn twice. In a diff,
|
|
486
|
+
`%% ref edge:<index>` counts edges as drawn: within each run of changed lines,
|
|
487
|
+
`+` lines come before `-` lines.
|
|
488
|
+
|
|
489
|
+
````md
|
|
490
|
+
```services diff
|
|
491
|
+
service API
|
|
492
|
+
- service SessionCache
|
|
493
|
+
- state active = 0
|
|
494
|
+
+ service Sessions
|
|
495
|
+
service Postgres
|
|
496
|
+
- state sessions = not used
|
|
497
|
+
+ state sessions = 0 rows
|
|
498
|
+
|
|
499
|
+
start "Sessions move to Postgres"
|
|
500
|
+
-step "API caches the session"
|
|
501
|
+
API -> SessionCache: create(alice)
|
|
502
|
+
SessionCache.active = 1
|
|
503
|
+
+step "Sessions writes the session"
|
|
504
|
+
API -> Sessions: create(alice)
|
|
505
|
+
Sessions -> Postgres: INSERT
|
|
506
|
+
Postgres.sessions = 1 row
|
|
507
|
+
```
|
|
508
|
+
````
|
|
509
|
+
|
|
510
|
+
In a `services diff`, lines inside a `-` or `+` service or step take its
|
|
511
|
+
sign. Today replays the unmarked and `-` lines and Proposed the unmarked and
|
|
512
|
+
`+` lines, so each state row shows Today's value struck through beside
|
|
513
|
+
Proposed's when they differ. A `-` and a `+` declaration of the same state key
|
|
514
|
+
give each version its own starting value. Added and removed steps color their
|
|
515
|
+
segment of the progress bar, and their caption starts with **Added** or
|
|
516
|
+
**Removed**. See [the runnable examples](fixtures/diagram-diffs/README.md).
|
|
517
|
+
|
|
518
|
+
## Link Mermaid nodes and edges
|
|
519
|
+
|
|
520
|
+
Inside a Mermaid fence, add `%% ref node:<id> [[reference]]` to link a node or
|
|
521
|
+
participant, or `%% ref edge:<index> [[reference]]` to link an edge or sequence
|
|
522
|
+
message. Edge indices start at zero in declaration order. The same file, symbol,
|
|
523
|
+
and commit references work here. Keep one directive per target; append
|
|
524
|
+
multiple references to that directive when needed.
|
|
525
|
+
|
|
526
|
+
````md
|
|
527
|
+
```mermaid
|
|
528
|
+
flowchart LR
|
|
529
|
+
A[ViewerApp] -->|Local mode only| B[CloseServerButton]
|
|
530
|
+
%% ref node:A [[src/viewer/ViewerApp.tsx#ViewerApp]]
|
|
531
|
+
%% ref node:B [[dae6b98:src/viewer/CloseServerButton.tsx#L8-L16]]
|
|
532
|
+
%% ref edge:0 [[dae6b98:src/viewer/ViewerApp.tsx#L219-L227]]
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
```mermaid
|
|
536
|
+
sequenceDiagram
|
|
537
|
+
participant App
|
|
538
|
+
participant Store
|
|
539
|
+
App->>Store: Save record
|
|
540
|
+
%% ref node:Store [[src/store.ts#Store]]
|
|
541
|
+
%% ref edge:0 [[src/store.ts#Store.save]]
|
|
542
|
+
```
|
|
543
|
+
````
|
|
544
|
+
|
|
545
|
+
Click a linked shape, edge line, or edge label, or focus it with Tab and press
|
|
546
|
+
Enter or Space. Directives are Mermaid comments, so they remain hidden and do
|
|
547
|
+
not change the diagram when rendered by other Mermaid tools. Missing diagram
|
|
548
|
+
targets display an error. See [the runnable example](fixtures/references/README.md).
|
|
549
|
+
|
|
550
|
+
## Link from prose
|
|
551
|
+
|
|
552
|
+
Write any reference in a paragraph, list item, or table cell, such as
|
|
553
|
+
`See [[src/store.ts#Store.save]] for the write path.` or
|
|
554
|
+
`Close server landed in [[dae6b98:src/viewer/CloseServerButton.tsx]].` It
|
|
555
|
+
renders as clickable inline code labeled with the file name and fragment
|
|
556
|
+
(`store.ts#Store.save`) and opens the same source panel. References inside code spans and link text stay
|
|
557
|
+
literal, so `` `[[path]]` `` shows the syntax itself.
|
|
558
|
+
|
|
559
|
+
## Telemetry
|
|
560
|
+
|
|
561
|
+
The CLI sends anonymous usage events to [PostHog](https://posthog.com): which commands run, whether `serve` started, which coding agent ran it, and which features of the local viewer get used. Events never include file paths, spec contents, comments, or anything else from your repository. [TELEMETRY.md](TELEMETRY.md) lists every event and field.
|
|
562
|
+
|
|
563
|
+
Turn it off with `DIFFMAP_TELEMETRY=0` (or `false`) or `DO_NOT_TRACK=1`. It is also off when `CI` is set.
|
|
564
|
+
|
|
565
|
+
## Feedback
|
|
566
|
+
|
|
567
|
+
Found a bug, hit a confusing error, or want a feature? [Open an issue](https://github.com/tanishqkancharla/diffmap/issues/new) with what you did, what you expected, what happened, and your productdoc version (`product-doc --version`). Agents using the generate-product-doc skill do the same through `gh issue create`.
|