fix: text-to-sql devnote date, images, and publish-devnotes nav

[andreatgretel]

Summary

Fixes three issues with the text-to-sql devnote published in #349, and a nav bug in the publish-devnotes workflow.

Changes

Fixed

• Post ordering: Date updated from 2026-03-11 to 2026-04-14 so the text-to-sql post appears at the top of the devnotes page instead of buried below older posts
• Broken images: Replaced raw <img> tags with markdown ![]() syntax - mkdocs rewrites relative paths for markdown images but not raw HTML, so the images were 404ing at the slug-based post URL
• Missing nav entry: The publish-devnotes workflow now overlays mkdocs.yml from HEAD (not just docs/devnotes/) so new nav entries are included in devnotes-only rebuilds

---

Generated with AI

[github-actions]

Docs preview: https://62d5fea4.dd-docs-preview.pages.dev

Notebook tutorials are placeholder-only in previews.

[greptile-apps]

Greptile Summary

This PR fixes three real bugs with the text-to-sql devnote: the post date is corrected to 2026-04-14 for proper ordering, two raw <img> tags are replaced with mkdocs markdown image syntax so relative paths resolve correctly at the slug-based URL, and the publish-devnotes workflow is updated to patch the "Dev Notes" nav section from HEAD's mkdocs.yml into the old source checkout so newly added nav entries aren't lost during devnotes-only rebuilds.

Confidence Score: 5/5

• This PR is safe to merge — all changes are targeted, well-reasoned fixes with no logic regressions.
• All three fixes address concrete, reproducible bugs (wrong ordering, 404 images, missing nav entries). No new logic paths are introduced in production code; the workflow change is limited to a controlled YAML patch using the Python yq wrapper against a known-good mkdocs.yml from the same repository.
• No files require special attention.

Important Files Changed

Filename	Overview
.github/workflows/publish-devnotes.yml	Adds a pip install yq + two-command yq patch to overlay the "Dev Notes" nav from HEAD's mkdocs.yml onto the old-source checkout; logic is correct and uses Python yq's jq syntax appropriately.
docs/devnotes/posts/text-to-sql.md	Date corrected to 2026-04-14, two raw <img> tags converted to mkdocs markdown syntax, LiveSQLBench URL updated, and stale cross-reference links removed from the Key Resources section.

Sequence Diagram

sequenceDiagram
    participant GH as GitHub Actions
    participant Git as Git (local)
    participant yq as yq (Python)
    participant Mike as mike deploy

    GH->>Git: checkout SOURCE_SHA (last deployed)
    GH->>Git: checkout github.sha -- docs/devnotes/
    GH->>yq: pip install yq
    GH->>Git: git show github.sha:mkdocs.yml
    Git-->>yq: mkdocs.yml content (HEAD)
    yq-->>GH: DEVNOTES_NAV (JSON of Dev Notes entries)
    GH->>yq: yq -y -i patch old mkdocs.yml with DEVNOTES_NAV
    yq-->>Git: mkdocs.yml updated in working tree
    GH->>Mike: mike deploy --push (SOURCE_SHA tree + new devnotes + patched nav)

Loading

_{Reviews (2): Last reviewed commit: "fix: text-to-sql devnote date, images, a..." | Re-trigger Greptile}

[github-actions]

Code Review: PR #546 — fix: text-to-sql devnote date, images, and publish-devnotes nav

Summary

Small, well-scoped fix PR (2 files, +4/−8) that addresses three issues with the text-to-sql devnote published in #349:

1. Date correction in docs/devnotes/posts/text-to-sql.md: updated from 2026-03-11 to 2026-04-14 so the post sorts to the top of the devnotes listing.
2. Broken images: replaced raw <img> HTML tags with mkdocs-compatible markdown ![](){} syntax, which allows mkdocs to rewrite relative paths correctly at the slug-based post URL.
3. Workflow overlay fix in .github/workflows/publish-devnotes.yml: the git checkout overlay now includes mkdocs.yml alongside docs/devnotes/, ensuring new nav entries are picked up during devnotes-only rebuilds.

Findings

docs/devnotes/posts/text-to-sql.md

• Image syntax is correct. The { width=800 } attribute syntax requires the attr_list mkdocs extension, which is enabled in mkdocs.yml (line 180). Both referenced assets (text-to-sql-pipeline.jpg, bird-benchmark-results.jpg) exist at docs/devnotes/posts/assets/text-to-sql/.
• Date change is reasonable. Moving from 2026-03-11 to 2026-04-14 (today) ensures proper sort order. The blog plugin uses the date frontmatter for ordering.
• Removed <br> tags. The extra spacing <br> tags after images were also removed, which is a clean simplification.

.github/workflows/publish-devnotes.yml

• Overlay change is correct. Adding mkdocs.yml to the checkout overlay (git checkout ${{ github.sha }} -- docs/devnotes/ mkdocs.yml) ensures that when a new devnote adds a nav entry, the updated mkdocs.yml is used during the build instead of the stale version from SOURCE_SHA.
• Low risk. The only scenario where this could cause issues is if mkdocs.yml has non-nav changes (e.g., plugin config, theme settings) between SOURCE_SHA and the triggering commit that are incompatible with the old docs state. This is unlikely in practice and the benefit clearly outweighs the risk.
• Trigger paths note (informational). The workflow triggers on docs/devnotes/** only, not on mkdocs.yml changes. This means a standalone mkdocs.yml nav reorder won't trigger a devnotes rebuild. This is pre-existing and acceptable — the overlay fix correctly handles the common case where nav updates accompany new devnotes.

Observation (out of scope)

• docs/devnotes/posts/async-all-the-way-down.md (line 103) also uses a raw <img> tag. If the same path-rewriting issue applies there, it may also have broken images at the served URL. Worth checking in a follow-up.

Verdict

Approve. All three fixes are correct, well-motivated, and low-risk. The PR is cleanly scoped and the description clearly explains the rationale for each change.

[dhruvnathawani]

LGTM!