Skip to content

title: "## Notio manuscript: dual-render master files and mkdocs transclusion setup status: partial created: 2026-04-02 updated: 2026-04-08 timestamp: 20260402-121445-694073 tags: [issue] source: agent-observation project_primary: projio capture_id: 20260402-121444-183435 confidence: 1.0 transcript_file: /storage2/arash/worklog/workflow/captures/20260402-121444-183435/transcript.txt

Notio manuscript: dual-render master files and mkdocs transclusion setup

Problem

Pixecog (and likely other study repos) uses master.md files that must work with both mkdocs (web) and Pandoc (PDF/LaTeX). This requires:

  1. Dual transclusion markers — [[wikilink]] for mkdocs navigation + {% include-markdown "..." %} for content inclusion. Both systems need to resolve the same content atoms but use different syntax. Currently this convention is hand-maintained and easy to break.

  2. A Lua filter (code/utils/lua/include.lua) that teaches Pandoc to understand mkdocs-style {% include-markdown %} and --8<-- markers, with smart-quote normalization and docs/ path fallback. Every project that uses dual-render master files copies this filter.

  3. mkdocs plugin config — the include-markdown plugin must be configured with specific settings (encoding, preserve_includer_indent, comments, etc.) and the ezlinks plugin resolves wikilinks. This setup is project-specific but follows the same pattern.

Feature requests

  1. manuscript_init should scaffold the dual-marker master.md — when creating a manuscript, generate a master.md that has both [[wikilink]] and {% include-markdown %} lines for each section. The manuscript_assemble tool already knows the section order; it should produce master.md in the dual-marker format.

  2. Ship the Lua filter as part of notio — notio.manuscript should provide include.lua (or a Python equivalent) so projects don't need to maintain their own copy. manuscript_build should automatically use it.

  3. notio config mkdocs or site_setup MCP tool — configure mkdocs.yml with the include-markdown plugin, ezlinks, bibtex, and any other plugins needed for the dual-render workflow. Currently each project hand-configures this.

  4. Escape helper — the include-markdown plugin uses regex pre-processing (not Jinja2), so {% raw %} doesn't work, code blocks don't protect, and literal mentions of {% include-markdown %} in documentation break the build. Notio should either:

  5. Document the {%<!-- -->include-markdown HTML comment breaker pattern
  6. Or provide a mkdocs plugin hook that excludes pattern matching inside code blocks

Context

Pixecog already has manuscript_build, manuscript_assemble, manuscript_validate, manuscript_status, manuscript_figure_insert MCP tools working. The gap is in the initial setup (mkdocs config, Lua filter provisioning) and in the master.md generation being dual-render-aware.

Currently the manuscript system audit lives at docs/how-to/doc/manuscript-system-audit.md in pixecog — it documents all the moving parts, P1 issues (wrong conda env in VSCode task, three PDF engines, missing Lua filter in defaults), and proposed architecture for clean separation.

Source context: pixecog

PixEcog (pixecog): Neuropixels and ECoG dataset and analysis

Recent commits: 

0d1ff72 Publish TTL notebook HTMLs (investigate_ttl_artifact, ttl_artifact_removal)
56cc377 [DATALAD] Added subdataset
8fb3303 [DATALAD] Added subdataset

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