Rewrite of system variables page to match new standards

[samironsoctopus]

This is probably a good test of our reviewer workflow too, since the group landed on GitHub as the place to review content.

[borland]

Why does a page have image and imageAlt?

[samironsoctopus]

These should power the open graph image. There is a fall back if there is no value. But the slot is there for high value pages that would need their own open graph image.

[borland]

I'm not up to speed with what "open graph image" means sorry.

In general, it's good not to leave empty things around; people either get confused by them (like I was), or mistake them for a bug and attempt to fill them in, which might break other things.

[borland]

🤖 Review by Claude (via Claude Code, requested by @orion-edwards)

I diffed the rewrite against main — including extracting every Octopus.* variable name from both versions to check for coverage gaps — and checked inbound links from the rest of the repo. The restructure into tables is a big readability win, and variable coverage is essentially complete. A few things need attention before merge.

---

🔴 1. Five inbound anchor links break

The old page carried explicit {#...} anchors that the rewrite dropped, and the headings were renamed, so the auto-generated slugs no longer match:

Linking file	Anchor used	New slug	Status
src/pages/docs/projects/ephemeral-environments/index.md:46	#release	#release-variables	❌
src/pages/docs/packaging-applications/package-repositories/index.md:47	#action	#action-variables	❌
src/pages/docs/releases/deployment-changes.md:33	#deployment-changes	#deployment-change-variables	❌
src/pages/docs/kubernetes/steps/kustomize.mdx:63	#reference-package-variables	#package-reference-variables	❌
src/pages/docs/projects/steps/conditions/index.mdx:65	#tracking-deployment-status	section deleted	❌
src/pages/docs/support/troubleshooting-failed-or-hanging-tasks.md:98	#user-modifiable-settings	#user-modifiable-settings	✅ (coincidence)

#older-versions, #release-package-build-information, #release-branch-information, #docker-image-package-variables, and #deployment-changes-templates also disappear. Nothing in the repo links to them, but they're the kind of thing that gets bookmarked and linked from support tickets and blog posts.

Cheapest fix: put the explicit {#release}, {#action}, {#deployment-changes}, {#reference-package-variables} anchors back on the new headings so old links keep resolving.

🔴 2. Indexed step/action notation is gone

The old "Tracking deployment status" section documented the indexer forms:

Octopus.Step[StepName].Status.Code / .Status.Error / .Status.ErrorDetail
Octopus.Action[ActionName].IsSkipped
Octopus.Action[ActionName].TargetRoles

The new page only has the unindexed current-step/current-action versions (lines 221, 242, 338–340). That's a real capability loss, not just prose — reading another step's status is the documented way to write run conditions, and conditions/index.mdx:65 links directly at that section to explain it.

Same pattern in Output variables: the old page had Octopus.Action[name].Output[machine].Package.InstallationDirectoryPath (machine indexer, for per-target output); line 321 now has only Octopus.Action[name].Output.Package.InstallationDirectoryPath.

Suggest a short note under Step/Action variables that indexer notation is available, plus keeping the {#tracking-deployment-status} anchor.

🔴 3. navOrder emptied and icon dropped

Frontmatter went from navOrder: 20 → navOrder: (blank). Every other page in docs/projects/variables/ has one (10, 18, 30, 40, 50, 60, 65, 70, 80, 90, 100, 110), and mdxContentCore.ts:284 sorts on it — a blank value will move this page in the sidebar and LLM surfaces. icon: fa-solid fa-desktop was also dropped; every sibling page has an icon.

---

🟡 Worth fixing

Line 16 — dropped word: "This page lists built-in Octopus provides for use in deployment processes" → "lists the built-in variables Octopus provides".

Lost cross-links. The old page linked out where the rewrite now just describes:

• Line 44: "build information has been pushed" → /docs/packaging-applications/build-servers/build-information; "project release notes" → /docs/releases/release-notes
• Output variables section: no link to /docs/projects/variables/output-variables (the old page had one), and it's not in Related links either — probably the single most relevant sibling page
• Intro no longer links the parent /docs/projects/variables/

Lost caveat on Octopus.Deployment.Error / ErrorDetail (lines 112–113). The old page had a hint explaining these only ever contain the exit code and Octopus stack trace — Octopus can't parse the deployment log, so they never show the underlying cause and you have to read the logs. The new one-line descriptions read as though the error text is in there, which will send people down the wrong path.

Whitespace. Everything from line 205 to EOF is indented by one space (191 lines), and line 343 is whitespace-only. I rendered a sample through the repo's own @astrojs/markdown-remark config to check — one space indent renders fine, so this is cosmetic, not a rendering bug. Still worth stripping so future diffs on this file stay readable.

🟡 Pre-existing, but this is the moment

Octopus.Acquire.MaxParallelism appears twice with contradictory descriptions — line 104 says "maximum number of packages deployed concurrently to multiple targets, default 10", line 409 says "maximum number of NuGet packages downloaded at once when acquiring packages, example 3". Both came across from the old page, which had the same conflict. One of them is wrong, or they need to be reconciled into a single entry.

Octopus.Action.MaxParallelism (224 / 410) and Octopus.Deployment.WorkerLeaseCap (126 / 423) are also duplicated across the two sections, though at least those agree with each other. A "see also" cross-reference would beat duplication.

🟡 New frontmatter fields

sidebarLabel, subject, type, audience, image, imageAlt — this is the only page in the repo using any of them, and I couldn't find theme code that reads them. Assuming that's intentional as part of the new standards and they're inert for now; flagging only so it's a deliberate choice rather than a surprise.

---

✅ What's good

• Table format is a genuine improvement over the old term-and-paragraph layout — far easier to scan ~200 variables
• Variable coverage holds up: I diffed the full extracted name lists and the only genuine losses are the indexer forms in §2
• Version info consolidated from scattered prose into one table, with OctopusShouldFailDeploymentOnSubstitutionFails (2025.1.0) correctly promoted out of an inline sentence
• Consistent "Example" column with realistic values
• cspell passes clean on the file

Nice work — the structural change is the right call. The anchors and the indexer notation are the two I'd treat as merge blockers.

[samironsoctopus]

Regarding changed subheadings: "Nothing in the repo links to them" is good enough for me. Any bookmarks that used an anchor will still land on the correct page, they just won't land on the correct subsection. I'm fine with that.

Don't know what happened with the leading whitespace, but good that the linter caught it.

I updated the content to include missing step/action notation caught by Claude review.

[team-marketing-branch-protections]

Pull request environment is available at https://stoctodocspr3275.z22.web.core.windows.net.

You can view the ephemeral environment status in Octopus Deploy.

This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity.

[borland]

I notice that the old version of this expressed the structure in JSON, whereas this is just tables now. The JSON helps make it much easier to see the structure and relationships, but sucks for describing the properties...

Anyway, in the description for Octopus.Release.Package above, you have "A collection of package objects". I think this heading should therefore be "Package object properties". It's subtle, but using the "Package object" term in both places ties them together in a way that "Package properties" doesn't

[borland]

I'll be honest. I stopped reading about halfway down the page; it looked reasonable enough and I'd bank on claude catching any minor mixups before I did. The content changes look good and the table format is much nicer than the eternally-scrolling list.

However, there is one major problem with the table approach, evidenced by this screenshot from the staging site, where the Description and Example columns are not visible at all.

What's happening:

• The layout specifies a fixed-with central content column of 800px
• The variable names are formatted as code with backticks. This means they don't wrap (which they shouldn't; wrapping would obscure the meaning)
• We have some quite long and verbose variable names, which consume almost the entire 800px width at the current font size
• The description and example columns don't fit within the 800px size. You have to scroll horizontally to see them, but modern macOS and windows don't show a horizontal scrollbar, so for all intents and purposes they're just gone 😢

I don't think we can ship this. We'll need to come up with some other way of presenting tables where the columns contain non-wrappable text

[borland]

The commit hash causes the example column on the table to be very wide and squash all the explanatory text. I think we should shorten it from 0c708fdec272bc4446c6cabea4f0022c2b616eba to 0c708f...6eba. Everyone knows what a commit hash is

[samironsoctopus]

Done.

[borland]

CustomInstallationDirectoryShouldBePurgedBeforeDeployment is super long and causes the column to push the other ones out of the visible area.

We could consider putting a <wbr> in the middle of the word, but it's awkward because it's just a single word. Unclear as to whether this would work or whether it'd be a good idea.

TreatConfigTransformationWarningsAsErrors below is also going to do it.

I feel like our max column width of 800x is too low. It's good for text, but for tables it's oppressive. Can we do something like min-width 800, max-width 1200 on the column, or style the tables so they can exceed the normal column bounds or something?

[borland]

Also, font-size reduction might help

[samironsoctopus]

I put a manual . This feels like an edge case. However, the design handover document specifies:
"Decorated code breaks onto next line at the dot OR capital letter, depending on if there's no dot for the break to occur before max width is reached. If there are no dots or capital letters, break occurs at max width."

[samironsoctopus]

That should probably be solved in the CSS, rather than with manual breaks. But the works for now. :)

[borland]

Decorated code breaks onto next line at the dot OR capital letter
...
That should probably be solved in the CSS, rather than with manual breaks

The problem is that CSS simply can't break words on capital letters.

[borland]

Also, font-size reduction might help

[borland]

As above, long value of 86B5C8E5553981FED961769B2DA3028C619596AC causes the table rendering to be wonky. Suggest 86B5C...96AC

[samironsoctopus]

Done

[borland]

As above, suggest shortening commit hash to 14677f...a1e9

[samironsoctopus]

Done

[borland]

Decorated code breaks onto next line at the dot OR capital letter
...
That should probably be solved in the CSS, rather than with manual breaks

The problem is that CSS simply can't break words on capital letters.

[borland]

Unfortunately you can't put tags inside code blocks

We could use a zero-width non-breaking space, however if someone copies and pastes the value, the ZWNBSP will end up in the pasted output and break their script so that's not great.

I'm not sure there's a solution here.

Maybe we just merge it and hope and pray that future changes to table formatting and font sizes will help?

[samironsoctopus]

What's wrong with:

word-break: normal;
overflow-wrap: anywhere;

On the <code> element?

[borland]

I saw the change to overflow-wrap: anywhere, and I understand the reason, given some of the giant long variable names that otherwise aren't wrappable.

But, that gets us this (screenshot from the staging site)

I don't think that's shippable :-(

[borland]

Rather than continuously kicking problems back to you I thought I'd try and fix it.

I've added a commit which uses explicit HTML to insert wbr's in the middle of some of the long words, e.g. <code>OctopusSuppressDuplicate<wbr>VariableWarning</code>

This is ugly to author, but we only need to do it in a handful of places and it works well. No tables overflow the horizontal area anymore.

I also piggybacked two other changes.

• Adding small horizontal padding to code blocks, per Mandy's comment here - this is also in alignment with the figma design, I just missed it earlier
• Reducing the font size for <code> blocks slightly. Note this is not the style that the figma design says to use. It calls for text.code.regular.medium which is actually bigger than the old font size. I used font.size.medium which, in my opinion, looks better as it's closer to the size of the surrounding non-monospace text.

Screenshot showing the explicit breaks on the very long words, plus the tweaks to the font

@samironsoctopus - see what you think, and merge when you're happy. Your call if we escalate the font size change up to Ellen or just take it