Skip to content

docs(codelab): embed local images in generated Colab notebook#272

Merged
haiyuan-eng-google merged 1 commit into
GoogleCloudPlatform:mainfrom
caohy1988:docs/codelab-notebook-image-embed
Jun 2, 2026
Merged

docs(codelab): embed local images in generated Colab notebook#272
haiyuan-eng-google merged 1 commit into
GoogleCloudPlatform:mainfrom
caohy1988:docs/codelab-notebook-image-embed

Conversation

@caohy1988
Copy link
Copy Markdown
Collaborator

Summary

Fixes the broken image reference in the checked-in Colab notebook (the non-blocking caveat from #271). The codelab references images by repo-relative path (e.g. images/ca-conversation.png) so claat copies them into img/ — but Colab can't resolve a repo path, so the generated notebook's image was broken.

Change: scripts/generate_colab_from_codelab.py now rewrites local markdown image refs into base64 data URIs during notebook generation (resolved relative to the source markdown's directory). The notebook then renders the image inline in Colab.

  • Source codelab markdown is unchanged → claat still uses the relative path and copies the file into img/.
  • Remote (http(s)://), data:, and attachment: refs are left untouched.
  • A missing local image fails loudly (FileNotFoundError) so a broken ref can't slip through.
  • examples/codelab/periodic_materialization/colab_notebook.ipynb regenerated — the CA screenshot is now embedded (1 data URI, 0 relative paths).

Tests

New tests/test_generate_colab_images.py pins the behavior so a future local image can't drift back to a broken Colab ref:

  • local image → data:image/png;base64,… (and round-trips to the original bytes)
  • remote / data / attachment refs unchanged
  • missing local image raises
  • build_notebook(..., base_dir=...) embeds; without base_dir it's a no-op (backward compatible)

Test plan

  • tests/test_generate_colab_images.py — 5 pass
  • Notebook drift --check in sync
  • bash autoformat.sh clean (pyink + isort)

The codelab references images by repo-relative path (so claat copies them into
img/), but Colab can't resolve a repo path, leaving the checked-in notebook
with a broken image ref. Teach the generator to rewrite local markdown image
refs into base64 data URIs (resolved relative to the source markdown dir);
remote/data/attachment refs are left unchanged, and a missing local image now
fails loudly. Source markdown is unchanged, so claat still uses the relative
path. Adds unit tests so a future local image can't drift back to a broken
Colab ref; notebook regenerated with the CA screenshot embedded.
@haiyuan-eng-google haiyuan-eng-google merged commit f4a9477 into GoogleCloudPlatform:main Jun 2, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants