fix: use /x/{slug} deep links for Lark example links

docs/plans/2026-03-23-001-fix-lark-deep-links-in-guide-pages-plan.md

@@ -0,0 +1,78 @@
+---
+title: "fix: Use /x/{slug} deep links for Lark example links in guide pages"
+type: fix
+status: completed
+date: 2026-03-23
+---
+
+# fix: Use /x/{slug} deep links for Lark example links in guide pages
+
+## Overview
+
+Guide pages in `site/content/guides/` have "Try it now" links that claim to open a specific example in Lark, but they all point to the bare root `https://lark.calcmark.org` instead of the deep-link URL `https://lark.calcmark.org/x/{slug}`. Users click expecting to see the named example but land on the Lark homepage instead.
+
+## Problem Statement
+
+Four guide pages name a specific example but link to the wrong URL:
+
+| Guide page | Link text | Current URL | Should be |
+|---|---|---|---|
+| `guides/system-sizing/_index.md:12` | "System Sizing example in Lark" | `https://lark.calcmark.org` | `https://lark.calcmark.org/x/system-sizing` |
+| `guides/business-planning/_index.md:10` | "Household Budget in Lark" | `https://lark.calcmark.org` | `https://lark.calcmark.org/x/household-budget` |
+| `guides/recipe-scaling/_index.md:14` | "Recipe Scaling example in Lark" | `https://lark.calcmark.org` | `https://lark.calcmark.org/x/recipe-scaling` |
+| `guides/unit-conversion/_index.md:9` | "Unit Conversion example in Lark" | `https://lark.calcmark.org` | No `unit-conversion` example exists — keep root link |
+
+Additionally, the Lark base URL (`https://lark.calcmark.org`) is hardcoded in 8+ locations across content and layouts with no centralized site param.
+
+## Proposed Solution
+
+### Part 1: Fix the deep links (required)
+
+Update three guide pages to use `/x/{slug}` deep links where a matching `calcmark_source` example exists:
+
+- `guides/system-sizing/_index.md` → `/x/system-sizing`
+- `guides/business-planning/_index.md` → `/x/household-budget`
+- `guides/recipe-scaling/_index.md` → `/x/recipe-scaling`
+
+For `guides/unit-conversion/_index.md`: no `unit-conversion` worked example exists (no `calcmark_source` frontmatter), so keep the root Lark link but update the link text to not imply a specific example will open. Change to generic "CalcMark Lark playground" phrasing.
+
+### Part 2: Create a `lark` shortcode (recommended)
+
+Create `site/layouts/shortcodes/lark.html` that generates Lark links with optional deep-link slug:
+
+```
+{{</* lark */>}}                          → https://lark.calcmark.org
+{{</* lark "system-sizing" */>}}          → https://lark.calcmark.org/x/system-sizing
+```
+
+This centralizes the base URL and makes `/x/` deep linking a first-class pattern. Convert the guide page links to use this shortcode.
+
+### Part 3: Add `larkURL` site param (recommended)
+
+Add `larkURL: "https://lark.calcmark.org"` to `hugo.yaml` params so all templates and shortcodes reference one source of truth. Update `section.html` and the new `lark` shortcode to use it.
+
+## Acceptance Criteria
+
+- [ ] `guides/system-sizing/_index.md` links to `https://lark.calcmark.org/x/system-sizing`
+- [ ] `guides/business-planning/_index.md` links to `https://lark.calcmark.org/x/household-budget`
+- [ ] `guides/recipe-scaling/_index.md` links to `https://lark.calcmark.org/x/recipe-scaling`
+- [ ] `guides/unit-conversion/_index.md` link text does not imply a specific example will open
+- [ ] New `lark` shortcode exists and supports optional slug parameter
+- [ ] `hugo.yaml` has `larkURL` param used by shortcode and `section.html`
+- [ ] `task site:build` succeeds (no broken shortcodes or template errors)
+- [ ] Existing pages that link to bare `lark.calcmark.org` in docs/ are optionally converted to shortcode
+
+## Context
+
+- The `/x/{slug}` pattern is already used in `site/layouts/_default/section.html:30` for "Edit live" buttons on example pages
+- The slug is derived from the `calcmark_source` filename: `path.BaseName "testdata/examples/system-sizing.cm"` → `system-sizing`
+- 10 worked examples have `calcmark_source` and get deep links automatically via the section template
+- The `guides/_index.md` root link is generic ("playground") and correct — no change needed
+- `docs/_index.md`, `docs/getting-started.md`, `docs/examples/_index.md` link to root Lark appropriately — no change needed
+
+## Sources
+
+- `site/layouts/_default/section.html:26-33` — existing `/x/{slug}` pattern
+- `site/layouts/shortcodes/` — 6 existing shortcodes (no Lark shortcode yet)
+- `site/hugo.yaml` — site config, no `larkURL` param currently
+- `docs/solutions/infrastructure/hugo-site-structure-from-scratch.md` — shortcode conventions

site/assets/css/components.css

@@ -91,6 +91,18 @@
   height: 1.1em;
 }
 
+/* Inline lark shortcode links */
+.lark-link {
+  white-space: nowrap;
+}
+
+.lark-link-icon {
+  width: 1em;
+  height: 1em;
+  vertical-align: -0.1em;
+  margin-right: 0.15em;
+}
+
 /* Theme toggle */
 .theme-toggle {
   background: none;

site/content/docs/_index.md

@@ -15,5 +15,5 @@ CalcMark is a calculation language that blends seamlessly with Markdown. Write y
 | Look up a specific feature | [User Guide](/docs/user-guide/) — task-oriented sub-pages |
 | Find the exact specification | [Language Reference](/docs/language-reference/) — formal spec with deep-linkable anchors |
 | Copy a working document | [Examples](/docs/examples/) — complete worked problems |
-| Try without installing | [CalcMark Lark](https://lark.calcmark.org) — browser playground |
+| Try without installing | {{< lark "" "CalcMark Lark" >}} — browser playground |
 | Contribute to CalcMark | [Contributing](/docs/contributing/) — architecture, development setup, conventions |

site/content/docs/examples/_index.md

@@ -4,7 +4,7 @@ summary: "Tutorials, worked examples, and feature references for CalcMark."
 weight: 900
 ---
 
-Each example page has a Larky icon you can click to open the file directly in [Lark](https://lark.calcmark.org), or copy the `cm remote` command to your terminal.
+Each example page has a Larky icon you can click to open the file directly in {{< lark "" "Lark" >}}, or copy the `cm remote` command to your terminal.
 
 ## Tutorials
 

site/content/docs/examples/embedded-datacenter-cost/_index.md

@@ -2,6 +2,7 @@
 title: "Embedded Datacenter Cost"
 summary: "CalcMark's embedded mode: live calculations inside a standard Markdown file, designed for Hugo and static-site pipelines."
 weight: 95
+calcmark_source: testdata/examples/embedded-datacenter-cost.md
 ---
 
 This example demonstrates **embedded mode** — CalcMark blocks inside a standard Markdown file. Instead of writing a `.cm` document, you write normal Markdown and tag calculation blocks with ` ```cm ` or ` ```calcmark `. Each block is evaluated independently, and the results replace the original block. Everything else passes through unchanged.

site/content/docs/getting-started.md

@@ -148,4 +148,4 @@ See [Sharing with GitHub Gist](/docs/user-guide/#sharing-gist) in the User Guide
 **Integrate:**
 - [Agent & API Integration](/docs/agent-integration/) — use CalcMark from code or AI agents
 - [Go Package](/docs/go-package/) — embed in your Go application
-- [CalcMark Lark](https://lark.calcmark.org) — try in your browser, no install needed
+- {{< lark "" "CalcMark Lark" >}} — try in your browser, no install needed

site/content/guides/_index.md

@@ -7,7 +7,7 @@ These tutorials teach CalcMark through real-world scenarios. Each one walks thro
 
 **New to CalcMark?** Start with [Getting Started](/docs/getting-started/) for installation and core concepts, then come back here.
 
-**Want to try without installing?** Open the [CalcMark Lark playground](https://lark.calcmark.org) in your browser and paste any example.
+**Want to try without installing?** Open the {{< lark "" "CalcMark Lark playground" >}} in your browser and paste any example.
 
 ### [System Sizing & Capacity Planning](/guides/system-sizing/)
 

site/content/guides/business-planning/_index.md

@@ -7,7 +7,7 @@ calcmark_build: progressive
 
 Revenue forecasts, cost breakdowns, margin analysis, budget health checks — financial models are just calculations embedded in narrative. CalcMark makes the narrative and the math live in one document.
 
-**Try it now:** Open the [Household Budget in Lark](https://lark.calcmark.org) or run `cm remote household-budget` in the editor.
+**Try it now:** Open the {{< lark "household-budget" "Household Budget in Lark" >}} or run `cm remote household-budget` in the editor.
 
 ---
 

site/content/guides/recipe-scaling/_index.md

@@ -11,7 +11,7 @@ calcmark_build: progressive
 
 A recipe is a CalcMark document waiting to happen — quantities with units, scaling by servings, cost per portion. CalcMark handles fractions (`2/3 cup`), measurement conventions (US vs Imperial), and document-wide scaling with a single frontmatter directive.
 
-**Try it now:** Open the [Recipe Scaling example in Lark](https://lark.calcmark.org) or run `cm remote recipe-scaling` in the editor.
+**Try it now:** Open the {{< lark "recipe-scaling" "Recipe Scaling example in Lark" >}} or run `cm remote recipe-scaling` in the editor.
 
 ---
 

site/content/guides/system-sizing/_index.md

@@ -9,7 +9,7 @@ How many servers do you need? How much bandwidth? What's the storage budget for
 
 CalcMark is built for this. Write your assumptions in plain text, let the math flow, and change any number to see the cascade.
 
-**Try it now:** Open the [System Sizing example in Lark](https://lark.calcmark.org) or run `cm remote system-sizing` in the editor.
+**Try it now:** Open the {{< lark "system-sizing" "System Sizing example in Lark" >}} or run `cm remote system-sizing` in the editor.
 
 ---
 

site/content/guides/unit-conversion/_index.md

@@ -6,7 +6,7 @@ weight: 40
 
 CalcMark knows about physical units — length, mass, volume, temperature, speed, energy, power, area, data sizes, force, impulse, pressure, acceleration, and frequency. You can convert between them with the `in` keyword, declare document-wide measurement conventions, and use inline qualifiers to be explicit about which definition you mean.
 
-**Try it now:** Open the [Unit Conversion example in Lark](https://lark.calcmark.org) or run `cm remote unit-conversion` in the editor.
+**Try it now:** Open the {{< lark "unit-conversion" "Unit Conversion example in Lark" >}} or run `cm remote unit-conversion` in the editor.
 
 ---
 

site/hugo.yaml

@@ -20,6 +20,7 @@ outputs:
 params:
   description: "Calculations embedded in Markdown documents."
   githubURL: "https://github.com/CalcMark/go-calcmark"
+  larkURL: "https://lark.calcmark.org"
   # Version is injected at build time via HUGO_PARAMS_version environment variable.
   # Falls back to "dev" for local builds.
   version: "dev"

site/layouts/_default/home.html

@@ -12,7 +12,7 @@ <h1 class="hero-headline">It&rsquo;s just Markdown.<br>Until it starts calculati
     <div class="hero-install">
       <pre class="install-cmd"><code>brew install calcmark/tap/calcmark</code></pre>
       <div class="hero-actions">
-        <a href="https://lark.calcmark.org" class="btn btn-primary btn-lark"><img src="{{ $larkColor.RelPermalink }}" alt="" class="btn-lark-icon" aria-hidden="true">Try it live!</a>
+        <a href="{{ site.Params.larkURL }}" class="btn btn-primary btn-lark"><img src="{{ $larkColor.RelPermalink }}" alt="" class="btn-lark-icon" aria-hidden="true">Try it live!</a>
         <a href="{{ "docs/getting-started/" | relURL }}" class="btn btn-secondary">Get Started</a>
         <a href="https://github.com/CalcMark/agent-skill" class="btn btn-secondary">Install for Your AI Agent</a>
       </div>

site/layouts/_default/section.html

@@ -27,7 +27,7 @@ <h1>{{ .Title }}<img src="{{ $lark.RelPermalink }}" alt="" class="page-lark" ari
     {{- $larkIcon := resources.Get "images/lark-color.svg" | fingerprint -}}
     {{- $slug := path.BaseName . -}}
     <div class="example-actions">
-      <a href="https://lark.calcmark.org/x/{{ $slug }}" class="btn btn-primary btn-lark" target="_blank" rel="noopener"><img src="{{ $larkIcon.RelPermalink }}" alt="" class="btn-lark-icon"> Edit live</a>
+      <a href="{{ site.Params.larkURL }}/x/{{ $slug }}" class="btn btn-primary btn-lark" target="_blank" rel="noopener"><img src="{{ $larkIcon.RelPermalink }}" alt="" class="btn-lark-icon"> Edit live</a>
       <span class="example-actions-or">or <a href="full/">view full document</a></span>
     </div>
     {{ end }}

site/layouts/partials/nav.html

@@ -12,7 +12,7 @@
          href="{{ .URL }}"{{ with .Params.external }} target="_blank" rel="noopener"{{ end }}>{{ .Name }}</a>
       {{ end }}
       <a class="nav-link nav-link--lark"
-         href="https://lark.calcmark.org" target="_blank" rel="noopener"><img src="{{ $larkColor.RelPermalink }}" alt="" class="nav-lark-icon" aria-hidden="true">Try it live</a>
+         href="{{ site.Params.larkURL }}" target="_blank" rel="noopener"><img src="{{ $larkColor.RelPermalink }}" alt="" class="nav-lark-icon" aria-hidden="true">Try it live</a>
     </nav>
     <button id="search-toggle" class="search-toggle" type="button" aria-label="Search">
       <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="6.5" cy="6.5" r="5"/><line x1="10" y1="10" x2="15" y2="15"/></svg>

site/layouts/shortcodes/lark.html

@@ -0,0 +1,12 @@
+{{- $base := site.Params.larkURL -}}
+{{- $slug := .Get 0 -}}
+{{- $text := .Get 1 -}}
+{{- $larkIcon := resources.Get "images/lark-color.svg" | fingerprint -}}
+{{- if $slug -}}
+  {{- $url := printf "%s/x/%s" $base $slug -}}
+  {{- $text = $text | default (printf "Open %s in Lark" $slug) -}}
+  <a href="{{ $url }}" class="lark-link" target="_blank" rel="noopener"><img src="{{ $larkIcon.RelPermalink }}" alt="" class="lark-link-icon" aria-hidden="true">{{ $text }}</a>
+{{- else -}}
+  {{- $text = $text | default "CalcMark Lark" -}}
+  <a href="{{ $base }}" class="lark-link" target="_blank" rel="noopener"><img src="{{ $larkIcon.RelPermalink }}" alt="" class="lark-link-icon" aria-hidden="true">{{ $text }}</a>
+{{- end -}}