📚 Sync docs from alaudadevops/tektoncd-operator on 88ef08fec5f476ea4f656e769ccb68ab84d06773

Source: wip: Connectors integration in pipeline (#604)
Author: Daniel Filipe Bruehmueller Morinigo
Ref: refs/heads/main
Commit: 88ef08fec5f476ea4f656e769ccb68ab84d06773

This commit automatically syncs documentation changes from the source-docs repository.

🔗 View source commit: https://github.com/alaudadevops/tektoncd-operator/commit/88ef08fec5f476ea4f656e769ccb68ab84d06773
🤖 Synced on 2025-10-15 04:22:37 UTC

Author: edge-katanomi-app2[bot]

.github/SYNC_INFO.md

@@ -1,10 +1,10 @@
 # Documentation Sync Information
 
-- **Last synced**: 2025-10-14 13:07:28 UTC
+- **Last synced**: 2025-10-15 04:22:37 UTC
 - **Source repository**: alaudadevops/tektoncd-operator
-- **Source commit**: [079776bbaddf3f46bda66241953c75a34e9d566b](https://github.com/alaudadevops/tektoncd-operator/commit/079776bbaddf3f46bda66241953c75a34e9d566b)
+- **Source commit**: [88ef08fec5f476ea4f656e769ccb68ab84d06773](https://github.com/alaudadevops/tektoncd-operator/commit/88ef08fec5f476ea4f656e769ccb68ab84d06773)
 - **Triggered by**: edge-katanomi-app2[bot]
-- **Workflow run**: [#81](https://github.com/alaudadevops/tektoncd-operator/actions/runs/18497527857)
+- **Workflow run**: [#84](https://github.com/alaudadevops/tektoncd-operator/actions/runs/18517697426)
 
 ## Files synced:
 - docs/

docs/en/design/guides/documentation-migration-guide.mdx

@@ -0,0 +1,381 @@
+---
+weight: 100
+---
+
+# Documentation Migration Guide: From MkDocs to Doom.js
+
+## Overview
+
+This guide provides comprehensive instructions for migrating design documents from the MkDocs-based `specs` repository to the Doom.js-based `tektoncd-operator` documentation system. This migration enables centralized documentation management within the tektoncd-operator project.
+
+## Repository Comparison
+
+### Source Repository (MkDocs-based)
+- **Repository**: `/specs` (gitlab-ce.alauda.cn/devops/specs)
+- **Documentation System**: MkDocs with Material theme
+- **File Format**: Standard Markdown (`.md`)
+- **Build System**: Python-based with pip requirements
+- **Configuration**: `mkdocs.yml`
+
+### Target Repository (Doom.js-based)
+- **Repository**: `/tektoncd-operator` (github.com/alaudadevops/tektoncd-operator)
+- **Documentation System**: Doom.js
+- **File Format**: MDX (`.mdx`) with React components
+- **Build System**: Node.js/Yarn-based
+- **Configuration**: `doom.config.yml`
+
+## Key Differences Between Systems
+
+### 1. File Extensions
+- **MkDocs**: Uses `.md` files
+- **Doom.js**: Uses `.mdx` files (supports JSX components)
+
+### 2. Frontmatter Format
+**MkDocs (specs repository):**
+```yaml
+---
+created: 2025-09-16
+title: Pipeline Orchestration and Execution
+tags:
+- connectors
+- pipeline
+- orchestrating-pipelines
+---
+```
+
+**Doom.js (tektoncd-operator):**
+```yaml
+---
+weight: 10
+sourceSHA: <optional-hash>
+i18n:
+  additionalPrompts: <optional-translation-hints>
+---
+```
+
+### 3. Admonition Syntax
+**MkDocs Format:**
+```markdown
+!!! tip "Pros"
+    - Easy to implement
+    - Good user experience
+
+!!! danger "Cons"
+    - Complex maintenance
+    - Limited scalability
+
+!!! note
+    This is a note without title
+```
+
+**Doom.js Format:**
+```markdown
+:::tip
+Easy to implement and provides good user experience
+:::
+
+:::danger
+Complex maintenance with limited scalability
+:::
+
+:::note
+This is a note without title
+:::
+
+:::details{title="Expandable Section"}
+Content that can be expanded/collapsed
+:::
+```
+
+### 4. Special Components
+**MkDocs**: Uses Python extensions and plugins
+**Doom.js**: Uses React components like:
+- `<Overview overviewHeaders={[]} />` for auto-generated navigation
+- Custom JSX components for interactive elements
+
+### 5. Build Commands
+**MkDocs:**
+```bash
+# Install dependencies
+pip3 install -r requirements.txt
+
+# Development server
+python3 -m mkdocs serve -s
+
+# Build
+python -m mkdocs build --strict --clean
+```
+
+**Doom.js:**
+```bash
+# Install dependencies
+yarn install
+
+# Development server
+yarn dev
+
+# Build
+yarn build
+
+# Lint
+yarn lint
+```
+
+## Migration Steps
+
+### Step 1: Prepare the Target Directory Structure
+
+Design documents should be placed in the appropriate directory within the tektoncd-operator documentation structure:
+
+```
+docs/en/design/
+├── index.mdx                    # Overview of design documents
+├── connector-integration/       # Connector-related designs
+├── pipeline-enhancements/       # Pipeline feature designs
+├── operator-improvements/       # Operator-specific designs
+└── architecture/               # Architecture decision records
+```
+
+### Step 2: File Migration Process
+
+#### 2.1 Copy and Rename Files
+1. Copy the `.md` file from the specs repository
+2. Rename the extension from `.md` to `.mdx`
+3. Place in the appropriate subdirectory under `docs/en/design/`
+
+#### 2.2 Update Frontmatter
+Transform the MkDocs frontmatter to Doom.js format:
+
+**Before (MkDocs):**
+```yaml
+---
+created: 2025-09-16
+title: Pipeline Orchestration and Execution
+tags:
+- connectors
+- pipeline
+- orchestrating-pipelines
+---
+```
+
+**After (Doom.js):**
+```yaml
+---
+weight: 10
+---
+```
+
+#### 2.3 Convert Admonitions
+Replace MkDocs admonition syntax with Doom.js format:
+
+**Search and Replace Patterns:**
+
+| MkDocs Pattern | Doom.js Replacement |
+|----------------|---------------------|
+| `!!! tip "Title"` | `:::tip` |
+| `!!! danger "Title"` | `:::danger` |
+| `!!! note "Title"` | `:::note` |
+| `!!! warning "Title"` | `:::warning` |
+| `!!! note` | `:::note` |
+
+**Example Transformation:**
+```markdown
+<!-- MkDocs format -->
+!!! tip "Pros"
+    - Easy to implement
+    - Good user experience
+
+<!-- Doom.js format -->
+:::tip
+- Easy to implement
+- Good user experience
+:::
+```
+
+#### 2.4 Handle Asset References
+Update image and asset references:
+
+1. Copy assets from `specs/docs/features/.../assets/` to `tektoncd-operator/docs/shared/assets/design/`
+2. Update image references in the document:
+   ```markdown
+   <!-- Before -->
+   ![](assets/pipeline-integration-flow.drawio.png)
+
+   <!-- After -->
+   ![](/shared/assets/design/pipeline-integration-flow.drawio.png)
+   ```
+
+### Step 3: Content Adaptation
+
+#### 3.1 Review Content Relevance
+- Ensure the design document is relevant to the tektoncd-operator project
+- Update any references to the "platform" to be specific to "Alauda DevOps Pipelines"
+- Remove or adapt content specific to other products if not applicable
+
+#### 3.2 Update Navigation Weight
+Assign appropriate `weight` values in frontmatter to control document ordering:
+- Lower numbers appear first
+- Use increments of 10 (10, 20, 30...) to allow future insertions
+- Group related documents with similar weight ranges
+
+#### 3.3 Add Index Files
+Create `index.mdx` files for directories containing multiple documents:
+
+```mdx
+---
+weight: 1
+---
+
+# Design Documents
+
+<Overview overviewHeaders={[]} />
+```
+
+### Step 4: Testing and Validation
+
+#### 4.1 Local Development
+1. Run the development server:
+   ```bash
+   cd tektoncd-operator
+   yarn dev
+   ```
+2. Navigate to the design section and verify:
+   - Document renders correctly
+   - Images display properly
+   - Admonitions render as expected
+   - Navigation structure is correct
+
+#### 4.2 Build Verification
+1. Build the documentation:
+   ```bash
+   yarn build
+   ```
+2. Check for any build errors or warnings
+3. Verify no broken links or missing assets
+
+### Step 5: Configuration Updates
+
+#### 5.1 Update doom.config.yml
+If migrating internal design documents, ensure they're covered by the `internalRoutes` configuration:
+
+```yaml
+internalRoutes:
+  - '*/design/**/*'
+  - '**/design/**/*'
+```
+
+#### 5.2 Navigation Structure
+Design documents will automatically appear in navigation due to the `<Overview />` component in index files.
+
+## Migration Checklist
+
+Use this checklist when migrating each document:
+
+- [ ] File copied and renamed to `.mdx`
+- [ ] Placed in appropriate `docs/en/design/` subdirectory
+- [ ] Frontmatter converted to Doom.js format
+- [ ] `weight` value assigned for navigation ordering
+- [ ] All admonitions converted (`!!!` → `:::`)
+- [ ] Asset files copied to shared assets directory
+- [ ] Image references updated to new paths
+- [ ] Content reviewed for tektoncd-operator relevance
+- [ ] Local development server tested
+- [ ] Build process completed successfully
+- [ ] Navigation structure verified
+
+## Common Issues and Solutions
+
+### Issue: Admonitions Not Rendering
+**Problem**: MkDocs-style admonitions (`!!! tip`) don't render in Doom.js
+**Solution**: Convert all admonitions to Doom.js format (`:::tip`)
+
+### Issue: Images Not Loading
+**Problem**: Relative asset paths from MkDocs don't work in Doom.js
+**Solution**:
+1. Copy assets to `docs/shared/assets/design/`
+2. Update references to use absolute paths starting with `/shared/`
+
+### Issue: Complex Tables
+**Problem**: Some advanced MkDocs table syntax might not render
+**Solution**: Simplify table markup or use standard Markdown tables
+
+### Issue: Build Errors
+**Problem**: Doom.js build fails due to unsupported syntax
+**Solution**:
+1. Check for unescaped JSX characters (`<`, `>`)
+2. Ensure all code blocks are properly fenced
+3. Validate frontmatter YAML syntax
+
+## Best Practices
+
+### 1. Document Organization
+- Group related design documents in subdirectories
+- Use descriptive filenames following kebab-case convention
+- Include date in document title or changelog section
+
+### 2. Asset Management
+- Name assets descriptively
+- Organize assets in subdirectories by feature/topic
+- Use web-optimized formats (PNG, SVG for diagrams)
+
+### 3. Content Quality
+- Maintain consistent heading structure (H1 for title, H2 for major sections)
+- Include changelog section for tracking document evolution
+- Use clear, actionable language in design decisions
+
+### 4. Navigation
+- Assign logical weight values for document ordering
+- Create meaningful directory structures
+- Include overview documents for major sections
+
+## Example Migration
+
+Here's a complete example of migrating a design document:
+
+### Before (MkDocs - specs repository)
+**File**: `docs/features/connector-v2/pipeline-integration/orchestration.md`
+
+```markdown
+---
+created: 2025-09-16
+title: Pipeline Orchestration and Execution
+tags:
+- connectors
+- pipeline
+---
+
+# Pipeline Orchestration and Execution
+
+!!! tip "Pros"
+    - Easy to implement
+    - Good user experience
+
+![](assets/pipeline-flow.png)
+```
+
+### After (Doom.js - tektoncd-operator)
+**File**: `docs/en/design/connector-integration/pipeline-orchestration.mdx`
+
+```mdx
+---
+weight: 20
+---
+
+# Pipeline Orchestration and Execution
+
+## Changelog
+- 2025-09-16: Initial version migrated from specs repository
+
+:::tip
+- Easy to implement
+- Good user experience
+:::
+
+![Pipeline Flow](/shared/assets/design/connector-integration/pipeline-flow.png)
+```
+
+## Conclusion
+
+This migration process enables centralized documentation management within the tektoncd-operator project while maintaining the rich formatting capabilities needed for technical design documents. Following these guidelines ensures consistency and maintainability of the documentation ecosystem.
+
+For questions or issues during migration, refer to the [Doom.js documentation](https://doom.alauda.io) or consult the development team.