docs(nx-dev): improve docs for special syntax in nx.json (#15085)

docs/shared/concepts/how-caching-works.md

@@ -72,9 +72,16 @@ We can define a more precise configuration as follows:
 }
 ```
 
-{% callout type="note" title="{projectRoot}" %}
-`{projectRoot}` is a key word that is replaced by the path to the current project's root directory.
+<!-- Prettier causes the callout block to break -->
+<!-- prettier-ignore-start -->
+
+{% callout type="note" title="Special Syntax Explained" %}
+
+- `{projectRoot}` is a key word that is replaced by the path to the current project's root directory.
+- `{workspaceRoot}` is a key word that is replaced by the root path of your workspace.
+- The `^` symbol means "of dependencies", i.e. `"^production"` means match the files defined for the `"production"` `namedInput`, but for all projects which the current project depends on.
 {% /callout %}
+<!-- prettier-ignore-end -->
 
 With this configuration, the build script will only consider the non-test files of `remixapp`, `header` and `footer`.
 The test script will consider all the source files for the project under test and only non-test files of its

nx-dev/ui-markdoc/src/index.ts

@@ -1,4 +1,4 @@
-import { Node, parse, renderers, transform } from '@markdoc/markdoc';
+import { Node, parse, renderers, Tokenizer, transform } from '@markdoc/markdoc';
 import { load as yamlLoad } from 'js-yaml';
 import React, { ReactNode } from 'react';
 import { Fence } from './lib/nodes/fence.component';
@@ -79,8 +79,15 @@ export const getMarkdocCustomConfig = (
   },
 });
 
-export const parseMarkdown: (markdown: string) => Node = (markdown) =>
-  parse(markdown);
+const tokenizer = new Tokenizer({
+  // Per https://markdoc.dev/docs/syntax#comments this will be on by default in a future version
+  allowComments: true,
+});
+
+export const parseMarkdown: (markdown: string) => Node = (markdown) => {
+  const tokens = tokenizer.tokenize(markdown);
+  return parse(tokens);
+};
 
 export const renderMarkdown: (
   documentContent: string,