Summary
Now that Pipelines-as-Code (PAC) has joined the Tekton organization, its documentation should be integrated into tekton.dev alongside the other Tekton components (Pipelines, Triggers, CLI, Dashboard, Chains, etc.) rather than living on a separate standalone site (pipelinesascode.com).
Current State
- PAC docs are hosted separately using Hugo + Hextra theme at pipelinesascode.com
- tekton.dev has only a stub page under Getting Started that links out to pipelinesascode.com
- All other Tekton components (Pipelines, Triggers, CLI, Dashboard, Chains, Operator, Results) have their docs synced into tekton.dev via
sync/sync.py with per-component YAML configs in sync/config/
Challenges
PAC's documentation structure is significantly different from the other Tekton components:
-
Different doc structure: Other components keep docs as flat markdown files in a docs/ folder in their repo. PAC uses a full Hugo site with nested content tree (docs/content/docs/) organized into sections: installation, guides, providers, operations, CLI, API, advanced, and dev.
-
Nested hierarchy: PAC docs have deep nesting (e.g., guides/creating-pipelines/, guides/event-matching/, guides/gitops-commands/, guides/llm-analysis/) that doesn't map cleanly to the current sync script's flat folder model.
-
Different theme/tooling: PAC uses the Hextra theme while tekton.dev uses Docsy. Front matter, shortcodes, and layout assumptions may differ.
Possible Approaches
-
Sync config approach: Create a sync/config/pipelines-as-code.yaml and extend sync.py to handle PAC's nested doc structure, mapping it into the tekton.dev content tree under content/en/docs/Pipelines-as-Code/.
-
Restructure PAC docs: Flatten or reorganize PAC's docs/ folder to match the pattern used by other Tekton components, then use the standard sync mechanism.
-
Hugo module / submodule approach: Mount PAC's docs content as a Hugo module directly into the website, preserving the hierarchy as-is.
-
Manual initial sync + sync script maintenance: Do a one-time import of PAC docs into the website repo, then maintain them there (similar to how some projects handle large doc sets).
Acceptance Criteria
Summary
Now that Pipelines-as-Code (PAC) has joined the Tekton organization, its documentation should be integrated into tekton.dev alongside the other Tekton components (Pipelines, Triggers, CLI, Dashboard, Chains, etc.) rather than living on a separate standalone site (pipelinesascode.com).
Current State
sync/sync.pywith per-component YAML configs insync/config/Challenges
PAC's documentation structure is significantly different from the other Tekton components:
Different doc structure: Other components keep docs as flat markdown files in a
docs/folder in their repo. PAC uses a full Hugo site with nested content tree (docs/content/docs/) organized into sections: installation, guides, providers, operations, CLI, API, advanced, and dev.Nested hierarchy: PAC docs have deep nesting (e.g.,
guides/creating-pipelines/,guides/event-matching/,guides/gitops-commands/,guides/llm-analysis/) that doesn't map cleanly to the current sync script's flat folder model.Different theme/tooling: PAC uses the Hextra theme while tekton.dev uses Docsy. Front matter, shortcodes, and layout assumptions may differ.
Possible Approaches
Sync config approach: Create a
sync/config/pipelines-as-code.yamland extendsync.pyto handle PAC's nested doc structure, mapping it into the tekton.dev content tree undercontent/en/docs/Pipelines-as-Code/.Restructure PAC docs: Flatten or reorganize PAC's
docs/folder to match the pattern used by other Tekton components, then use the standard sync mechanism.Hugo module / submodule approach: Mount PAC's docs content as a Hugo module directly into the website, preserving the hierarchy as-is.
Manual initial sync + sync script maintenance: Do a one-time import of PAC docs into the website repo, then maintain them there (similar to how some projects handle large doc sets).
Acceptance Criteria