diff options
| -rw-r--r-- | README.md | 283 | ||||
| -rwxr-xr-x | scripts/setup.sh | 193 |
2 files changed, 476 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..4b32e46 --- /dev/null +++ b/README.md @@ -0,0 +1,283 @@ +# Docsify: Self-Hosted Setup on Apache 2 + +A complete guide to running Docsify on Apache 2 with no external CDN dependencies. We follow the [manual creation](https://docsify.js.org/#/quickstart?id=manual-initialization) but download the JavaScript and CSS files locally so we don't have to worry if the domain cdn.jsdelivr.net get seized (who knows what's going to happen in the future). + +--- + +## Prerequisites + +- Apache 2.4+ +- `curl` (for downloading assets) + +--- + +## Directory Structure + +The final layout this guide produces, relative to your document root: + +``` +./ +├── index.html ← Docsify entry point +├── README.md ← Homepage content +├── _sidebar.md ← Sidebar navigation +├── getting-started.md ← Example page +└── assets/ + ├── js/ + │ ├── docsify.min.js + │ └── search.min.js + └── css/ + └── vue.css +``` + +All commands in this guide assume you have already `cd`'d into your document root. + +--- + +## Step 1: Create the Directory Structure + +```bash +mkdir -p assets/js +mkdir -p assets/css +``` + +--- + +## Step 2: Download Docsify Assets + +All files are downloaded from jsDelivr once and served locally thereafter. See all [docsify CDN files](https://cdn.jsdelivr.net/npm/docsify@4/lib/) on jsDelivr. + +```bash +# Docsify core +curl -L "https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js" \ + -o assets/js/docsify.min.js + +# Search plugin +curl -L "https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js" \ + -o assets/js/search.min.js + +# Theme (Vue — clean, light) +curl -L "https://cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" \ + -o assets/css/vue.css +``` + +### Alternative Themes + +Replace `vue.css` in the command above with any of the following if preferred; see all [themes](https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/themes/). + +* buble.css +* dark.css +* dolphin.css +* pure.css +* vue.css + +### Optional: Syntax Highlighting + +If your documentation includes fenced code blocks, download Prism and the language components you need: + +```bash +# Prism core (required) +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 +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 +``` + +Then add each `<script>` tag for these files to `index.html` (see Step 3). + +--- + +## Step 3: Create `index.html` + +Create `index.html`: + +```html +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>My Docs</title> + <link rel="stylesheet" href="assets/css/vue.css"> +</head> +<body> + <div id="app"></div> + <script> + window.$docsify = { + name: 'My Docs', + loadSidebar: true, // enables _sidebar.md + subMaxLevel: 2, // auto-generate H2 entries in sidebar + search: 'auto' // enables the search plugin + } + </script> + <script src="assets/js/docsify.min.js"></script> + <script src="assets/js/search.min.js"></script> + + <!-- Remove the lines below if you did not download Prism --> + <script src="assets/js/prism-core.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> +</body> +</html> +``` + +> **Note:** Docsify uses hash-based routing by default, producing URLs like +> `/docs/#/page-name`. This requires no Apache configuration whatsoever. + +--- + +## Step 4: Create Boilerplate Content + +### Homepage — `README.md` + +Docsify uses `README.md` in each directory as its index page, just like GitHub. + +Create `README.md`: + +```markdown +# Welcome + +This is the home page of your documentation site. +Edit `README.md` to replace this content. + +## Quick Links + +- [Getting Started](getting-started.md) +``` + +### Sidebar — `_sidebar.md` + +The sidebar lists your pages and their navigation structure. + +Create `_sidebar.md`: + +```markdown +- [Home](/) +- [Getting Started](getting-started.md) +``` + +Add a new `- [Title](filename.md)` entry here each time you create a new page. + +### Example Page — `getting-started.md` + +Create `getting-started.md`: + +```markdown +# Getting Started + +This is an example page. Replace this content with your own documentation. + +## Section One + +Write your content here using standard Markdown. + +## Section Two + +Docsify will automatically generate sidebar anchors for H2 headings +when `subMaxLevel: 2` is set in `index.html`. +``` + +--- + +## Step 5: Set File Permissions + +Since you are creating these files yourself, you already own them. Just ensure they +are readable by Apache: + +```bash +find . -type f -exec chmod 644 {} \; +find . -type d -exec chmod 755 {} \; +``` + +--- + +## Apache Configuration + +No Apache configuration is required. Docsify's default hash-based routing means every +request is for a real file (`index.html`, a `.md` file, or an asset) — Apache serves +them as ordinary static files without any rewrite rules or special directives. + +--- + +## Verify the Setup + +After completing the steps above, confirm the file layout looks correct: + +```bash +find . -not -path '*/\.*' | sort +``` + +Expected output: + +``` +. +./README.md +./_sidebar.md +./assets +./assets/css +./assets/css/vue.css +./assets/js +./assets/js/docsify.min.js +./assets/js/search.min.js +./getting-started.md +./index.html +``` + +Then open `http://your-server/docs/` in a browser. You should see the rendered +homepage with a sidebar and search bar — no external requests are made. + +--- + +## Adding New Pages + +1. Create a `.md` file in the docs directory (or a subdirectory). +2. Add a corresponding entry to `_sidebar.md`. + +Example for a new page `reference.md`: + +```markdown +- [Home](/) +- [Getting Started](getting-started.md) +- [Reference](reference.md) +``` + +For subdirectories, nest entries with indentation: + +```markdown +- [Home](/) +- [Getting Started](getting-started.md) +- **Advanced** + - [Configuration](advanced/configuration.md) + - [Deployment](advanced/deployment.md) +``` + +--- + +## Upgrading Docsify + +Since files are self-hosted, upgrades are manual. Re-run the `curl` commands from +Step 2 with a specific version to update: + +```bash +# Pin to a specific version (replace 4.13.1 with the target version) +curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/docsify.min.js" \ + -o assets/js/docsify.min.js + +curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/plugins/search.min.js" \ + -o assets/js/search.min.js + +curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/themes/vue.css" \ + -o assets/css/vue.css +``` + +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 new file mode 100755 index 0000000..d3d188e --- /dev/null +++ b/scripts/setup.sh @@ -0,0 +1,193 @@ +#!/usr/bin/env bash +# setup-docsify.sh — Bootstrap a self-hosted Docsify site on Apache 2. +# +# Run this script from your Apache document root: +# cd /path/to/docroot +# bash setup-docsify.sh [--with-prism] +# +# Options: +# --with-prism Also download Prism and enable syntax highlighting in index.html + +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 + +# ── Argument parsing ──────────────────────────────────────────────────────────── +for arg in "$@"; do + case "$arg" in + --with-prism) PRISM=true ;; + *) echo "Unknown option: $arg" >&2; exit 1 ;; + esac +done + +# ── Output helpers ────────────────────────────────────────────────────────────── +GREEN='\033[0;32m' +BLUE='\033[0;34m' +RED='\033[0;31m' +BOLD='\033[1m' +NC='\033[0m' + +step() { echo -e "\n${BLUE}${BOLD}==> $1${NC}"; } +ok() { echo -e " ${GREEN}✓${NC} $1"; } +die() { echo -e " ${RED}✗${NC} $1" >&2; exit 1; } + +# ── Preflight checks ──────────────────────────────────────────────────────────── +step "Preflight checks" + +command -v curl &>/dev/null \ + || die "curl is required but not found. Install curl and try again." +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." + read -r -p " Continue? [y/N] " reply + [[ "${reply,,}" == "y" ]] || { echo "Aborted."; exit 0; } +fi + +echo -e " Working in: $(pwd)" + +# ── Step 1: Directories ───────────────────────────────────────────────────────── +step "Step 1 — Creating directory structure" + +mkdir -p assets/js assets/css +ok "assets/js/" +ok "assets/css/" + +# ── Step 2: Download Docsify assets ───────────────────────────────────────────── +step "Step 2 — Downloading Docsify assets" + +CDN="https://cdn.jsdelivr.net/npm" + +fetch() { + local url="$1" dest="$2" + curl -sL --fail "$url" -o "$dest" || die "Failed to download: $url" + 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 +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 + +# ── 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' +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>My Docs</title> + <link rel="stylesheet" href="assets/css/vue.css"> +</head> +<body> + <div id="app"></div> + <script> + window.$docsify = { + name: 'My Docs', + loadSidebar: true, // enables _sidebar.md + subMaxLevel: 2, // auto-generate H2 entries in sidebar + search: 'auto' // enables the search plugin + } + </script> + <script src="assets/js/docsify.min.js"></script> + <script src="assets/js/search.min.js"></script> +HTML_HEAD + + if [[ "$PRISM" == true ]]; then + cat << 'HTML_PRISM' + + <!-- Prism syntax highlighting --> + <script src="assets/js/prism-core.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' +</body> +</html> +HTML_FOOT +} > index.html + +ok "index.html" + +# ── Step 4: Boilerplate content ───────────────────────────────────────────────── +step "Step 4 — Creating boilerplate content" + +cat > README.md << 'EOF' +# Welcome + +This is the home page of your documentation site. +Edit `README.md` to replace this content. + +## Quick Links + +- [Getting Started](getting-started.md) +EOF +ok "README.md" + +cat > _sidebar.md << 'EOF' +- [Home](/) +- [Getting Started](getting-started.md) +EOF +ok "_sidebar.md" + +cat > getting-started.md << 'EOF' +# Getting Started + +This is an example page. Replace this content with your own documentation. + +## Section One + +Write your content here using standard Markdown. + +## Section Two + +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" + +find . -type f -exec chmod 644 {} \; +find . -type d -exec chmod 755 {} \; +ok "Files: 644 | Directories: 755" + +# ── Verify ─────────────────────────────────────────────────────────────────────── +step "Verifying file layout" + +find . -not -path '*/\.*' | sort + +# ── Done ───────────────────────────────────────────────────────────────────────── +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 |