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

README.md

@@ -72,9 +72,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`.
 - Other placeholders (`ALB_NAME`, `INSTANCE_NAME`, `my-zone`, `example.com`) are fine. They are never replaced, so readers still swap them by hand.
 - Prose that explains flag syntax, like ``--project <project>``, can keep the angle brackets. It isn't a value to copy.

docs-vars.js

@@ -14,12 +14,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.
+  // `$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)(?![\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: 'your-project-id',
   };
   var canonicalToken = function (token) {
     return TOKEN_ALIASES[token] || token;
@@ -108,13 +113,16 @@
 
   // 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, values) {
+  // 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))) {
+    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;
@@ -140,16 +148,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('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, values);
+      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);
       });
     });
   };