The mkdocs-pipeline-visualizer plugin automates the creation of up-to-date documentation for your Tekton pipelines and tasks.

To install the mkdocs-pipeline-visualizer plugin, run the following command:

$ pip install mkdocs-pipeline-visualizer

Below is an example of how to configure mkdocs.yaml:

site_name: Tekton
docs_dir: ./tekton

nav:
  - Home: index.md

plugins:
  - pipeline-visualizer

markdown_extensions:
  plantuml_markdown:
    server: http://www.plantuml.com/plantuml

theme:
  name: material
  features:
    - navigation.sections

By default, the plugin creates two sections at the root level: Pipelines and Tasks. The docs_dir should point to the location of pipelines and tasks manifests.

Let's say you have a pipeline file located at:

./pipelines/project-a/deployment/my-pipeline.yaml

Here's how different nav_pipeline_grouping_offset values would affect the navigation structure:

• "0:-1": Includes all directories except the last one (which is the file name).

  • Result: Pipelines > pipelines > project-a > deployment > my-pipeline

• "1:-1": Skips the first directory and includes all others except the last one.

  • Result: Pipelines > project-a > deployment > my-pipeline

• "1:-2": Skips the first directory and excludes the last two (the last directory and the file name).

  • Result: Pipelines > project-a > my-pipeline

• None (default): All pipelines are placed directly under the nav_section_pipelines section.

  • Result: Pipelines > my-pipeline

You can change the location of the documentation sections by placing an empty section in any location of the navigation (nav) and setting it to the value of nav_section_pipelines or nav_section_tasks:

site_name: Tekton
docs_dir: ./tekton

nav:
  - Home: index.md
  - Tekton:
    - "Tasks": []
    - "Pipelines": []
    - "StepActions": []

plugins:
  - pipeline-visualizer

To change the names of the menu sections and apply a custom graph theme, use the following configuration:

site_name: Tekton
docs_dir: ./tekton

nav:
  - Home: index.md  
  - Tekton:
    - "🛠️ Tasks": []
    - "🚀 Pipelines": []
    - "⚙️ StepActions": []

plugins:
  - pipeline-visualizer:
      plantuml_theme: hacker
      nav_section_tasks: "🛠️ Tasks"
      nav_section_pipelines: "🚀 Pipelines"
      nav_section_stepactions: "⚙️ StepActions"      

You can customize how task categories appear in the navigation by providing mappings in the nav_category_mapping configuration:

plugins:
  - pipeline-visualizer:
      nav_category_mapping:
        "Code Quality": "Quality Tools"
        "Build": "Build Tools"
        "Deploy": "Deployment"

• Fix rendering of StepAction

• Corrected markdown code block rendering for scripts.

• Support for Tekton StepActions.
• nav_section_stepactions and nav_stepaction_grouping_offset configuration options.
• Updated navigation generation to include StepActions.
• Updated example configuration and documentation.

• Resolved infinite loop issue with mkdocs serve by preventing unnecessary file writes when content is unchanged.

• Optional support for categorization of tasks in navigation using tekton.dev/categories annotation.

• Example in example/.
• Visualization for step templates in tasks.

• Corrected typo in plantuml_graphs attribute name (from plantum_graphs).
• Corrected typo in nav_task_grouping_offset attribute name (from nav_tasks_grouping_offset).

• Navigation generation feature with customizable sections for pipelines and tasks.
• Support for grouping pipelines and tasks in the navigation.
• Improved logging with configurable log levels.
• Version-based sorting for resources in navigation.

• Improved visualization of tasks, parameters, and workspaces.
• Better handling of different script types in task steps.

• Various bug fixes and code structure improvements.

• Version of tasks from the documentation until a better presentation is available.

• Issue with backslashes (\) in usage examples.
• Example in the README.

• Version of pipeline/task when available.

• Hide workspaces for tasks when none are used.

• Sample on how to use a task in a pipeline.
• plantuml_graphs option to make PlantUML graphs optional.

• Removed extra --- after tasks.
• Processing of only pipelines or tasks.

• Display of all tasks in the finally block.

• Configuration for graph direction (plantuml_graph_direction).
• Configuration for PlantUML theme (plantuml_theme).
• Display of references to configMaps.

• Presentation of default and empty values.

• Unused code.

• Issue with multidoc YAML.