diff options
| -rw-r--r-- | README.md | 20 | ||||
| -rwxr-xr-x | scripts/setup.sh | 65 |
2 files changed, 60 insertions, 25 deletions
@@ -4,6 +4,19 @@ A complete guide to self-hosting Docsify with no external CDN dependencies. We f --- +## Quick Start + +If you just want a working site, run the bundled script from your document root. It performs every step in this guide automatically: it downloads and version-pins all assets, writes `index.html`, creates starter content, and generates a SHA-256 checksum manifest. + +```bash +cd /path/to/your/docroot +bash /path/to/scripts/setup.sh +``` + +Re-running is safe: it refreshes the vendored assets and regenerates `index.html`, but never overwrites your Markdown files (`README.md`, `_sidebar.md`, or any pages you have added). Everything below explains what the script does and how to perform each step by hand. + +--- + ## Prerequisites - Any static web server (Apache, nginx, Caddy, or similar) @@ -374,10 +387,13 @@ Since you are creating these files yourself, you already own them. Just ensure t are readable by your web server's user (e.g. `www-data`, `nginx`, or `caddy`): ```bash -find . -type f -exec chmod 644 {} \; -find . -type d -exec chmod 755 {} \; +find . -path './.*' -prune -o -type f -exec chmod 644 {} \; +find . -path './.*' -prune -o -type d -exec chmod 755 {} \; ``` +The `-path './.*' -prune` clause skips dotfiles and dotdirectories, so if your document +root is a Git repository these commands leave its `.git/` permissions untouched. + --- ## Serving the Site diff --git a/scripts/setup.sh b/scripts/setup.sh index 03f5c70..5d8c958 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -1,10 +1,10 @@ #!/usr/bin/env bash -# setup-docsify.sh — Bootstrap a self-hosted Docsify site (static files; serve with +# setup.sh — Bootstrap a self-hosted Docsify site (static files; serve with # any web server — Apache, nginx, Caddy, …). # # Run this script from your web server's document root: # cd /path/to/docroot -# bash setup-docsify.sh +# bash setup.sh # # Downloads Docsify core, the search plugin, the Vue theme, the copy-to-clipboard # plugin, extra Prism languages (bash, yaml, python, r), KaTeX math, Mermaid diagrams, @@ -24,13 +24,24 @@ set -euo pipefail 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 +FLEXIBLE_ALERTS_VERSION="1.3.0" +TABS_VERSION="1.6.3" +PAGINATION_VERSION="2.10.1" +MEDIUM_ZOOM_VERSION="1.1.0" +SIDEBAR_COLLAPSE_VERSION="1.3.5" +MERMAID_VERSION="11.15.0" +DOCSIFY_MERMAID_VERSION="2.0.1" +# Math plugin and its KaTeX renderer are coupled: the standalone KaTeX stylesheet/font +# version (KATEX_VERSION) MUST match the renderer bundled inside this docsify-katex +# release. docsify-katex 1.4.4 bundles KaTeX 0.11.1 (the 2.x line is broken). Bump the +# two together. +DOCSIFY_KATEX_VERSION="1.4.4" KATEX_VERSION="0.11.1" # ── Argument check ────────────────────────────────────────────────────────────── if [[ $# -gt 0 ]]; then echo "This script takes no options (got: $*)." >&2 - echo "Usage: bash setup-docsify.sh" >&2 + echo "Usage: bash setup.sh" >&2 exit 1 fi @@ -58,7 +69,7 @@ if [[ -f index.html ]]; then echo -e " ${RED}!${NC} index.html already exists in: $(pwd)" echo -e " This re-downloads assets and regenerates index.html (edits to" echo -e " index.html will be lost). Existing Markdown files are left untouched." - read -r -p " Continue? [y/N] " reply + read -r -p " Continue? [y/N] " reply || reply="" # EOF (non-interactive) -> treat as "no" [[ "${reply,,}" == "y" ]] || { echo "Aborted."; exit 0; } fi @@ -99,32 +110,39 @@ fetch "${CDN}/prismjs@${PRISM_VERSION}/components/prism-yaml.min.js" assets/j 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 -# assets/css/fonts/. Stylesheet + fonts are pinned to the bundled KaTeX (KATEX_VERSION). -fetch "${CDN}/docsify-katex@1.4.4/dist/docsify-katex.js" assets/js/docsify-katex.js +# Math: docsify-katex bundles the KaTeX renderer (version coupling is documented in the +# Configuration block above). KaTeX's stylesheet loads its fonts from ./fonts/ beside it, +# so the woff2 files go in assets/css/fonts/. Stylesheet + fonts are pinned to the bundled +# KaTeX (KATEX_VERSION). +fetch "${CDN}/docsify-katex@${DOCSIFY_KATEX_VERSION}/dist/docsify-katex.js" assets/js/docsify-katex.js fetch "${CDN}/katex@${KATEX_VERSION}/dist/katex.min.css" assets/css/katex.min.css -for f in $(grep -oE 'fonts/KaTeX_[^)]+\.woff2' assets/css/katex.min.css | sort -u); do +# Read the woff2 font list out of the stylesheet, then download each. Guard against an +# empty match: a future KaTeX bump could change the CSS format, which would otherwise +# silently ship a site whose math renders without fonts. +mapfile -t katex_fonts < <(grep -oE 'fonts/KaTeX_[^)]+\.woff2' assets/css/katex.min.css | sort -u) +[[ ${#katex_fonts[@]} -gt 0 ]] \ + || die "No KaTeX woff2 fonts found in katex.min.css; the CSS format may have changed for katex@${KATEX_VERSION}." +for f in "${katex_fonts[@]}"; do curl -sL --fail "${CDN}/katex@${KATEX_VERSION}/dist/$f" -o "assets/css/$f" \ || die "Failed to download: $f" done -ok "assets/css/fonts/ ($(ls -1 assets/css/fonts | wc -l) KaTeX woff2 files)" +ok "assets/css/fonts/ (${#katex_fonts[@]} 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 +fetch "${CDN}/docsify-plugin-flexible-alerts@${FLEXIBLE_ALERTS_VERSION}/dist/docsify-plugin-flexible-alerts.min.js" assets/js/docsify-plugin-flexible-alerts.min.js +fetch "${CDN}/docsify-tabs@${TABS_VERSION}/dist/docsify-tabs.min.js" assets/js/docsify-tabs.min.js +fetch "${CDN}/docsify-pagination@${PAGINATION_VERSION}/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 +fetch "${CDN}/medium-zoom@${MEDIUM_ZOOM_VERSION}/dist/medium-zoom.min.js" assets/js/medium-zoom.min.js +fetch "${CDN}/medium-zoom@${MEDIUM_ZOOM_VERSION}/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 +fetch "${CDN}/docsify-sidebar-collapse@${SIDEBAR_COLLAPSE_VERSION}/dist/docsify-sidebar-collapse.min.js" assets/js/docsify-sidebar-collapse.min.js +fetch "${CDN}/docsify-sidebar-collapse@${SIDEBAR_COLLAPSE_VERSION}/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 +fetch "${CDN}/mermaid@${MERMAID_VERSION}/dist/mermaid.min.js" assets/js/mermaid.min.js +fetch "${CDN}/docsify-mermaid@${DOCSIFY_MERMAID_VERSION}/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: @@ -248,9 +266,10 @@ EOF # ── Step 5: Permissions ───────────────────────────────────────────────────────── step "Step 5 — Setting file permissions" -find . -type f -exec chmod 644 {} \; -find . -type d -exec chmod 755 {} \; -ok "Files: 644 | Directories: 755" +# Prune dotfiles/dotdirs so a docroot that is a Git repo keeps its .git/ perms intact. +find . -path './.*' -prune -o -type f -exec chmod 644 {} \; +find . -path './.*' -prune -o -type d -exec chmod 755 {} \; +ok "Files: 644 | Directories: 755 (dotfiles left untouched)" # ── Verify ─────────────────────────────────────────────────────────────────────── step "Verifying file layout" |