From b10d3e328b253e0a4c2ba4b729e2d730de1cf470 Mon Sep 17 00:00:00 2001 From: thediveo Date: Fri, 26 Jun 2026 19:22:43 +0000 Subject: [PATCH 1/2] refact: docsify use browser-sync instead of docsify-cli Signed-off-by: thediveo --- src/docsify/NOTES.md | 13 +++-- src/docsify/README.md | 22 ++++---- src/docsify/devcontainer-feature.json | 32 ++++++----- src/docsify/install.sh | 76 +++++++++++++-------------- test/docsify/debian.sh | 4 ++ test/docsify/fedora.sh | 4 ++ test/docsify/port_5678.sh | 3 -- test/docsify/scenarios.json | 21 +++++++- 8 files changed, 103 insertions(+), 72 deletions(-) create mode 100644 test/docsify/debian.sh create mode 100644 test/docsify/fedora.sh diff --git a/src/docsify/NOTES.md b/src/docsify/NOTES.md index 098a404..f7c933b 100644 --- a/src/docsify/NOTES.md +++ b/src/docsify/NOTES.md @@ -1,8 +1,3 @@ -## OS Support - -Tested only with -[mcr.microsoft.com/devcontainers/base:ubuntu](https://mcr.microsoft.com/en-us/artifact/mar/devcontainers/base/about#about:_ubuntu). - ## Docs Directory If the directory configured in the `docs-path` option does not exist, it is @@ -11,3 +6,11 @@ automatically created when the devcontainer starts. If the directory configured in the `docs-path` does not contain any `index.html`, both a starter `index.html` as well as `README.md` will be created. + +## OS Support + +Tested with: +- [ghcr.io/almalinux/almalinux](https://ghcr.io/almalinux/almalinux), +- [mcr.microsoft.com/devcontainers/base:debian](https://mcr.microsoft.com/en-us/artifact/mar/devcontainers/base/about#about:_debian), +- [fedora](https://hub.docker.com/_/fedora), +- [mcr.microsoft.com/devcontainers/base:ubuntu](https://mcr.microsoft.com/en-us/artifact/mar/devcontainers/base/about#about:_ubuntu). diff --git a/src/docsify/README.md b/src/docsify/README.md index d4f4557..a21687a 100644 --- a/src/docsify/README.md +++ b/src/docsify/README.md @@ -1,13 +1,13 @@ -# docsify (docsify) +# docsify server (docsify) -Automatically serves ./docs (or another) workspace directory via 'docsify serve' in the background. +Automatically serves ./docs (or another) workspace directory via 'browser-sync' in the background. ## Example Usage ```json "features": { - "ghcr.io/thediveo/devcontainer-features/docsify:0": {} + "ghcr.io/thediveo/devcontainer-features/docsify:1": {} } ``` @@ -16,13 +16,9 @@ Automatically serves ./docs (or another) workspace directory via 'docsify serve' | Options Id | Description | Type | Default Value | |-----|-----|-----|-----| | port | TCP port serving the docsified documentation | string | 3300 | -| livereload-port | TCP port to receive live reload events from | string | 3301 | | docs-path | workspace relative directory to serve from | string | docs | - -## OS Support - -Tested only with -[mcr.microsoft.com/devcontainers/base:ubuntu](https://mcr.microsoft.com/en-us/artifact/mar/devcontainers/base/about#about:_ubuntu). +| reload-delay | time in milliseconds to delay the reload event following file changes | string | 2000 | +| reload-debounce | time in milliseconds to restrict the frequency in which browser:reload events can be emitted to connected clients | string | 5000 | ## Docs Directory @@ -33,6 +29,14 @@ If the directory configured in the `docs-path` does not contain any `index.html`, both a starter `index.html` as well as `README.md` will be created. +## OS Support + +Tested with: +- [ghcr.io/almalinux/almalinux](https://ghcr.io/almalinux/almalinux), +- [mcr.microsoft.com/devcontainers/base:debian](https://mcr.microsoft.com/en-us/artifact/mar/devcontainers/base/about#about:_debian), +- [fedora](https://hub.docker.com/_/fedora), +- [mcr.microsoft.com/devcontainers/base:ubuntu](https://mcr.microsoft.com/en-us/artifact/mar/devcontainers/base/about#about:_ubuntu). + --- diff --git a/src/docsify/devcontainer-feature.json b/src/docsify/devcontainer-feature.json index 30b916b..de14d1c 100644 --- a/src/docsify/devcontainer-feature.json +++ b/src/docsify/devcontainer-feature.json @@ -1,8 +1,8 @@ { - "name": "docsify", + "name": "docsify server", "id": "docsify", - "version": "0.2.0", - "description": "Automatically serves ./docs (or another) workspace directory via 'docsify serve' in the background.", + "version": "1.0.0", + "description": "Automatically serves ./docs (or another) workspace directory via 'browser-sync' in the background.", "options": { "port": { "type": "string", @@ -10,23 +10,27 @@ "proposals": ["3300"], "default": "3300" }, - "livereload-port": { - "type": "string", - "description": "TCP port to receive live reload events from", - "proposals": ["3301"], - "default": "3301" - }, "docs-path": { "type": "string", "description": "workspace relative directory to serve from", "proposals": ["docs"], "default": "docs" + }, + "reload-delay": { + "type": "string", + "description": "time in milliseconds to delay the reload event following file changes", + "proposals": ["2000"], + "default": "2000" + }, + "reload-debounce": { + "type": "string", + "description": "time in milliseconds to restrict the frequency in which browser:reload events can be emitted to connected clients", + "proposals": ["5000"], + "default": "5000" } }, - "dependsOn": { - "ghcr.io/devcontainers/features/node:2": { - "version": "lts" - } - }, + "installsAfter": [ + "ghcr.io/devcontainers/features/node" + ], "postStartCommand": "/usr/local/bin/docsify-serve" } \ No newline at end of file diff --git a/src/docsify/install.sh b/src/docsify/install.sh index dfd7045..1227cc4 100755 --- a/src/docsify/install.sh +++ b/src/docsify/install.sh @@ -4,11 +4,14 @@ set -e DOCSIFY_SERVE_PATH="/usr/local/bin/docsify-serve" DOCSIFY_FALLBACK_PATH="/usr/local/share/docsify-serve/fallback" +PORT=${PORT:-3300} DOCS_PATH=${DOCS_PATH:-docs} +RELOAD_DELAY=${RELOAD_DELAY:2000} +RELOAD_DEBOUNCE=${RELOAD_DEBOUNCE:5000} -echo "Activating feature 'docsify-cli'..." +echo "Activating feature 'docsify'..." -npm install -g docsify-cli +npm -g install browser-sync mkdir -p "${DOCSIFY_FALLBACK_PATH}" cp fallback/index.html fallback/README.md "${DOCSIFY_FALLBACK_PATH}" @@ -18,10 +21,7 @@ cat <"${DOCSIFY_SERVE_PATH}" # we need to explicitly "activate" (the current) node here, as otherwise # devcontainers using our feature and also setting their remoteEnv PATH will -# cause our script to fail when run as the postStartCommand. Moreover, as this -# script will be run in a non-login shell using a plain "docker exec -it ...", -# we thus don't have the profile settings ready. - +# cause our script to fail when run as the postStartCommand. . /usr/local/share/nvm/nvm.sh nvm use node @@ -30,40 +30,38 @@ if [ ! -f "${DOCS_PATH}/index.html" ]; then cp ${DOCSIFY_FALLBACK_PATH}/* "${DOCS_PATH}" fi -# since this script is going to be executed as this feature's -# "postStartCommand" there is an important catch here: it is run via -# "docker exec -it ...". Please notice the absence of "-d" as this is a -# synchronous operation. Just using "nohup" as shown in several cases is -# a bad idea: when postStartCommand finishes, it tears down the nohup. -# Thus, use setsid(1) (https://man7.org/linux/man-pages/man1/setsid.1.html) -# to run the docsify serve node process in a new session. -echo "starting \"docsify serve\" in the background..." -LOGFILE=/tmp/nohup-feature-docsify.log +wait_for_process_logfile() { + local name=\$1 + local file=\$2 + local now=\$(date +%s) + local end=\$((now + 5)) + while true; do + if [ -s "\${file}" ]; then + echo "🚀 \${name} started" + break + fi + now=\$(date +%s) + if [ "\${now}" -ge "\${end}" ]; then + echo "❌ ERROR: \${name} did not start" + break + fi + sleep 0.25 + done +} + +# Start browser-sync in the background to serve the docsified contents, watching +# for changes, and triggering browser reloads. +BROWSYNC_LOGFILE=/tmp/nohup-feature-docsify.log setsid --fork bash -c "\ - docsify serve \ - -p=${PORT} \ - -P=${LIVERELOAD_PORT} \ + browser-sync \ + "${DOCS_PATH}" \ + --port ${PORT} \ + --reload-delay ${RELOAD_DELAY} \ + --reload-debounce ${RELOAD_DEBOUNCE} \ + --no-ui \ --no-open \ - ${DOCS_PATH} \ - >\${LOGFILE} 2>&1" -# wait for the background'ed bash running "docsify serve ..." to have created -# the log file, as at this point we're sure this bash process has been -# disassociated from the current session and will now not be affected any longer -# when we exit. -now=\$(date +%s) -end=\$((now + 5)) -while true; do - if [ -s "\${LOGFILE}" ]; then - echo "...docsify started" - break - fi - now=\$(date +%s) - if [ "\${now}" -ge "\${end}" ]; then - echo "ERROR: docsify didn't start" - break - fi - sleep 0.25 -done + -w \ + >\${BROWSYNC_LOGFILE} 2>&1" +wait_for_process_logfile "browser-sync" \${BROWSYNC_LOGFILE} EOF - chmod 0755 "${DOCSIFY_SERVE_PATH}" diff --git a/test/docsify/debian.sh b/test/docsify/debian.sh new file mode 100644 index 0000000..59f7c4d --- /dev/null +++ b/test/docsify/debian.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env bash +set -e + +. ./default.sh diff --git a/test/docsify/fedora.sh b/test/docsify/fedora.sh new file mode 100644 index 0000000..59f7c4d --- /dev/null +++ b/test/docsify/fedora.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env bash +set -e + +. ./default.sh diff --git a/test/docsify/port_5678.sh b/test/docsify/port_5678.sh index c28591a..6c8bf34 100755 --- a/test/docsify/port_5678.sh +++ b/test/docsify/port_5678.sh @@ -12,7 +12,4 @@ EOF ) check "serves at port 5678" bash -c "${CMD}" -check "serves live-reload at port 5679" bash -c \ - "lsof -nP -iTCP:5679 -sTCP:LISTEN | awk 'NR>1 {print \$2}' | sort -u | (read PID && ps -p \$PID -o cmd= | grep -q 'node')" - reportResults diff --git a/test/docsify/scenarios.json b/test/docsify/scenarios.json index a128e9d..0779251 100644 --- a/test/docsify/scenarios.json +++ b/test/docsify/scenarios.json @@ -2,21 +2,23 @@ "default": { "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { + "ghcr.io/devcontainers/features/node:2": {}, "docsify": {} } }, "port_5678": { "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { + "ghcr.io/devcontainers/features/node:2": {}, "docsify": { - "port": "5678", - "livereload-port": "5679" + "port": "5678" } } }, "docspath": { "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { + "ghcr.io/devcontainers/features/node:2": {}, "docsify": { "docs-path": "foobar" } @@ -25,6 +27,21 @@ "almalinux": { "image": "ghcr.io/almalinux/almalinux:10", "features":{ + "ghcr.io/devcontainers/features/node:2": {}, + "docsify": {} + } + }, + "debian": { + "image": "mcr.microsoft.com/devcontainers/base:debian-13", + "features": { + "ghcr.io/devcontainers/features/node:2": {}, + "docsify": {} + } + }, + "fedora": { + "image": "fedora", + "features": { + "ghcr.io/devcontainers/features/node:2": {}, "docsify": {} } } From ce28d05cdbd24fa34d553ebc2a2e797df3f6049e Mon Sep 17 00:00:00 2001 From: thediveo Date: Fri, 26 Jun 2026 19:23:19 +0000 Subject: [PATCH 2/2] chore: docs, use clearly visible emojis in log Signed-off-by: thediveo --- src/local-pkgsite/NOTES.md | 1 + src/local-pkgsite/README.md | 1 + src/local-pkgsite/install.sh | 4 ++-- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/local-pkgsite/NOTES.md b/src/local-pkgsite/NOTES.md index fc4f590..b6e3a9d 100644 --- a/src/local-pkgsite/NOTES.md +++ b/src/local-pkgsite/NOTES.md @@ -19,6 +19,7 @@ For example: } } ``` + ## OS Support Tested with: diff --git a/src/local-pkgsite/README.md b/src/local-pkgsite/README.md index 3aa5213..4a47893 100644 --- a/src/local-pkgsite/README.md +++ b/src/local-pkgsite/README.md @@ -40,6 +40,7 @@ For example: } } ``` + ## OS Support Tested with: diff --git a/src/local-pkgsite/install.sh b/src/local-pkgsite/install.sh index 64b267f..40ebd09 100644 --- a/src/local-pkgsite/install.sh +++ b/src/local-pkgsite/install.sh @@ -161,12 +161,12 @@ wait_for_process_logfile() { local end=\$((now + 5)) while true; do if [ -s "\${file}" ]; then - echo "...\${name} started" + echo "🚀 \${name} started" break fi now=\$(date +%s) if [ "\${now}" -ge "\${end}" ]; then - echo "ERROR: \${name} did not start" + echo "❌ ERROR: \${name} did not start" break fi sleep 0.25