Skip to content

docs(extend): retire the merged component docs, redirect to help (PRDCT-543) - #406

Open
Iamfle4ka wants to merge 4 commits into
mainfrom
docs/retire-dev-extend
Open

docs(extend): retire the merged component docs, redirect to help (PRDCT-543)#406
Iamfle4ka wants to merge 4 commits into
mainfrom
docs/retire-dev-extend

Conversation

@Iamfle4ka

@Iamfle4ka Iamfle4ka commented Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Jira issue(s): PRDCT-543 — companion delete-from-dev PR for connection-docs#1046 (merged 2026-07-29).

Components, Common Interface, Job Queue and Publish now live at help.keboola.com/extend/** at identical paths. Until this PR lands there are two copies of the same 41 pages, one of which nobody is maintaining.

Changes:

  • 41 pages → redirect_to stubs (extend/component 22, extend/common-interface 16, extend/job-queue 1, extend/publish 2). Front matter only: title, the original permalink, the original redirect_from, plus redirect_to: https://help.keboola.com<same path>.
  • Stubs rather than deletions. A scan of the keboola GitHub org found 210 files linking to /extend/component/ and 65 to /extend/common-interface/, and that excludes component documentation_urls, the platform UI, support macros and bookmarks. Every redirect_from is preserved, so legacy URLs (/extend/docker/, /extend/docker-runner/, /extend/custom-science/…, /extend/registration/…) keep working — they reach help in two hops.
  • 55 links repointed in the 20 pages that stay (Generic Extractor, /integrate/**, /overview/**, /cli/**, index.md, extend/index.md) so they go to help directly instead of through a stub.
  • A branded "this page has moved" note_layouts/redirect.html. jekyll-redirect-from only injects its own template when the site has no redirect layout of its own, so this one file replaces "Redirecting… Click here if you are not redirected." on all 41 stubs at once. The redirect still fires immediately (location.replace + a 0s meta refresh), so nobody waits; the note is what a reader sees when it does not fire, and it asks them to update bookmarks and component documentation_urls. The copy adapts, since this layout renders every redirect_from alias in the repo too: the help wording only for help-bound targets, "the path did not change" only when the from-path and target path actually match (true for the 41 stubs, not for aliases like /extend/docker//extend/component/), and a plain "this page has a new address" for aliases that stay on dev docs. Rendered against those three cases with Liquid in strict mode.
  • Nav: the four retired subtrees are gone from _data/navigation.yml.
  • /extend/ keeps its landing page for Generic Extractor and Generic Writer (still documented here), with a note pointing at help.keboola.com/extend/ for component development.
  • 99 images deleted — every one of them only used by the retired pages, and all already mirrored under public/extend/ on help. component/ui-options/configuration.png stays: Generic Extractor pages still use it.

Verification:

  • All 41 targets and /extend/ itself return 200 on help.
  • Every rewritten anchor was checked against the live help page. Three groups needed care:
    • #input-mapping--basic / #output-mapping--basic#input-mapping-----basic / #output-mapping-----basic. The headings are #### Input mapping --- basic; kramdown turned --- into an em dash, Starlight keeps the literal dashes, so the slug is different. (See the note below — the heading itself is worth fixing on help.)
    • #preparing-the-data-folder#preparing-data-folder and #creating-a-component#creating-component: these were already broken on dev, fixed in passing.
  • _data/navigation.yml still parses; no reference to a retired path remains anywhere in the repo except the stubs' own front matter.
  • Build: not run locally — this repo builds through docker compose and there is no container runtime on my machine, so the Build workflow on this PR is the first build.

Follow-ups, not in this PR:

  • Real 301s for developers.keboola.com. redirect_to emits a meta-refresh page (HTTP 200 + canonical); a 301 needs an S3 routing-rule / CloudFront change outside this repo. Given the identity paths, a single /extend/* → help.keboola.com/extend/* rule would cover the whole subtree.
  • On help: /extend/common-interface/folders/ links to #output-mapping--headless-csv, which does not exist (same --- heading issue) — a leftover from #1046.

…CT-543)

Components, Common Interface, Job Queue and Publish were merged into
help.keboola.com/extend/** in keboola/connection-docs#1046 at identical paths.
Leaving them here means two competing copies of the same 41 pages, so they
become `redirect_to` stubs.

Stubs rather than deletions: a scan of the keboola GitHub org found 210 files
linking to /extend/component/ and 65 to /extend/common-interface/, plus the
usual unknowable set (component `documentation_url`s, the platform UI, support
macros, bookmarks). Every existing `redirect_from` is preserved, so legacy
URLs such as /extend/docker/ and /extend/docker-runner/ keep working — they
now land on the help page in two hops.

Also here:
- 55 links from the pages that stay (Generic Extractor, /integrate/**,
  /overview/**, /cli/**, the two landing pages) now point at help directly
  instead of bouncing through a stub. Two anchors that were already broken on
  dev are fixed in passing (#preparing-the-data-folder ->
  #preparing-data-folder, #creating-a-component -> #creating-component), and
  the config-file mapping anchors take their help-side form
  (#input-mapping--basic -> #input-mapping-----basic). All rewritten anchors
  were verified against the live help pages.
- The four retired subtrees are removed from _data/navigation.yml.
- /extend/ keeps its landing page for Generic Extractor and Generic Writer,
  with a note about where component development now lives.
- 99 images that only the retired pages used are deleted; all of them are
  already mirrored under public/extend/ on help. The one image still used by
  Generic Extractor pages (component/ui-options/configuration.png) stays.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@linear-code

linear-code Bot commented Aug 3, 2026

Copy link
Copy Markdown

PRDCT-543

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>
@Iamfle4ka

Copy link
Copy Markdown
Collaborator Author

Ordering note: the two mapping links in integrate/variables/index.md now point at #input-mapping--basic / #output-mapping--basic, which is what help will generate once connection-docs#1069 lands (it replaces the literal --- in those headings with a real em dash). Merge #1069 first — until then those two anchors resolve to the top of the page rather than the section. Everything else in this PR is independent of it.

jekyll-redirect-from only injects its own template when the site has no
`redirect` layout of its own, so a single `_layouts/redirect.html` replaces
"Redirecting… Click here if you are not redirected." on all 41 stubs at once.

The redirect still fires immediately (`location.replace` + a 0s meta refresh),
so nobody waits — this markup is the fallback for when it does not fire, and it
now says where the page went and asks the reader to update bookmarks and
component `documentation_url`s.

The copy adapts, because this layout also renders every `redirect_from` alias
in the repo: the "moved to help.keboola.com" wording is used only for
help-bound targets, "the path did not change" only when the from-path and the
target path actually match (it does for the 41 stubs, not for aliases such as
/extend/docker/ -> /extend/component/), and aliases that stay on dev docs get a
plain "this page has a new address".

Rendered against those three cases with Liquid in strict mode; the repo builds
through docker compose, which is still unavailable locally, so the Build
workflow remains the first real build.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
# Conflicts:
#	extend/component/ui-options/configuration-schema.md
#	extend/component/ui-options/ui-examples/configuration-schema-examples.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants