Skip to content

Add test case for MyST target anchors before title heading #6

@mmcky

Description

@mmcky

Problem

The parseDocumentComponents() method in src/parser.ts expects a # Title heading immediately after frontmatter. However, MyST documents often have target anchors before the title:

---
jupytext:
  ...
---

(about_py)=           <-- Target anchor
\```{raw} jupyter   <-- Raw block  
...
\```

# About These Lectures  <-- Title is HERE, not immediately after frontmatter

This causes parseDocumentComponents() to throw:

Expected # title heading at line 12, found: (about_py)=

Current Impact

  • Bulk Translator: Fixed by switching to parseSections() for heading-map generation
  • Incremental Sync (file-processor.ts): May fail on source files with this structure

Requested Changes

  1. Add test cases to src/__tests__/parser-components.test.ts for documents with:

    • Target anchors (anchor-name)= before title
    • Raw blocks before title
    • Index directives before title
    • Combination of the above (like real QuantEcon lectures)
  2. Update parseDocumentComponents() to handle content between frontmatter and title:

    • Skip target anchors (...)=
    • Skip MyST directives before title
    • Find the # Title heading wherever it appears

Test Fixture

Use the structure from lecture-python-programming.myst:

---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

(about_py)=
\```{raw} jupyter
<div id="qe-notebook-header">...</div>
\```

\```{index} single: python
\```

# About These Lectures

Related

  • Discovered while testing bulk translator with Persian translation
  • The fix for bulk translator is in place (uses parseSections() instead)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions