fix(ci): replace yq with surgical Python nav patching

[andreatgretel]

Summary

• Replace yq JSON roundtrip with Python-based text replacement in publish-devnotes.yml
• The yq approach was mangling the entire mkdocs.yml (indentation, quoting, comments), causing mike deploy to fail
• The Python script surgically replaces only the Dev Notes nav block, leaving all other content untouched

Follow-up to #546

[greptile-apps]

Greptile Summary

This PR replaces a yq JSON-roundtrip approach (which was mangling mkdocs.yml indentation and comments) with a small Python script that performs a targeted text-level replacement of only the Dev Notes nav block. The docs file receives a date update, HTML-to-MkDocs image syntax conversion, a URL correction, and two removed reference links.

Confidence Score: 5/5

• This PR is safe to merge — the Python nav-patching logic is correct and all remaining findings are P2 or lower.
• No P0 or P1 issues were found. The boundary-detection logic in the patch script correctly handles 6-space-indented sub-items (confirmed against the actual mkdocs.yml), blank lines, and YAML comment lines. The workflow integration is straightforward, and the docs changes are purely cosmetic/content updates.
• No files require special attention.

Important Files Changed

Filename	Overview
.github/scripts/patch-devnotes-nav.py	New Python script that surgically extracts and splices the Dev Notes nav block; boundary detection correctly handles 6-space-indented sub-items (matching the actual mkdocs.yml), blank lines, and comment lines. Logic is sound and idempotent.
.github/workflows/publish-devnotes.yml	Replaces yq roundtrip with the new Python patch script; correctly checks out patch-devnotes-nav.py from HEAD alongside devnotes, writes HEAD's mkdocs.yml to /tmp, and invokes the script against the old source's mkdocs.yml.
docs/devnotes/posts/text-to-sql.md	Documentation-only changes: updated date, converted raw HTML img tags to MkDocs Material attribute syntax, updated a URL, and trimmed two reference links.

Sequence Diagram

sequenceDiagram
    participant GH as GitHub Actions
    participant GHP as gh-pages branch
    participant Repo as Repository
    participant Tmp as /tmp
    participant Script as patch-devnotes-nav.py
    participant MkDocs as mkdocs.yml (old source)

    GH->>GHP: "fetch origin gh-pages --depth=1"
    GHP-->>GH: last deploy commit (SOURCE_SHA, VERSION)
    GH->>Repo: git checkout SOURCE_SHA
    Repo-->>GH: old source state
    GH->>Repo: git checkout github.sha -- docs/devnotes/ .github/scripts/patch-devnotes-nav.py
    Repo-->>GH: new devnotes + patch script overlaid
    GH->>Repo: git show github.sha:mkdocs.yml
    Repo-->>Tmp: mkdocs-head.yml (HEAD nav)
    GH->>Script: python3 patch-devnotes-nav.py /tmp/mkdocs-head.yml mkdocs.yml
    Script->>Tmp: extract Dev Notes block from HEAD mkdocs.yml
    Script->>MkDocs: extract Dev Notes block from old mkdocs.yml
    Script->>MkDocs: splice HEAD block into old file (surgical replace)
    MkDocs-->>GH: patched mkdocs.yml (only Dev Notes nav updated)
    GH->>GH: mike deploy --push --update-aliases VERSION latest

Loading

_{Reviews (1): Last reviewed commit: "refactor(ci): extract nav patching into ..." | Re-trigger Greptile}