docs(workbooks): document reference line labels and their placement controls

[igorlukanin]

Summary

• The reference-line docs already described a Label field that the product did not have. Cube Cloud now supports one, so this makes the existing prose true and documents what ships alongside it.
• Adds a Reference line labels subsection to the Axes page: the free-text label, the two placement controls (horizontal start / middle / end, vertical above / below), the end/above defaults, and the fact that the label takes the line's colour.
• Notes that a label on a line near the top or bottom of the plot flips to the other side of the line automatically, so the text stays inside the chart area.
• Extends the line-chart page's one-line reference to mention the placement controls.

Test plan

• Rendered locally with mint dev; both pages return 200 and the new content renders (tables, <Tip>)
• Uses components and table styles already present on the Axes page
• CI must pass

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Aug 3, 2026, 5:21 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @igorlukanin's task in 1m 23s —— View job

---

Review complete — docs-only change, looks good overall. 1 medium (misplaced <Note> scope), 3 low. 4 inline comments posted.

Full review

• Gather context (diff, changed files)
• Read full page context for both files
• Check docs conventions (docs-mintlify/CLAUDE.md)
• Check for existing/stale Claude review threads (none found)
• Post review

Summary

Correct target directory (/docs-mintlify, not the deprecated /docs), correct conventional-commit prefix, no new pages so no docs.json change needed, <Tip> is a valid Mintlify component already used in this docs set, and the tables match the styling of the other tables on the page. Extending the existing Axes page instead of creating a new one is exactly what docs-mintlify/CLAUDE.md asks for. This is low-risk: no code, no security/performance/test surface.

Findings

#	Severity	File	Issue
1	Medium	axes.mdx:74-81	The <Note> saying reference lines are left-Y-axis-only now sits after the new ### Reference line labels H3, so it reads as a constraint on labels rather than on reference lines generally. Move it above the new subsection.
2	Low	axes.mdx:70	"clear of the bars" — this page covers bar, line, area, scatter, and heatmap; the sibling edit in this PR documents the same controls on the line-chart page, where there are no bars.
3	Low	line.mdx:30	labelled is British spelling and the only instance in the whole docs site (bar.mdx, skills.mdx, scheduled-tasks.mdx, snowflake.mdx all use labeled).
4	Low	axes.mdx:60-72	Some padding against CLAUDE.md's "Do not pad" / "Say it once": the "the reader has to already know what it means" framing and the "clearing the label leaves the line untouched" sentence. Also, the new paragraphs are hard-wrapped at ~95 chars while the rest of the file keeps each paragraph on one line.

Suggestion blocks are attached to findings 2–4.

Optional

axes.mdx:51 — step 3 of the numbered list still reads "Optionally set a Label that appears next to the line." A short "see Reference line labels for placement" would point readers at the new subsection from the procedure they're most likely to land on.

Not verifiable from this repo

The behavioral claims — that the two placement controls only appear once a label is set, the End/Above defaults, the label inheriting the line color, and the auto-flip near the plot edges — describe Cube Cloud UI that isn't in this repository. I took them on the author's word; worth a second pair of eyes from someone who can click through the shipped build.

• [Branch: `igor/cub-3609-docs-reference-line-labels`](https://github.com/cube-js/cube/tree/igor/cub-3609-docs-reference-line-labels)

[claude]

The <Note> about the left-Y-axis restriction applies to reference lines in general, not to labels. Before this PR it sat directly under ## Reference lines; now that a ### Reference line labels subsection is inserted above it, it reads as if only labelled reference lines are left-axis-only.

Move it up so it closes the parent section before the new H3 (i.e. right after "You can add multiple reference lines to the same axis. Each is configured independently." on line 56), and leave the <Tip> as the last thing in the labels subsection.

[claude]

"clear of the bars" is too chart-specific for this page — axes.mdx states up front that these settings apply to "all Vega-based chart types (bar, line, area, scatter, heatmap)", and the sibling change in this PR documents the same controls on the line chart page, where there are no bars.

Suggested change

	New labels start at **End** and **Above** — the right end of the line, clear of the bars. The label
	New labels start at **End** and **Above** — the right end of the line, clear of the plotted marks. The label

[claude]

labelled is British spelling and is the only occurrence in the entire docs site — everywhere else uses labeled (bar.mdx, skills.mdx, scheduled-tasks.mdx, snowflake.mdx).

Suggested change

	Add a horizontal reference line in the **Y axis** section of the Style tab. Set the value, label, color, and line style (solid, dashed, or dotted). A labelled line also takes horizontal (start / middle / end) and vertical (above / below) placement for its text. Multiple reference lines are supported.
	Add a horizontal reference line in the **Y axis** section of the Style tab. Set the value, label, color, and line style (solid, dashed, or dotted). A labeled line also takes horizontal (start / middle / end) and vertical (above / below) placement for its text. Multiple reference lines are supported.

[claude]

Minor, against docs-mintlify/CLAUDE.md ("Do not pad", "Say it once"): a couple of sentences here are editorial or state the obvious rather than answering "how do I use this?".

• "the reader has to already know what it means" — motivational framing the reader doesn't need.
• "Clearing the label removes the text and leaves the line itself untouched" — expected behavior of clearing a text field.

Something like this keeps every fact that's actually new:

Suggested change

	A reference line with no label renders as a bare rule — the reader has to already know what it
	means. Type text into **Label** to name it, for example `Target 18k`.
	Once a label is set, two alignment controls appear next to it:
	| Control | Options | Description |
	|---|---|---|
	| **Horizontal** | Start / Middle / End | Where along the line the text sits |
	| **Vertical** | Above / Below | Which side of the line the text sits on |
	New labels start at **End** and **Above** — the right end of the line, clear of the bars. The label
	takes the line's color, so it always reads as part of that line. Clearing the label removes the text
	and leaves the line itself untouched.
	Type text into **Label** to name a reference line, for example `Target 18k`. Once a label is set,
	two alignment controls appear next to it:
	| Control | Options | Description |
	|---|---|---|
	| **Horizontal** | Start / Middle / End | Where along the line the text sits |
	| **Vertical** | Above / Below | Which side of the line the text sits on |
	New labels start at **End** and **Above**. The label takes the line's color, so it always reads as
	part of that line.

Also note the new paragraphs are hard-wrapped at ~95 chars while the rest of this file keeps each paragraph on a single line — worth matching either way.