feat: fill $PROJECT references with the reader's project ID

README.md

@@ -73,9 +73,9 @@ NAMESPACE="default"
 Rules:
 
 - Write the token exactly, in lowercase. Variants such as `my-project`, `my-project-id`, `<project-id>`, `<org-id>` or `ORG_ID` are not replaced.
-- `PROJECT_ID` and `$PROJECT_ID` are aliases of `your-project-id` and get the same value (the MetricsQL queries in the observability pages use `PROJECT_ID`). `${PROJECT_ID}`, `MY_PROJECT_ID` and `PROJECT_ID_2` are not replaced.
+- `PROJECT_ID`, `$PROJECT_ID` and `$PROJECT` are aliases of `your-project-id` and get the same value (the MetricsQL queries in the observability pages use `PROJECT_ID`). `${PROJECT_ID}`, `${PROJECT}`, `MY_PROJECT_ID`, `PROJECT_ID_2` and a bare `PROJECT` are not replaced, nor is `$PROJECT` on the left of an assignment (`$PROJECT = "your-project-id"`).
 - Don't wrap a token in `<…>`. Shiki reads `<` as a shell redirect and splits the token across several spans, so it can't be replaced.
-- Replace values only, never variable references: `PROJECT="your-project-id"` uses the token, `--project $PROJECT` stays.
+- Put the token in values, not in variable references: write `PROJECT="your-project-id"` and `--project $PROJECT`, never `--project your-project-id`. The reader's value still shows in `--project $PROJECT`, because `$PROJECT` is an alias.
 - Use `your-email` only for the reader's own account. Someone else's identity (an audit filter, an allowed-users list) keeps an example address like `alice@example.com`.
 - `ALB_NAME` is for a load balancer that already exists. For a name the reader makes up (`datumctl alb create`), write `NEW_ALB_NAME`, which is never replaced. With one load balancer, `ALB_NAME` is filled in. With several, nothing is filled until the reader picks one, and the pick applies to every `ALB_NAME` on the page.
 - Other placeholders (`INSTANCE_NAME`, `my-zone`, `example.com`) are fine. They are never replaced, so readers still swap them by hand.

docs-vars.js

@@ -16,13 +16,17 @@
   var VAR_CLASS = "datum-var";
   // A whole token only: `your-project-id-2` is someone's own name, not a token.
   // `$` and `{` before it are excluded so `${PROJECT_ID}` stays as written.
-  // `NEW_ALB_NAME` (a name the reader makes up) doesn't match.
+  // `$PROJECT` being assigned (PowerShell `$PROJECT = "your-project-id"`) stays
+  // too, or the copied code would read `my-project = "my-project"`.
   var TOKEN_PATTERN =
-    /(?<![\w${-])(your-org-id|your-project-id|your-email|\$PROJECT_ID|PROJECT_ID|ALB_NAME)(?![\w-])/g;
+    /(?<![\w${-])(your-org-id|your-project-id|your-email|\$PROJECT_ID|\$PROJECT(?!\s*=)|PROJECT_ID)(?![\w-])/g;
+  // Text past a node that the end-of-token checks may need (`$PROJECT    =`).
+  var LOOKAHEAD_CHARS = 32;
   // Other spellings that mean the same value as a token.
   var TOKEN_ALIASES = {
-    PROJECT_ID: "your-project-id",
-    $PROJECT_ID: "your-project-id",
+    PROJECT_ID: 'your-project-id',
+    $PROJECT_ID: 'your-project-id',
+    $PROJECT: 'your-project-id',
   };
   var canonicalToken = function (token) {
     return TOKEN_ALIASES[token] || token;
@@ -179,14 +183,17 @@
 
   // Keeps the original text node in place (trimmed to the text before the
   // first token) and adds the rest after it, so React still finds the node it
-  // rendered when it updates or removes the code block.
-  var fillTextNode = function (node, ctx) {
+  // rendered when it updates or removes the code block. `following` is the
+  // code's text after this node: Shiki splits `$PROJECT` and ` = ...` into
+  // separate spans, so the end-of-token checks need to see past the node.
+  var fillTextNode = function (node, values, following) {
     var text = node.nodeValue;
     var matches = [];
     var match;
     TOKEN_PATTERN.lastIndex = 0;
-    while ((match = TOKEN_PATTERN.exec(text))) {
-      if (isMarked(ctx, match[1])) matches.push(match);
+    while ((match = TOKEN_PATTERN.exec(text + following))) {
+      if (match.index + match[1].length > text.length) break;
+      if (values[match[1]]) matches.push(match);
     }
     if (!matches.length) return;
 
@@ -211,19 +218,21 @@
       // The hover card names the token in a <code> too; that one stays plain.
       var text = code.textContent;
       if (
-        (text.indexOf("your-") === -1 &&
-          text.indexOf("PROJECT_ID") === -1 &&
-          text.indexOf(ALB_TOKEN) === -1) ||
-        code.closest("#" + TIP_ID)
+        (text.indexOf('your-') === -1 && text.indexOf('PROJECT') === -1) ||
+        code.closest('#' + TIP_ID)
       ) {
         return;
       }
       var walker = document.createTreeWalker(code, NodeFilter.SHOW_TEXT);
       var nodes = [];
       while (walker.nextNode()) nodes.push(walker.currentNode);
-      nodes.forEach(function (node) {
-        if (!node.parentElement.closest("." + VAR_CLASS))
-          fillTextNode(node, ctx);
+      nodes.forEach(function (node, i) {
+        if (node.parentElement.closest('.' + VAR_CLASS)) return;
+        var following = '';
+        for (var j = i + 1; j < nodes.length && following.length < LOOKAHEAD_CHARS; j++) {
+          following += nodes[j].nodeValue;
+        }
+        fillTextNode(node, values, following);
       });
     });
   };