Skip to content

Problem

The auto-generated docs/pipelines/index.md is a bare list of flow links. The code/pipelines/architecture.md contains a mermaid cross-flow DAG, flow layer table, data flow summary, and derivative mapping — but it's collected as a separate page that users have to navigate to manually.

The pipelines landing page should show the mermaid DAG with clickable flow nodes so users can visually navigate the ecosystem. Currently this requires manually editing the generated index.md with include-markdown directives, which is fragile (the file is auto-generated).

Proposed fix

When docs_collect generates the top-level docs/pipelines/index.md, it should:

  1. Check if code/pipelines/architecture.md exists (it already does this for separate collection)
  2. Extract the mermaid diagram section from it
  3. Include it in the generated index between the # Pipelines header and the flow list
  4. Add click directives to mermaid nodes linking to their flow pages (e.g., click IEEG "preprocess_ieeg/" "preprocess_ieeg")
  5. Keep the flow list below the diagram as a text fallback

Alternatively, support an include-markdown directive in a source template for the index, so projects can customize what appears on the landing page without editing generated output.

Context

The architecture.md source already has the mermaid with click directives added. The issue is purely that docs_collect doesn't incorporate it into the index. The manual workaround (editing the generated index.md with include-markdown) breaks because: - docs_collect only skips regeneration if index.md already exists, but any re-collection that deletes it first would lose the customization - The include-markdown plugin path resolution is fragile across monorepo sub-sites

Source context: pixecog

PixEcog (pixecog): Neuropixels and ECoG dataset and analysis

Recent commits: 

8dc0d9d Pipeline docs: gitignore docs/pipelines/, relocate hand-authored files
96cd1ec Refactor sharpwaveripple/contracts: extract generic helpers to utils/io, remove pipelines __init__.py
36f9326 Add result note directory and sample note

README:

type: readme

Quick Start for Collaborators

Follow this checklist to get started with Pixecog documentation and workflows.

🐀 Pixecog Project — Compact Overview

Core principles

  • One immutable BIDS raw dataset (raw/) as the canonical baseline
  • Each analysis pipeline ha