fix(extend): render the config-file mapping headings, repair their anchors - #1069
Merged
Conversation
…chors
Twelve headings on the Configuration File page still carried kramdown's
`---` em-dash shorthand ("Input mapping --- basic"). Kramdown turned that into
an em dash and slugged the id off the result; Starlight renders the three
hyphens literally and slugs them too, so the page showed "Input mapping ---
basic" and the ids became `input-mapping-----basic`.
Using a real em dash fixes both at once: the heading reads correctly and the id
goes back to the kramdown-era `input-mapping--basic`, so anchor links written
against developers.keboola.com — including the ones in component repos we
cannot edit — resolve again.
Two links were pointing at a third spelling, `#output-mapping---delete-rows`,
which never existed on either site; they now match the built id.
Verified against the build (`astro build`): all 12 ids are the `--` form, and
every in-repo link to a config-file anchor resolves. audit-phase2 unchanged at
45 broken internal links / 0 missing images / 3 multi-h1.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Iamfle4ka
pushed a commit
to keboola/developers-docs
that referenced
this pull request
Aug 3, 2026
The two mapping links pointed at `#input-mapping-----basic` / `#output-mapping-----basic`, the ids help currently generates from the literal `---` in those headings. keboola/connection-docs#1069 replaces the dashes with a real em dash, which restores the original `--` ids. Point at those, and merge #1069 first. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This was referenced Aug 3, 2026
Iamfle4ka
pushed a commit
that referenced
this pull request
Aug 5, 2026
…verride treatments
Owner decision 2026-08-05 (Jordan's option on the 07-30 call): Variables lives under
Flows. `/transformations/variables/` becomes `/flows/variables/`, with the API pages as
its children; the old URLs keep working via `redirect_from`.
The override of a configuration variable from a flow was documented in FOUR places:
`transformations/variables` "Flow Usage", `flows/index.md` "## Variables",
`flows/index.md` "Control Task Execution" (the only one with current UI), and the API
page's "Orchestrator Integration". They collapse into one section on the new page.
Corrected while merging them, against the live flow schemas:
- Conditional flows are `keboola.flow`; `keboola.orchestrator` is legacy. The API page's
"Orchestrator Integration" documented the legacy component as if it were current. It is
now "Driving Variables from a Flow", split into Conditional Flows (variable tasks,
merge-by-name, `variableOverrides` tri-state) and Legacy Flows (the existing task
payload, labelled legacy with a migration-guide link).
- The evaluation-sequence rules and the surrounding prose said "orchestration" throughout.
Shared Code is a different feature — it substitutes code, not values, and only for
transformations — so it moves out to `/transformations/shared-code/`, UI plus the API
section lifted off the Variables API page. Its 17 images move with it.
Also: the Jekyll-era escape `{{ "{{ multiplier " }}}}` rendered literally on the page;
`flows/index.md` drops from 391 to 227 lines; `workspace/sql-editor` linked variables
through an absolute help.keboola.com URL.
Verified: build clean, 309 pages. audit-phase2 broken links 54 → 54, missing images 0,
one old-docs smell fixed (156 → 155 total). #1073's anchor checker reports no new broken
anchors from these pages — the two on the API page are the `config-file` headings #1069
repairs. All five old URLs redirect, no duplicate heading ids.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Iamfle4ka
pushed a commit
that referenced
this pull request
Aug 5, 2026
Two of these are defects my own rewrite introduced:
- `actionParameters` was bound to `keboola.orchestrator` by the new "Legacy Flows"
heading. That property belongs to the *older* `orchestrator` component
(syrup.keboola.com/orchestrator); `keboola.orchestrator` stores tasks as
`task: {componentId, configId, mode, …}`, which the page's own Step 5 example shows.
Claim dropped rather than restated.
- Renaming "orchestration" → "flow" in the evaluation-sequence rules silently asserted
legacy-orchestrator precedence for `keboola.flow`, where neither task-level
`variableValuesId` nor run-level overrides are declared. Those bullets are now scoped
to legacy flows explicitly.
- The exception list read as though a `keboola.flow` configuration may carry placeholders
while the next sentence said it may not; it now names both flow components.
Pre-existing, but on pages this PR makes canonical:
- "If you omit *thirdVar*, it will be replaced by an empty string" is wrong.
`configuration-variables-resolver` collects every unresolved placeholder and throws
`Missing values for placeholders: …`. It also contradicted the new UI page, which
states the error correctly. Replaced with both real error strings.
- The static flow-variable example used `"value": 3600`; the live `keboola.flow` schema
declares `value` as a string, so an unquoted number fails validation. Same for the
`variableValuesData` example and the tutorial's `"value": 1`.
- **Tutorial blocker:** the run-job body inlined `'$VARIABLES_VALUES'` unquoted, so bash
word-split a multi-line value — curl got a JSON fragment truncated at
`"values":` plus 12 stray argv words, and only zsh happened to work. Now a heredoc on
stdin: verified ARGC=10 and a byte-identical, `json.load`-valid body in both shells.
- The tutorial said default values live in "additional configurations"; they are
configuration rows of the same variable configuration, referenced by
`variables_values_id`.
Also: the legacy task-payload claim is inherited from developers.keboola.com and is
absent from every public orchestrator schema, so it now carries a caution saying so
rather than reading as current behaviour. And `PageTitle.astro` still keyed its emoji off
`transformations/variables`, so the icon vanished with the move.
The two remaining broken anchors on the API page (`config-file/#input-mapping--basic`)
resolve once #1069 lands — it converts those `---` headings to em dashes, which slug to
exactly the two-dash form linked here.
Verified: build clean, 309 pages, audit unchanged at 54 broken links / 0 missing images /
155 total, no new broken anchors.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
jordanrburger
approved these changes
Aug 5, 2026
jordanrburger
left a comment
jordanrburger
left a comment
Contributor
There was a problem hiding this comment.
Approving — this is right, and it's the head of a chain so it needs to go in first.
I checked the rendering claim against production rather than taking it on trust. On /catalog/multi-project/ the HTML currently ships separate project --- Oracle with three literal hyphens, while ora-history — The source database on the same page renders correctly. So SmartyPants eats -- and leaves --- alone, exactly like you said, and the double-slug thing follows from it.
Merge order for this chain — four PRs are entangled and the order matters:
- #1069 (this one) — base
main. It'sBEHIND, so rebase it. - #1070 — base is this branch, can't merge until this does.
- #1073 — base is #1070's branch.
One thing I want to flag loudly: #1072 shows as MERGED but its 73 anchor fixes aren't on production. It went into docs/em-dash-prose (#1070's branch), not main, so those fixes only reach readers when #1070 lands. Reading the PR list, anyone would assume that work already shipped — I did.
For next time: if a PR's base isn't main, put it in the title or slap a label on it. Three deep with a merge into the middle is invisible from the list view.
This was referenced Aug 5, 2026
jordanrburger
added a commit
that referenced
this pull request
Aug 5, 2026
Resolves two conflicts created by merging #1069 (whose branch update brought main forward while this branch was cut from the pre-update commit): - components/extractors/other/index.md: kept main's Dark Sky deprecation note and applied this branch's em-dash fix to all eight list entries. - management/notifications/notifications.md: kept main's rewritten flow notification section, which supersedes the old bullets and already uses real em dashes. Verified: 0 literal `---` remain in prose across src/content/docs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #1046, found while retiring the dev-side copies (developers-docs#406).
Twelve headings on Configuration File still carry kramdown's
---em-dash shorthand:Kramdown turned that into an em dash and slugged the id off the result. Starlight renders the three hyphens literally and slugs them too — so the page currently shows
Input mapping --- basicand the id isinput-mapping-----basic.A real em dash fixes both at once: the heading reads correctly, and the id goes back to the kramdown-era
input-mapping--basic, so anchor links written againstdevelopers.keboola.com— including those in component repos we can't edit — resolve again.Changes:
extend/common-interface/config-file/:---→—in the 12 affected headings. Nothing else on the page touched.extend/common-interface/manifest-files/out-tables-manifests/and…-native-types/: both linked to#output-mapping---delete-rows, a third spelling that never existed on either site → now#output-mapping--delete-rows.extend/common-interface/folders/needed no edit: its#output-mapping--headless-csvlink becomes correct once the heading is fixed. That link is live-broken today.Verified against
astro build(not dev):--form, e.g.id="input-mapping--basic",id="output-mapping--delete-rows".Input mapping — basic.config-fileanchor resolves against the built page.audit-phase2: 45 broken internal links / 0 missing images / 3 multiple-h1 / 0 unclosed fences — identical tomain. (The audit does not check anchors, which is why these three slipped through PRDCT-543: Extending Keboola as its own top-level section #1046; checked by hand againstdist/.)config-fileis the only page undersrc/content/docs/with a literal---inside a heading. Body prose still uses---as an em dash in many migrated pages — that renders literally too, but it's cosmetic and out of scope here.