docs(codelab): match the published Google Codelab format (issue #96)#274
Merged
haiyuan-eng-google merged 2 commits intoJun 2, 2026
Conversation
…shed Google Codelab format Aligns docs/codelabs/periodic_materialization.md with the reference codelab format in issue GoogleCloudPlatform#96 (Context Caching in BigQuery), while preserving the dual-purpose colab markers so the self-contained Colab notebook still generates. Format changes: - Frontmatter: ---delimited YAML with id, summary, authors, keywords (category:/product:), layout: paginated (drops categories/tags/status/ feedback-link in favor of the GoogleCloudPlatform#96 metadata set). - Per-section Duration switched to MM:SS (e.g. 05:00); total 42 min. - Tips/notes converted to claat asides (> aside positive / > aside negative) -- renders as 6 special + 1 warning callout boxes. - Section titles sentence-cased and de-numbered (dropped 'Phase N:'), matching GoogleCloudPlatform#96's descriptive step titles; in-body cross-references updated. - Bold action phrases, console output fences, and an intro workflow diagram. - Ending reshaped to ## Congratulations + #### What you've learned + #### Reference docs. Generator: strip claat aside marker lines (> aside positive/negative) when building the notebook so the marker text does not leak into Colab; the callout body renders as a plain blockquote. Adds tests/test_generate_colab_asides.py. Notebook regenerated; --check passes. claat export builds clean (exit 0).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reformats the periodic-materialization codelab (
docs/codelabs/periodic_materialization.md) to follow the published Google Codelab format demonstrated in the reference example codelab (Context Caching in BigQuery, issue #96). Runnable commands and queries are preserved; the changes are presentation/reader-flow oriented.The dual-purpose
<!-- colab:* -->markers are HTML comments invisible to claat, so the rendered codelab now matches #96 and the self-contained Colab notebook still generates from the same source.This PR also adds the BigQuery Studio graph visualization (
images/graph-visualization.png) to the Query the decision trace step, using the same generated-notebook image embedding path as the existing codelab images.Format changes (to match #96)
----delimited YAML:id,summary,authors,keywords: category:..., product:...,layout: paginated(dropscategories/tags/status/feedback linkin favor of the BigQuery Agent Analytics Roadmap #96 metadata set).MM:SSper section (claat totals 42 min, and the intro estimate now matches).> aside positive/> aside negative). Renders as 6special+ 1warningcallout boxes.Phase N:), matching BigQuery Agent Analytics Roadmap #96's descriptive step titles; all in-body cross-references updated to track the new titles.consoleoutput fences, and an intro workflow diagram (images/context-graph-flow.png).images/graph-visualization.png) with qualifiedGRAPH ${DATASET}.agent_decisions_graphguidance.## Congratulations+#### What you've learned+#### Reference docs.Generator change
claat aside marker lines (
> aside positive/> aside negative) would otherwise leak into the Colab notebook as literal blockquote text. Taughtscripts/generate_colab_from_codelab.pyto strip those marker lines (same pattern it already uses forDuration:lines) so the callout body renders as a plain Markdown blockquote in Colab. Addedtests/test_generate_colab_asides.py.Verification
generate_colab_from_codelab.py --checkpasses (notebook regenerated, no drift).aside/Durationlines, 0 broken relative image refs, 0curl(still self-contained), 3 base64-embedded PNG images.claat exportbuilds clean (exit 0); images copied intoimg/; asides render as callout boxes.pytest tests/test_generate_colab_asides.py tests/test_generate_colab_images.py tests/test_codelab_embedded_artifacts.py-> 12 passed.