Develop

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).

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).
+
 
 ---
 

src/docsify/devcontainer-feature.json

@@ -1,32 +1,36 @@
 {
-    "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",
             "description": "TCP port serving the docsified documentation",
             "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"
 }

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 <<EOF >"${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}"

src/local-pkgsite/NOTES.md

@@ -19,6 +19,7 @@ For example:
     }
 }
 ```
+
 ## OS Support
 
 Tested with:

src/local-pkgsite/README.md

@@ -40,6 +40,7 @@ For example:
     }
 }
 ```
+
 ## OS Support
 
 Tested with:

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

test/docsify/debian.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -e
+
+. ./default.sh

test/docsify/fedora.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -e
+
+. ./default.sh

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

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": {}
         }
     }