Fill-in placeholders

Examples for an API often contain values that each reader has to change, such as YOUR_TOKEN. In a normal code block, readers copy the code and then edit it by hand. The placeholder attribute turns those values into fields. What a reader types fills every block on the site, and the copied code.

Readers see

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/workspaces/WORKSPACE_ID/runs

from example import Client

client = Client(token="YOUR_TOKEN")

You write

```sh placeholder="YOUR_TOKEN,WORKSPACE_ID"
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/workspaces/WORKSPACE_ID/runs
```

```py placeholder="YOUR_TOKEN"
from example import Client

client = Client(token="YOUR_TOKEN")
```

Type a token into a YOUR_TOKEN field in one block, and the field in the other block shows it too. Each field is as wide as its text, and keeps the colour of the string it is in. The copy button copies the code with your values.

Syntax

Syntax	Where
placeholder="<A>,<B>"	Code block fence line
placeholders.storage="local", "session" or "none"	Code block fence line

The attribute lists the literal texts to turn into fields, separated by commas. Every match of each text in the block becomes a field. If one text contains another, the longer text wins where both match.

Examples

Values in a playground

This block combines fill-in placeholders with a playground button, to show that the playground gets the reader’s value. Type a token, then click Open in TS Playground:

Output

Open in TS Playground (opens in a new tab)

const response = await fetch('https://api.example.com/v1/runs', {
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
});
console.log(await response.json());

Source

```ts placeholder="YOUR_TOKEN" playground="typescript"
const response = await fetch('https://api.example.com/v1/runs', {
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
});
console.log(await response.json());
```

Behaviour

• Fields:
  • A field shows its placeholder text until the reader types. Its accessible name is the placeholder text.
  • A field is as wide as its placeholder text or its value, whichever is longer.
• Typing:
  • Typing in a field updates every field with the same text on the page. Pages that load later show the value too.
  • Escape in a field clears its value, in every field with the same text.
  • Values stay in the reader’s browser. The plugin never sends them anywhere.
• Copy, playgrounds and print:
  • The copy button copies the code with the reader’s values. An empty field copies its placeholder text. A manual copy of a selection in the block copies the same way.
  • A playground button opens the code with the reader’s values.
  • A field prints as its text, without the border: the value if the reader typed one, or else the placeholder text.
• Warnings:
  • If a text in the attribute is not in the code, the build logs a warning.
• Without JavaScript:
  • Fields are plain inputs. They do not update each other, and the copy button copies the placeholder text.

Danger

Tell readers where their values go. With the default storage: 'local', the browser keeps the values after the reader closes the tab. On a shared computer, the next person can see them.

Options

placeholders

Turns placeholder text into input fields. Set it to false to turn the feature off.

Type

false | object

Default

On

placeholders.storage

Where the browser keeps the values that readers type. A code block can set its own on its fence line.

Type

'local' | 'session' | 'none'

Default

'local'

'local' keeps values across visits. 'session' keeps them until the reader closes the tab. 'none' keeps them only while the page is open. For a site where readers type secrets, such as API tokens, use 'session':

astro.config.mjs

codeblocks({
  placeholders: { storage: 'session' },
});

ConfigurationLearn how to set options for the whole site, or for a single code block.

Limitations

• A field matches literal text only. A text that also appears in a place that is not a placeholder becomes a field there too. Choose texts such as YOUR_TOKEN that appear nowhere else.
• A custom url playground gets the reader’s values only if it puts the code in the URL with encodeURIComponent(). A custom post playground must put the code in a field as it is.

Related

• Open in playground: open the code, with the reader’s values, in an online playground.
• Hidden lines: hide set-up lines, such as the line that reads a token from the environment.