diff options
Diffstat (limited to 'scripts/setup.sh')
| -rwxr-xr-x | scripts/setup.sh | 77 |
1 files changed, 67 insertions, 10 deletions
diff --git a/scripts/setup.sh b/scripts/setup.sh index bdebe9b..f083c12 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -6,8 +6,10 @@ # bash setup-docsify.sh # # Downloads Docsify core, the search plugin, the Vue theme, the copy-to-clipboard -# plugin, extra Prism languages (bash, yaml, python, r), and KaTeX math rendering — -# all served locally, no external CDN dependencies at runtime. +# plugin, extra Prism languages (bash, yaml, python, r), KaTeX math, Mermaid diagrams, +# and UX plugins (alerts, tabs, pagination, image zoom, collapsible sidebar) — +# all served locally, no external CDN dependencies at runtime. Versions are pinned and +# a SHA-256 manifest (assets/SHA256SUMS) is written for reproducible, verifiable rebuilds. # # Re-running in an existing site is safe: it refreshes the assets and regenerates # index.html, but never overwrites Markdown files (README.md, _sidebar.md, and any @@ -16,8 +18,11 @@ set -euo pipefail # ── Configuration ─────────────────────────────────────────────────────────────── -# Use "4" for the latest 4.x release, or pin to a specific version e.g. "4.13.1" -DOCSIFY_VERSION="4" +# All versions are pinned exactly for reproducible, CDN-independent rebuilds. Bump a +# version here, re-run, and commit the refreshed assets/ + assets/SHA256SUMS. +DOCSIFY_VERSION="4.13.1" +PRISM_VERSION="1.30.0" +COPY_CODE_VERSION="3.0.2" # KaTeX stylesheet/font version — must match the renderer bundled in docsify-katex@1.4.4 KATEX_VERSION="0.11.1" @@ -82,16 +87,16 @@ fetch "${CDN}/docsify@${DOCSIFY_VERSION}/lib/plugins/search.min.js" assets/js/s fetch "${CDN}/docsify@${DOCSIFY_VERSION}/themes/vue.css" assets/css/vue.css # Copy-to-clipboard plugin (injects its own CSS — no separate stylesheet needed) -fetch "${CDN}/docsify-copy-code@3/dist/docsify-copy-code.min.js" assets/js/docsify-copy-code.min.js +fetch "${CDN}/docsify-copy-code@${COPY_CODE_VERSION}/dist/docsify-copy-code.min.js" assets/js/docsify-copy-code.min.js # Extra Prism languages. Docsify already bundles Prism core plus html/css/clike/ # javascript, so we only add the languages it does NOT ship. Never download # prism-core here — a standalone core replaces Docsify's Prism and silently breaks # highlighting for every language loaded after it. -fetch "${CDN}/prismjs@1/components/prism-bash.min.js" assets/js/prism-bash.min.js -fetch "${CDN}/prismjs@1/components/prism-yaml.min.js" assets/js/prism-yaml.min.js -fetch "${CDN}/prismjs@1/components/prism-python.min.js" assets/js/prism-python.min.js -fetch "${CDN}/prismjs@1/components/prism-r.min.js" assets/js/prism-r.min.js +fetch "${CDN}/prismjs@${PRISM_VERSION}/components/prism-bash.min.js" assets/js/prism-bash.min.js +fetch "${CDN}/prismjs@${PRISM_VERSION}/components/prism-yaml.min.js" assets/js/prism-yaml.min.js +fetch "${CDN}/prismjs@${PRISM_VERSION}/components/prism-python.min.js" assets/js/prism-python.min.js +fetch "${CDN}/prismjs@${PRISM_VERSION}/components/prism-r.min.js" assets/js/prism-r.min.js # Math: docsify-katex@1.4.4 bundles the KaTeX renderer (2.x is broken). KaTeX's # stylesheet loads its fonts from ./fonts/ beside it, so the woff2 files go in @@ -104,6 +109,29 @@ for f in $(grep -oE 'fonts/KaTeX_[^)]+\.woff2' assets/css/katex.min.css | sort - done ok "assets/css/fonts/ ($(ls -1 assets/css/fonts | wc -l) KaTeX woff2 files)" +# UX plugins — each loads after docsify; alerts/tabs/pagination inject their own CSS. +fetch "${CDN}/docsify-plugin-flexible-alerts@1.3.0/dist/docsify-plugin-flexible-alerts.min.js" assets/js/docsify-plugin-flexible-alerts.min.js +fetch "${CDN}/docsify-tabs@1.6.3/dist/docsify-tabs.min.js" assets/js/docsify-tabs.min.js +fetch "${CDN}/docsify-pagination@2.10.1/dist/docsify-pagination.min.js" assets/js/docsify-pagination.min.js +# Image zoom: medium-zoom is a generic library (a hook in index.html applies it) + its CSS +fetch "${CDN}/medium-zoom@1.1.0/dist/medium-zoom.min.js" assets/js/medium-zoom.min.js +fetch "${CDN}/medium-zoom@1.1.0/dist/style.css" assets/css/medium-zoom.css +# Collapsible sidebar — needs its own stylesheet +fetch "${CDN}/docsify-sidebar-collapse@1.3.5/dist/docsify-sidebar-collapse.min.js" assets/js/docsify-sidebar-collapse.min.js +fetch "${CDN}/docsify-sidebar-collapse@1.3.5/dist/sidebar.min.css" assets/css/sidebar.min.css + +# Diagrams: Mermaid (self-contained, ~3 MB) + docsify-mermaid, which turns ```mermaid +# fenced blocks into diagrams (it uses Mermaid v11's run() API). +fetch "${CDN}/mermaid@11.15.0/dist/mermaid.min.js" assets/js/mermaid.min.js +fetch "${CDN}/docsify-mermaid@2.0.1/dist/docsify-mermaid.js" assets/js/docsify-mermaid.js + +# Record SHA-256 checksums of every downloaded asset. Commit assets/ together with this +# manifest to rebuild without jsDelivr and to verify integrity later with: +# (cd assets && sha256sum -c SHA256SUMS) +( cd assets && find . -type f ! -name SHA256SUMS \( -name '*.js' -o -name '*.css' -o -name '*.woff2' \) \ + -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS ) +ok "assets/SHA256SUMS ($(wc -l < assets/SHA256SUMS) files)" + # ── Step 3: index.html ────────────────────────────────────────────────────────── step "Step 3 — Creating index.html" @@ -119,6 +147,8 @@ cat > index.html << 'HTML' <title>My Docs</title> <link rel="stylesheet" href="assets/css/vue.css"> <link rel="stylesheet" href="assets/css/katex.min.css"> + <link rel="stylesheet" href="assets/css/sidebar.min.css"> + <link rel="stylesheet" href="assets/css/medium-zoom.css"> </head> <body> <div id="app"></div> @@ -127,7 +157,15 @@ cat > index.html << 'HTML' name: 'My Docs', loadSidebar: true, // enables _sidebar.md subMaxLevel: 2, // auto-generate H2 entries in sidebar - search: 'auto' // enables the search plugin + search: 'auto', // enables the search plugin + plugins: [ + // medium-zoom: click an image in the content to enlarge it + function (hook) { + hook.doneEach(function () { + if (window.mediumZoom) mediumZoom('.markdown-section img'); + }); + } + ] } </script> <script src="assets/js/docsify.min.js"></script> @@ -140,6 +178,18 @@ cat > index.html << 'HTML' <script src="assets/js/prism-yaml.min.js"></script> <script src="assets/js/prism-python.min.js"></script> <script src="assets/js/prism-r.min.js"></script> + + <!-- UX plugins (callout boxes, tabs, prev/next pagination, image zoom, collapsible sidebar) --> + <script src="assets/js/docsify-plugin-flexible-alerts.min.js"></script> + <script src="assets/js/docsify-tabs.min.js"></script> + <script src="assets/js/docsify-pagination.min.js"></script> + <script src="assets/js/medium-zoom.min.js"></script> + <script src="assets/js/docsify-sidebar-collapse.min.js"></script> + + <!-- Diagrams: Mermaid + docsify integration (disable Mermaid's own auto-run) --> + <script src="assets/js/mermaid.min.js"></script> + <script src="assets/js/docsify-mermaid.js"></script> + <script>mermaid.initialize({ startOnLoad: false });</script> </body> </html> HTML @@ -217,3 +267,10 @@ echo -e "this setup adds bash, yaml, python, and r. To add more languages, downl echo -e "additional prism-<lang>.min.js files into assets/js/ and add their <script>" echo -e "tags to index.html. Copy-to-clipboard buttons are enabled on all code blocks." echo -e "LaTeX math renders via KaTeX (inline \$...\$ and block \$\$...\$\$)." +echo 'Mermaid diagrams render from ```mermaid fenced blocks.' +echo 'UX: callout boxes (> [!NOTE]), tabs, prev/next pagination, image zoom, and a' +echo 'collapsible sidebar are enabled.' +echo "" +echo -e "Asset versions are pinned and checksummed in assets/SHA256SUMS" +echo -e "(verify any time with: cd assets && sha256sum -c SHA256SUMS)." +echo -e "Commit assets/ to Git to rebuild without depending on jsDelivr." |