From 28208c4068e88f187cca1deef4e94b3eebf64802 Mon Sep 17 00:00:00 2001 From: Dylan Thomas Date: Mon, 23 Mar 2026 16:55:41 -0600 Subject: [PATCH 1/3] fix: use /x/{slug} deep links for Lark example links in site content Guide pages linked to the bare lark.calcmark.org root instead of deep-linking to the specific example via /x/{slug}. Users clicking "System Sizing example in Lark" landed on the homepage, not the example. - Add larkURL param to hugo.yaml to centralize the Lark base URL - Create lark shortcode with optional slug for deep links - Fix 3 guide pages to deep-link: system-sizing, household-budget, recipe-scaling - Update unit-conversion guide text (no matching example exists) - Convert all remaining hardcoded lark.calcmark.org links in content and layouts to use the centralized param/shortcode Co-Authored-By: Claude Opus 4.6 (1M context) --- ...fix-lark-deep-links-in-guide-pages-plan.md | 78 +++++++++++++++++++ site/content/docs/_index.md | 2 +- site/content/docs/examples/_index.md | 2 +- site/content/docs/getting-started.md | 2 +- site/content/guides/_index.md | 2 +- .../guides/business-planning/_index.md | 2 +- site/content/guides/recipe-scaling/_index.md | 2 +- site/content/guides/system-sizing/_index.md | 2 +- site/content/guides/unit-conversion/_index.md | 2 +- site/hugo.yaml | 1 + site/layouts/_default/home.html | 2 +- site/layouts/_default/section.html | 2 +- site/layouts/partials/nav.html | 2 +- site/layouts/shortcodes/lark.html | 11 +++ 14 files changed, 101 insertions(+), 11 deletions(-) create mode 100644 docs/plans/2026-03-23-001-fix-lark-deep-links-in-guide-pages-plan.md create mode 100644 site/layouts/shortcodes/lark.html diff --git a/docs/plans/2026-03-23-001-fix-lark-deep-links-in-guide-pages-plan.md b/docs/plans/2026-03-23-001-fix-lark-deep-links-in-guide-pages-plan.md new file mode 100644 index 0000000..4c9441f --- /dev/null +++ b/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: + +``` +{{}} → https://lark.calcmark.org +{{}} → 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 diff --git a/site/content/docs/_index.md b/site/content/docs/_index.md index 9f7a316..eaa4c9b 100644 --- a/site/content/docs/_index.md +++ b/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 | diff --git a/site/content/docs/examples/_index.md b/site/content/docs/examples/_index.md index 11acb09..d4ac60a 100644 --- a/site/content/docs/examples/_index.md +++ b/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 diff --git a/site/content/docs/getting-started.md b/site/content/docs/getting-started.md index 77b182f..d764a50 100644 --- a/site/content/docs/getting-started.md +++ b/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 diff --git a/site/content/guides/_index.md b/site/content/guides/_index.md index c242189..ee325f2 100644 --- a/site/content/guides/_index.md +++ b/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/) diff --git a/site/content/guides/business-planning/_index.md b/site/content/guides/business-planning/_index.md index 4d11a07..cb7c750 100644 --- a/site/content/guides/business-planning/_index.md +++ b/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. --- diff --git a/site/content/guides/recipe-scaling/_index.md b/site/content/guides/recipe-scaling/_index.md index 03458eb..d102d51 100644 --- a/site/content/guides/recipe-scaling/_index.md +++ b/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. --- diff --git a/site/content/guides/system-sizing/_index.md b/site/content/guides/system-sizing/_index.md index c6801fc..9b4a7b1 100644 --- a/site/content/guides/system-sizing/_index.md +++ b/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. --- diff --git a/site/content/guides/unit-conversion/_index.md b/site/content/guides/unit-conversion/_index.md index 4dab5b0..e8c03b3 100644 --- a/site/content/guides/unit-conversion/_index.md +++ b/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:** Try it in the {{< lark "" "CalcMark Lark playground" >}} or run `cm remote unit-conversion` in the editor. --- diff --git a/site/hugo.yaml b/site/hugo.yaml index 87883fe..ffd7f95 100644 --- a/site/hugo.yaml +++ b/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" diff --git a/site/layouts/_default/home.html b/site/layouts/_default/home.html index 5e031ab..816ab6e 100644 --- a/site/layouts/_default/home.html +++ b/site/layouts/_default/home.html @@ -12,7 +12,7 @@

It’s just Markdown.
Until it starts calculati 
brew install calcmark/tap/calcmark
- Try it live! + Try it live! Get Started Install for Your AI Agent
diff --git a/site/layouts/_default/section.html b/site/layouts/_default/section.html index 24f81eb..645c448 100644 --- a/site/layouts/_default/section.html +++ b/site/layouts/_default/section.html @@ -27,7 +27,7 @@

{{ .Title }} - Edit live + Edit live or view full document

{{ end }} diff --git a/site/layouts/partials/nav.html b/site/layouts/partials/nav.html index 974b343..2575e9a 100644 --- a/site/layouts/partials/nav.html +++ b/site/layouts/partials/nav.html @@ -12,7 +12,7 @@ href="{{ .URL }}"{{ with .Params.external }} target="_blank" rel="noopener"{{ end }}>{{ .Name }} {{ end }} Try it live + href="{{ site.Params.larkURL }}" target="_blank" rel="noopener">Try it live