Commands and placeholders

Documentation is full of commands that only work after the reader changes a word in them: their name, a repository, a token. idocs draws a command as a code block, in colour, with the language in its header and two icon buttons: copy, and fill in, for those words.

Shell

git clone https://github.com/{yourname}/{repo}.git

Click the sliders icon, or a highlighted word in the command, type a name, and press Enter to copy. The number on the icon is how many values are still empty. The same name fills every command on the site, and is remembered for next time.

Placeholders

A placeholder is a word in {braces} or <angle brackets>: letters, digits, _ and -.

Written	Read as
`{yourname}`, `{repo-name}`	a value to fill in
`<you_pat>`, `<TOKEN>`	the same
`{Token}`, `<token>` and `<TOKEN>`	one value: case and `-` versus `_` do not matter
`${HOME}`, `{{ name }}`, `{a,b}`, `{1..3}`	not a placeholder: shell and templates are left alone
`\{literal}`	the text `{literal}`, with no backslash

Copying uses the values that are set and leaves the placeholder as written for the ones that are not.

Secrets

A name containing token, pat, jwt, key, secret or password (as a whole word: you_pat, api_key, not monkey) is a secret. Its field is a password field, the command shows •••••••• in its place, and the value is kept in memory until the tab closes. Other values are saved in the browser.

In a diagram

Every fenced block in a node’s Markdown file, a step’s note: or a view’s summary: is drawn this way: the language in the header, the code in colour, a copy button, and a fill-in button where there are placeholders.

HTTP request / response

Loading diagram…

Colour and the header

The header names the language: ```sh is Shell, ```yaml is YAML, and a block with no language is Text. A title goes after it with title="...":

```yaml title="diagram.yaml"
nodes:
  api: { kind: service }
```

Colours come from the theme’s own palette (--idocs-blue, --idocs-green and so on), so a diagram that restyles its tokens restyles its code, in both themes. Shell, YAML, JSON, HTTP and INI, TOML and .env files are read properly: commands and their flags, variables, keys, sections, headers. Other languages get strings, numbers and comments (TypeScript, JavaScript, Python, Go, Rust, Java, C, SQL, CSS, Ruby and similar), and the rest, such as HTML and Markdown, are left plain.

Placeholders in a language

Placeholders are looked for only in shell, plain text and configuration blocks: no language, sh, bash, zsh, console, powershell, text, env, ini, toml, yaml and http. In ts, html, json and other code, {x} and <x> are code, so they are left alone. Add vars to the fence to turn them on, or novars to turn them off:

```json vars
{ "owner": "{yourname}" }
```

```sh novars
echo {not-a-placeholder}
```

In a docs page

Use <Command> in an MDX page. Pass the command as an attribute: braces in the body of a tag are code in MDX.

import Command from '@the-package-labs/idocs-astro/Command.astro'

<Command lang="sh" title="Install" code="npm install @{yourname}/widgets" />

For several lines, use a template literal:

<Command code={`export TOKEN=<you_pat>
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/{org}/repos`} />

ShellInstall

export TOKEN=<you_pat>
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/{org}/repos

lang picks the colours and the name in the header, as in a fence, and title adds a caption next to it.