docs: surface pointer + trace playgrounds into a top-level Explore section#227
Open
gnidan wants to merge 10 commits into
Open
docs: surface pointer + trace playgrounds into a top-level Explore section#227gnidan wants to merge 10 commits into
gnidan wants to merge 10 commits into
Conversation
Content for the docs reorg (#17), authored for integration into docs' Explore section (docs/explore/, per gnidan's Option A + build-fresh-and- trim). Authoring source for docs to integrate onto docs-explore-section. - explore/trace-playground.mdx: learn-by-doing (counter -> function call -> tail-call optimization). - explore/pointer-playground.mdx: curated cross-topic (memory region, storage slot, struct group, computed-slot expression). - explore/index.mdx: Explore hub linking the three playgrounds. - explore/bug-playground.mdx: moved from examples/. - core-schemas/programs/tracing.mdx: trimmed to reference; interactive examples moved to the Trace playground. - implementation-guides/building-a-trace-viewer.mdx: extracted how-to. - pointers/{regions,collections,expressions}.mdx: interactive examples removed, schema tables + prose kept, playground cross-links added. All internal links point at /docs/explore/*.
Structural wiring to complete the Explore section reorg: - add explore/_category_.json (label "Explore", sidebar position 2) - add navbar "Playground" item -> /docs/explore - renumber subsequent categories (Getting started 3, Concepts 4, Core schemas 5, Implementation guides 6; Reference 7) - order Explore pages: Pointer / Trace / BUG playground per plan - repoint former /docs/examples links (overview, getting-started, compiler guides) to /docs/explore and drop the stale resources pagination override Composes with the Explore content + reference trims. Part of #17.
Contributor
|
Per review: remove the top-nav Playground entry so the header reads Documentation | Specification. The Explore sidebar section (the core reorg) stays. Part of #17.
explore/index.mdx carried pagination_prev: core-schemas/info/resources from the old examples/ page (position 6). With Explore now at position 2, that pointed Previous forward into Core schemas; drop it so Previous auto-links to Project overview. Part of #17.
Per review, replace the toy pointer examples with real Solidity storage layouts: packed sub-slot address, dynamic array element (keccak256(5)+i), mapping value (keccak256(key,3)), and the flagship short/long storage string (one pointer resolved against both short and long state). Content authored by writer; keeps sidebar_position 2 (Pointer/Trace/BUG). #17.
lint-staged's glob skips .mdx, so the rebuilt examples slipped past the local hook; apply prettier (quote-style only). #17
Per gnidan #227 review: Explore now sits after Reference (position 8) instead of position 2.
- pointer-playground: mark "pointer" as an ethdebug/format noun (bold+link to the pointers reference) - bug-playground: introduce BUG + bugc (optimizing reference compiler) and the self-referential validation angle - Explore CTA sidebar_labels (drop "Playground"): per-item call-to-action wording
- core-schemas/pointers/index.mdx: mark "pointer"/"ethdebug/format" as nouns on first use (harmonizes with the Explore pointer intro) - trace CTA sidebar_label: drop "live"
gnidan
added a commit
that referenced
this pull request
Jul 3, 2026
#243) The docs BugPlayground only ever showed one program; the example picker lived in the standalone packages/playground app. Port a lean version into the docs widget (gnidan #33). - bugc-react: add a curated `bugExamples` set (Counter, Function calls, Arrays & loops) as a reusable export. Sources are distilled from packages/bugc/examples and stripped of the `/*@test*/` behavioral annotations the raw files carry, so they read cleanly in an editor. examples.test.ts asserts each compiles to bytecode without errors (guards against a typo in an inlined source); adds the missing vitest.config.ts so the package's test script runs. - web BugPlayground: add an optional `examples` prop (defaults to bugExamples) and an Example dropdown in the header controls. The selector shows only when no `initialCode` is passed — so the bare playground page gains it while inline single-example doc embeds stay unchanged. Selecting an example loads its source and recompiles. Additive; does not affect the tracer or #227. Example sources verified to compile via the new tests; UI wiring mirrors the existing optimizer selector.
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
1 participant
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.
Surfaces the interactive pointer and trace playgrounds out of the dense Core
Schemas reference and into a dedicated top-level Explore section — the
project's best teaching material, previously buried under reference/spec pages.
This is a
packages/web(docs site) change only — no spec/schema changes.Structure (docs/web)
overview): Pointer Playground, Trace Playground, BUG Playground, plus a hub
landing page.
categories renumbered (Getting started 3 … Reference 7).
/docs/examples/*links (overview, getting-started,compiler guides) to
/docs/explore/*and drops a stale pagination override.Content (docs/web)
(pointers: memory slice / storage slot / struct group / computed slot;
tracing: counter → function call → tail-recursive sum → factorial).
(regions/collections/expressions/tracing), keeping schema tables + static
SchemaExamples + spec links, with cross-links to the playgrounds.
Prose authored by writer (commit d585ddd); structural wiring by docs.
Note: the old
/docs/examples/*URLs change to/docs/explore/*. Allin-repo links are updated; a client-side redirect for external inbound links
is a possible follow-up (needs the plugin-client-redirects dependency).