diff options
| -rw-r--r-- | README.md | 69 | ||||
| -rwxr-xr-x | scripts/setup.sh | 137 |
2 files changed, 117 insertions, 89 deletions
@@ -24,7 +24,15 @@ The final layout this guide produces, relative to your document root: └── assets/ ├── js/ │ ├── docsify.min.js - │ └── search.min.js + │ ├── search.min.js + │ ├── docsify-copy-code.min.js + │ ├── prism-core.min.js + │ ├── prism-clike.min.js + │ ├── prism-javascript.min.js + │ ├── prism-bash.min.js + │ ├── prism-yaml.min.js + │ ├── prism-python.min.js + │ └── prism-r.min.js └── css/ └── vue.css ``` @@ -70,33 +78,49 @@ Replace `vue.css` in the command above with any of the following if preferred; s * pure.css * vue.css -### Optional: Syntax Highlighting +### Syntax Highlighting (Prism) -If your documentation includes fenced code blocks, download Prism and the language components you need: +Download the Prism highlighting engine and its language components. The core engine +ships **no languages on its own**, so each language is a separate file. Note that +`prism-clike.min.js` is the base grammar that `prism-javascript.min.js` extends, so it +must be downloaded and loaded **before** javascript (see Step 3). ```bash -# Prism core (required) +# Prism core engine (no languages on its own) curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js" \ -o assets/js/prism-core.min.js -# Language components — add as many as needed +# clike — base grammar required by javascript +curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-clike.min.js" \ + -o assets/js/prism-clike.min.js + +# Language components +curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js" \ + -o assets/js/prism-javascript.min.js + curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js" \ -o assets/js/prism-bash.min.js curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js" \ -o assets/js/prism-yaml.min.js -curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js" \ - -o assets/js/prism-javascript.min.js +curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-python.min.js" \ + -o assets/js/prism-python.min.js + +curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-r.min.js" \ + -o assets/js/prism-r.min.js ``` -Then add each `<script>` tag for these files to `index.html` (see Step 3). +To highlight more languages, download additional `prism-<lang>.min.js` files (browse the +[Prism components](https://cdn.jsdelivr.net/npm/prismjs@1/components/)) and add a matching +`<script>` tag in Step 3. Some languages extend others — anything built on `clike` (e.g. +javascript) must load after `prism-clike.min.js`. -### Optional: Copy-to-Clipboard Button +### Copy-to-Clipboard Button -To add a **copy** button to every fenced code block, download the -[docsify-copy-code](https://github.com/jperasmus/docsify-copy-code) plugin. As with -the assets above, it is fetched once and served locally thereafter: +Add a **copy** button to every fenced code block with the +[docsify-copy-code](https://github.com/jperasmus/docsify-copy-code) plugin. Like the +assets above, it is fetched once and served locally thereafter: ```bash # Copy-to-clipboard plugin @@ -148,15 +172,16 @@ Create `index.html`: </script> <script src="assets/js/docsify.min.js"></script> <script src="assets/js/search.min.js"></script> - - <!-- Remove the line below if you did not download the copy-code plugin --> <script src="assets/js/docsify-copy-code.min.js"></script> - <!-- Remove the lines below if you did not download Prism --> + <!-- Prism: core engine first, then clike (required by javascript), then languages --> <script src="assets/js/prism-core.min.js"></script> + <script src="assets/js/prism-clike.min.js"></script> + <script src="assets/js/prism-javascript.min.js"></script> <script src="assets/js/prism-bash.min.js"></script> <script src="assets/js/prism-yaml.min.js"></script> - <script src="assets/js/prism-javascript.min.js"></script> + <script src="assets/js/prism-python.min.js"></script> + <script src="assets/js/prism-r.min.js"></script> </body> </html> ``` @@ -257,7 +282,15 @@ Expected output: ./assets/css ./assets/css/vue.css ./assets/js +./assets/js/docsify-copy-code.min.js ./assets/js/docsify.min.js +./assets/js/prism-bash.min.js +./assets/js/prism-clike.min.js +./assets/js/prism-core.min.js +./assets/js/prism-javascript.min.js +./assets/js/prism-python.min.js +./assets/js/prism-r.min.js +./assets/js/prism-yaml.min.js ./assets/js/search.min.js ./getting-started.md ./index.html @@ -310,5 +343,9 @@ curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/themes/vue.css" \ -o assets/css/vue.css ``` +The Prism components (`prismjs@1`) and the copy-code plugin (`docsify-copy-code@3`) +are versioned independently of Docsify; re-run their Step 2 commands with a pinned +version number the same way when you want to update them. + Check the [Docsify releases page](https://github.com/docsifyjs/docsify/releases) for the latest version number before upgrading. diff --git a/scripts/setup.sh b/scripts/setup.sh index ab24775..a404eae 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -3,38 +3,40 @@ # # Run this script from your Apache document root: # cd /path/to/docroot -# bash setup-docsify.sh [--with-prism] [--with-copy-code] +# bash setup-docsify.sh # -# Options: -# --with-prism Also download Prism and enable syntax highlighting in index.html -# --with-copy-code Also download the docsify-copy-code plugin (copy button on code blocks) +# Downloads Docsify core, the search plugin, the Vue theme, the copy-to-clipboard +# plugin, and Prism syntax highlighting (bash, yaml, javascript, python, r) — all +# served locally, no external CDN dependencies at runtime. +# +# 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 +# pages you have added) that already exist. 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" -PRISM=false -COPY_CODE=false -# ── Argument parsing ──────────────────────────────────────────────────────────── -for arg in "$@"; do - case "$arg" in - --with-prism) PRISM=true ;; - --with-copy-code) COPY_CODE=true ;; - *) echo "Unknown option: $arg" >&2; exit 1 ;; - esac -done +# ── Argument check ────────────────────────────────────────────────────────────── +if [[ $# -gt 0 ]]; then + echo "This script takes no options (got: $*)." >&2 + echo "Usage: bash setup-docsify.sh" >&2 + exit 1 +fi # ── Output helpers ────────────────────────────────────────────────────────────── GREEN='\033[0;32m' BLUE='\033[0;34m' +YELLOW='\033[0;33m' RED='\033[0;31m' BOLD='\033[1m' NC='\033[0m' step() { echo -e "\n${BLUE}${BOLD}==> $1${NC}"; } ok() { echo -e " ${GREEN}✓${NC} $1"; } +skip() { echo -e " ${YELLOW}•${NC} $1"; } die() { echo -e " ${RED}✗${NC} $1" >&2; exit 1; } # ── Preflight checks ──────────────────────────────────────────────────────────── @@ -46,7 +48,8 @@ ok "curl $(curl --version | head -1 | awk '{print $2}')" if [[ -f index.html ]]; then echo -e " ${RED}!${NC} index.html already exists in: $(pwd)" - echo -e " This script will overwrite index.html and all boilerplate .md files." + 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 [[ "${reply,,}" == "y" ]] || { echo "Aborted."; exit 0; } fi @@ -71,33 +74,30 @@ fetch() { ok "$dest" } -fetch "${CDN}/docsify@${DOCSIFY_VERSION}/lib/docsify.min.js" assets/js/docsify.min.js -fetch "${CDN}/docsify@${DOCSIFY_VERSION}/lib/plugins/search.min.js" assets/js/search.min.js +# Core Docsify, search plugin, and theme +fetch "${CDN}/docsify@${DOCSIFY_VERSION}/lib/docsify.min.js" assets/js/docsify.min.js +fetch "${CDN}/docsify@${DOCSIFY_VERSION}/lib/plugins/search.min.js" assets/js/search.min.js fetch "${CDN}/docsify@${DOCSIFY_VERSION}/themes/vue.css" assets/css/vue.css -if [[ "$PRISM" == true ]]; then - echo "" - echo " Downloading Prism syntax highlighting..." - fetch "${CDN}/prismjs@1/components/prism-core.min.js" assets/js/prism-core.min.js - 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-javascript.min.js" assets/js/prism-javascript.min.js -fi +# 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 -if [[ "$COPY_CODE" == true ]]; then - echo "" - echo " Downloading copy-to-clipboard plugin..." - fetch "${CDN}/docsify-copy-code@3/dist/docsify-copy-code.min.js" assets/js/docsify-copy-code.min.js -fi +# Prism syntax highlighting: core engine, then clike (required by javascript), +# then the individual languages. +fetch "${CDN}/prismjs@1/components/prism-core.min.js" assets/js/prism-core.min.js +fetch "${CDN}/prismjs@1/components/prism-clike.min.js" assets/js/prism-clike.min.js +fetch "${CDN}/prismjs@1/components/prism-javascript.min.js" assets/js/prism-javascript.min.js +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 # ── Step 3: index.html ────────────────────────────────────────────────────────── step "Step 3 — Creating index.html" -# index.html is assembled in parts so the Prism <script> block can be -# included or omitted cleanly. The heredoc delimiters are single-quoted -# ('HTML_HEAD') to prevent the shell from expanding $docsify. -{ - cat << 'HTML_HEAD' +# The heredoc delimiter is single-quoted ('HTML') so the shell does not expand +# $docsify inside the template. +cat > index.html << 'HTML' <!DOCTYPE html> <html lang="en"> <head> @@ -119,39 +119,40 @@ step "Step 3 — Creating index.html" </script> <script src="assets/js/docsify.min.js"></script> <script src="assets/js/search.min.js"></script> -HTML_HEAD - - if [[ "$COPY_CODE" == true ]]; then - cat << 'HTML_COPYCODE' - - <!-- Copy-to-clipboard button for code blocks --> <script src="assets/js/docsify-copy-code.min.js"></script> -HTML_COPYCODE - fi - - if [[ "$PRISM" == true ]]; then - cat << 'HTML_PRISM' - <!-- Prism syntax highlighting --> + <!-- Prism: core engine first, then clike (required by javascript), then languages --> <script src="assets/js/prism-core.min.js"></script> + <script src="assets/js/prism-clike.min.js"></script> + <script src="assets/js/prism-javascript.min.js"></script> <script src="assets/js/prism-bash.min.js"></script> <script src="assets/js/prism-yaml.min.js"></script> - <script src="assets/js/prism-javascript.min.js"></script> -HTML_PRISM - fi - - cat << 'HTML_FOOT' + <script src="assets/js/prism-python.min.js"></script> + <script src="assets/js/prism-r.min.js"></script> </body> </html> -HTML_FOOT -} > index.html +HTML ok "index.html" # ── Step 4: Boilerplate content ───────────────────────────────────────────────── -step "Step 4 — Creating boilerplate content" +step "Step 4 — Boilerplate content (created only if missing)" + +# Write the heredoc on stdin to $1, but never clobber an existing file — so +# re-running refreshes the assets and index.html without touching your content. +write_boilerplate() { + local dest="$1" + local content + content="$(cat)" + if [[ -e "$dest" ]]; then + skip "$dest (exists — left unchanged)" + else + printf '%s\n' "$content" > "$dest" + ok "$dest" + fi +} -cat > README.md << 'EOF' +write_boilerplate README.md << 'EOF' # Welcome This is the home page of your documentation site. @@ -161,15 +162,13 @@ Edit `README.md` to replace this content. - [Getting Started](getting-started.md) EOF -ok "README.md" -cat > _sidebar.md << 'EOF' +write_boilerplate _sidebar.md << 'EOF' - [Home](/) - [Getting Started](getting-started.md) EOF -ok "_sidebar.md" -cat > getting-started.md << 'EOF' +write_boilerplate getting-started.md << 'EOF' # Getting Started This is an example page. Replace this content with your own documentation. @@ -183,7 +182,6 @@ Write your content here using standard Markdown. Docsify will automatically generate sidebar anchors for H2 headings when `subMaxLevel: 2` is set in `index.html`. EOF -ok "getting-started.md" # ── Step 5: Permissions ───────────────────────────────────────────────────────── step "Step 5 — Setting file permissions" @@ -201,15 +199,8 @@ find . -not -path '*/\.*' | sort echo "" echo -e "${GREEN}${BOLD}Setup complete.${NC}" echo -e "Open your site in a browser to verify." - -if [[ "$PRISM" == true ]]; then - echo "" - echo -e "Prism is enabled for: bash, yaml, javascript." - echo -e "To add more languages, download additional prism-*.min.js files" - echo -e "into assets/js/ and add their <script> tags to index.html." -fi - -if [[ "$COPY_CODE" == true ]]; then - echo "" - echo -e "Copy-to-clipboard buttons are enabled on all code blocks." -fi +echo "" +echo -e "Syntax highlighting (Prism) is enabled for: bash, yaml, javascript, python, r." +echo -e "To add more languages, download additional prism-*.min.js files into" +echo -e "assets/js/ and add their <script> tags to index.html (after prism-core.min.js)." +echo -e "Copy-to-clipboard buttons are enabled on all code blocks." |