Code block guidelines

To create a code block:

• Use triple-grave characters (```) as a fence, and enter a language name after the first ``` fence
• Indent lines by four spaces or one tab

Learn about conventions for code blocks

Learn about code block special formatting and functionality

Here is an example of a JSON code block:

```json
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```

The rendered output looks like this:

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

Add output

To add the output of your code block, create a second code block below the first and add the output property to the opening code fence, like this:

npx wrangler vectorize create tutorial-index --dimensions=3 --metric=cosine

✅ Successfully created index 'tutorial-index'

[[vectorize]]
binding = "VECTORIZE_INDEX" # available in your Worker on env.VECTORIZE_INDEX
index_name = "tutorial-index"

```sh
npx wrangler vectorize create tutorial-index --dimensions=3 --metric=cosine
```

```txt output
✅ Successfully created index 'tutorial-index'

[[vectorize]]
binding = "VECTORIZE_INDEX" # available in your Worker on env.VECTORIZE_INDEX
index_name = "tutorial-index"
```

Languages

To define the language of your code block, enter the name of the language after the first ``` fence.

If there is no appropriate syntax language, use txt (for example, a fragment of an Apache configuration file).

Make sure you enter the language name in lower case, since other capitalizations of these names are not supported. For example, entering JavaScript would use the txt language.

Here is a list of supported languages:

• bash (alias: curl) Learn more about terminal commands
• c
• diff
• go
• graphql
• hcl (alias: tf)
• html
• ini
• java
• js (alias: javascript)
• json Learn more about JSON commands
• kotlin
• php
• powershell Learn more about terminal commands
• python (alias: py)
• ruby (alias: rb)
• rust (alias: rs)
• sh (alias: shell) Learn more about terminal commands
• sql
• swift
• toml
• ts (alias: typescript)
• txt (aliases: text, plaintext, no language name)
• xml
• yaml (alias: yml)

Terminal commands

Use sh for one-line commands executed in the Linux/macOS terminal.

• Each command must be in a single line
• Use "$ "(dollar sign, space) or "FOLDER_NAME $ " (folder name, space, dollar sign, space)
• Examples:
  • $ command-to-run
  • ~/my-folder $ command-to-run (where ~ means the home folder of the current user)

Note

The Copy to clipboard button (top-right corner of the code block) will copy the entire content, not just what the reader can select.

Use bash for other Linux/macOS/generic commands.

• For example:
  • Commands that span multiple lines (usually each line ends with a \) and may include one or more lines of JSON content
  • Commands for specific shells (for example, a command specifically for the zsh shell, where the prompt is usually %)
• If a code block contains only one (multi-line) command, do not include a $ prefix so that the user can run the command immediately after copying and pasting without having to remove the prefix
• If a code block includes several commands or it includes output, consider including a prefix before each command to help differentiate between commands and their output
• For zsh-specific instructions you can use a % command prefix instead of $

Use the powershell language for Windows PowerShell commands.

• By default, do not use any prompt prefixes for PowerShell commands
  • If you need to establish context (for example, you must be in a specific folder before running a command), use the following prompt:
    • "PS FOLDER_NAME> " (the > is part of the prompt, and there is a space after it)
    • Examples:
      • PS C:\> command-to-run.exe
      • PS C:\Users\JohnDoe> command-to-run.exe

Use the txt language for Windows console commands.

• Use "FOLDER_NAME>" (folder name, greater than symbol, no space after)
• Alternatively, do not include any prompt and start the line with the command the user must enter (knowing that it will be harder to understand what must be entered and what is example output)
• Examples:
  • C:> command-to-run.exe
  • C:\Program Files> command-to-run.exe
  • C:\Users\JohnDoe> command-to-run.exe

JSON

Use json for JSON code blocks or JSON fragments.

Multi-line curl commands with a JSON body should use bash syntax highlighting instead.

Note

JSON fragments may appear with a red background in GitHub because they are not valid JSON. Make it clear in the documentation that it is a fragment and not an entire piece of valid JSON content.

Add special formatting

You can add special formatting to code blocks, such as collapsed sections, line numbers, and highlighting. Here is a showcase of some of the functionality. You can find more options at Expressive Code ↗, a project by Astro.

Write string example

Write-Output "This one has a title"

JavaScript

// Collapsing
const foo = {
  1: 1,
  2: 2,
  3: 3,
};

JavaScript

// Line numbers
const foo = "bar";
const bar = "baz";

JavaScript

// Example with wrap
function getLongString() {
  return "This is a very long string that will most probably not fit into the available space unless the container is extremely wide";
}

JavaScript

function demo() {
  console.log("These are inserted and deleted marker types");
  // The return statement uses the default marker type
  return true;
}

JavaScript

function thisIsJavaScript() {
  // This entire block gets highlighted as JavaScript,
  // and we can still add diff markers to it!
  console.log('Old code to be removed')
  console.log('New and shiny code!')
}

```powershell title="Write string example"
Write-Output "This one has a title"
```

```js collapse={3-5}
// Collapsing
const foo = {
  1: 1,
  2: 2,
  3: 3,
};
```

```js showLineNumbers
// Line numbers
const foo = "bar";
const bar = "baz";
```

```js wrap
// Example with wrap
function getLongString() {
  return "This is a very long string that will most probably not fit into the available space unless the container is extremely wide";
}
```

```js "return true;" ins="inserted" del="deleted"
function demo() {
  console.log("These are inserted and deleted marker types");
  // The return statement uses the default marker type
  return true;
}
```

```diff lang="js"
  function thisIsJavaScript() {
    // This entire block gets highlighted as JavaScript,
    // and we can still add diff markers to it!
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }
```

Warning

Do not use the $ sign in your code blocks before a command.

Workers Playground

If you add the playground option to the opening code fence for a Worker example, it will add a "Run Worker in Playground" link that will take the user to the Worker's playground.

Live demo

JavaScript

export default {
  fetch() {
    return new Response("Test!");
  },
};

Run Worker in Playground

How to use

```js playground
export default {
  fetch() {
    return new Response("Test!");
  },
};
```

Run Worker in Playground

GraphQL API Explorer

Add graphql-api-explorer to the opening code fence to create a graphql code block with a Run in GraphQL API Explorer button that leads to GraphQL API Explorer ↗.

Note

This button only works if the person selecting it is logged in or has an API token saved.

A GraphQL query

query ASingleDatasetExample($zoneTag: string, $start: Time, $end: Time) {
  viewer {
    zones(filter: { zoneTag: $zoneTag }) {
      firewallEventsAdaptive(
        filter: { datetime_gt: $start, datetime_lt: $end }
        limit: 2
        orderBy: [datetime_DESC]
      ) {
        action
        datetime
        host: clientRequestHTTPHost
      }
    }
  }
}

Run in GraphQL API Explorer

```graphql graphql-api-explorer title="A GraphQL query"
query ASingleDatasetExample($zoneTag: string, $start: Time, $end: Time) {
  viewer {
    zones(filter: { zoneTag: $zoneTag }) {
      firewallEventsAdaptive(
        filter: { datetime_gt: $start, datetime_lt: $end }
        limit: 2
        orderBy: [datetime_DESC]
      ) {
        action
        datetime
        host: clientRequestHTTPHost
      }
    }
  }
}
```

Variables

In the GraphQL API Explorer, the Variables section is automatically filled based on the names and types of the variables defined in your query:

• Variables that include start and are of type Time are set to six hours before the current time
• Variables that include end and are of type Time are set to the current time
• Variables that include start and are of type Date are set to 24 hours before the current date
• Variables that include end and are of type Date are set to the current date
• Variables that include zoneTag and are of type string are set to "ZONE_ID"
• Variables that include accountTag and are of type string are set to "ACCOUNT_ID"
• Variables that include id and are of type string are set to "REPLACE_WITH_ID"
• Variables that include limit and are of type int are set to 100
• Any other variable with a type of string is set to "REPLACE_WITH_STRING"

You can also add custom variables by setting their values as a JSON string in the graphql-api-explorer metadata. The custom variables will be merged with the automatically populated variables.

In the following example, the custom value is custom-variable:

```graphql graphql-api-explorer='{"uID": "custom-variable"}' title="A GraphQL query"
query GraphqlExample($zoneTag: string, $start: Time, $end: Time) {
 viewer {
   zones(filter: { zoneTag: $zoneTag }) {
     ...
   }
 }
}
```

So, the Variables would look something like this:

{"zoneTag":"ZONE_ID", "start":"2025-09-11T14:00:00Z", "end":"2025-09-11T20:00:00Z", "uId": "custom-variable"}