Skip to content

docs: teach amounts, units and addresses with runnable examples #419

Open

Description

@IanoNjuguna

The gap

Our beginner pages explain what a UTxO and an address are, and the how-tos assume Haskell, Go or Rust. Nothing covers the three representations that every reader hits before writing any transaction, and every API expects exactly: an amount, a token unit, and an address prefix that names its network.

Those three are pure string and integer work, so they are also the only part of Cardano you can demonstrate in a browser without a wallet, a provider key or a node.

Two changes, as two stacked PRs:

  1. Turn on @docusaurus/theme-live-codeblock and put one runnable block in the wallet tutorial, so the numbers a payment form needs can be edited on the page.
  2. A new page under How To Guide → Beginner, "Numbers and Identifiers", with three focused blocks: ADA to lovelace, an asset name to its unit, and an address to its network and credential kind.

Why live blocks instead of code fences

A live block is compiled at build time, so a syntax error in one fails the build. Ordinary code fences drift silently; these cannot. The ones that need an SDK, a provider or a wallet stay ordinary blocks, because the import would throw in the browser and a playground that always errors teaches the wrong thing.

What is in scope

  • the three representations above, with worked interaction
  • the limits stated on the page: prefix and header byte only, no checksum verification
  • a pointer to where protocol parameters actually come from (/epochs/latest/parameters, the genesis file) rather than hardcoding a number copied from another network

What is not

  • a Mesh or Blaze sandbox. Nothing that imports those can run in a playground.
  • slot to wall-clock conversion as a widget. It needs systemStart and slotLength from the network's genesis file, and a wrong constant would be worse than no widget, so the page names the source instead.
  • any change to the Haskell, Go and Rust how-tos, or to the session recaps.

Acceptance: the theme is a dependency, one block on the wallet tutorial, one new beginner page, all three blocks render and react in a local build with no horizontal overflow, and npm run build passes with onBrokenLinks: throw.

Activity

  1. self-assigned this
    on Nov 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions