Skip to content

notio note_resolve generates malformed cross-references (missing dot before .md extension)

Problem

Cross-references between notes are generated with the .md extension fused to the note ID — e.g., issue-arash-20260407-051003-916809md instead of issue-arash-20260407-051003-916809.md. The dot before md is missing.

This produces ~100+ "unrecognized relative link" warnings in mkdocs builds. The links silently break — they don't resolve to any file.

Examples from pixecog build

'log/issue/issue-arash-20260407-051015-630644.md' contains an unrecognized relative link '../../issue-arash-20260327-002158-537055md'
'log/task/task-arash-20260331-042147-991389.md' contains an unrecognized relative link '../../task-arash-20260327-023910-851248md'
'log/idea/idea-arash-20260407-032215-349055.md' contains an unrecognized relative link '../../idea-arash-20260251215-164928md'

All follow the same pattern: ../../{note-id}md instead of ../../{note-id}.md.

Affected components

The bug is in whichever notio code generates cross-reference links in note bodies — likely note_resolve, note_create, or the ref formatter used when notes reference other notes in their content. The ../../ relative path prefix is correct (two levels up from log/{type}/), only the extension separator is wrong.

Impact

  • mkdocs strict build: these are INFO (not WARNING) so don't block the build, but produce ~100 lines of noise
  • Rendered site: all inter-note links are broken
  • pandoc: not affected (doesn't build these pages)

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