Documentation

Code

You can use standard Markdown syntax, this is called "code blocks." It is also possible to render code blocks in two different themes, add titles to them, highlight lines, simulate a terminal and wrap multiple languages for a UI with a language selector.

The "code examples" feature allows pulling code samples from separate files. This can be useful for autogenerated code samples or such that go through automated testing.

Note that the alternative Markdown syntax for code blocks obtained by indenting by 4 spaces the content is not supported.

Code blocks

  • To add titles for the code blocks, pass title="my title" after the language tag.
  • The primary theme is the default. To render the code block in the secondary theme, pass secondaryTheme in the extended language tag syntax.

In its minimal form, code blocks are standard markdown as follows:

you write:md
```
The syntax is not highlighted as no language is indicated.
**Formatting syntax** like _this_ or <b>tag</b> will remain unparsed.
```
The syntax is not highlighted as no language is indicated.
**Formatting syntax** like _this_ or <b>tag</b> will remain unparsed.

Themes, title

Primary theme (default)

you write:md
```md title="Code block in primary theme"
Sample code goes here.
```
Code block in primary thememd
Sample code goes here.

Secondary theme

you write:md
```md title="Code block in secondary theme" secondaryTheme
Sample code goes here.
```
Code block in secondary thememd
Sample code goes here.

With highlighted lines

It is also possible to highlight specific lines in a code. To highlight, pass highlightLines in the syntax and enter the range or specific line to be highlighted. The expected syntax for highlightLines is a comma separated string which can contain either a single number or a range. A range can be specified either as dash separated 1-5 (meaning from line 1 to 5 inclusive) or separated by 2 dots 1..5 (meaning from line 1 to 5 inclusive) or separated by 3 dots 1...5 (meaning from line 1 to 5, with 5 not inclusive).

you write:md
```json highlightLines="8,10,1-3,12..14,18...21"
{
  "glossary": {
    "title": "example glossary",
    "GlossDiv": {
      "title": "S",
      "GlossList": {
        "GlossEntry": {
          "ID": 123.45,
          "Sort": true,
          "GlossTerm": "Standard Generalized Markup Language",
          "Acronym": "SGML",
          "Abbrev": "ISO 8879:1986",
          "GlossDef": {
            "para": "A meta-markup language, used to create markup languages such as DocBook.",
            "GlossSeeAlso": ["GML", "XML"]
          },
          "GlossSee": null
        }
      }
    }
  }
}
```
{
  "glossary": {
    "title": "example glossary",
    "GlossDiv": {
      "title": "S",
      "GlossList": {
        "GlossEntry": {
          "ID": 123.45,
          "Sort": true,
          "GlossTerm": "Standard Generalized Markup Language",
          "Acronym": "SGML",
          "Abbrev": "ISO 8879:1986",
          "GlossDef": {
            "para": "A meta-markup language, used to create markup languages such as DocBook.",
            "GlossSeeAlso": ["GML", "XML"]
          },
          "GlossSee": null
        }
      }
    }
  }
}

Terminal / console with prompt

using language console instead of sh prefixes a $ as command prompt to each line:

curl -H "Content-Type: application/json" \
  "https://api.europe-west1.gcp.commercetools.com"

To omit he prompt on certain lines, add the option noPromptLines="3-4".

cd project
cp -R \
  dist \
  public/
rm -rf dist
yarn start

No options, but you can check that the indentation in regards to the left prompt is aligned when the line wraps.

# fetch a token:
curl https://auth.sphere.io/oauth/token --basic --user "{client_id}:{client_secret}" -X POST -d "grant_type=client_credentials&scope=manage_project:{project_key}"
# now access the API:
curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.sphere.io/PROJECT_KEY/products

Passing the option title="Fetching an access token"

Fetching an access tokenTerminal
# fetch a token:
curl https://auth.sphere.io/oauth/token --basic --user "{client_id}:{client_secret}" -X POST -d "grant_type=client_credentials&scope=manage_project:{project_key}"
# now access the API:
curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.sphere.io/PROJECT_KEY/products

Multi language code blocks in markdown

It's possible to nest multiple markdown code blocks into one <MultiCodeBlock> element to have them display as a multi language code example without having to delegate the content into file using the <CodeExample> and <MultiCodeExample> features from the gatsby-theme-code-examples add-on.

you write:md
<MultiCodeBlock>


```js
console.log('this is it in javascript');
```


```php
echo "this is it in PHP"
```


</MultiCodeBlock>
console.log('this is it in javascript');

Code examples from files

The <CodeExample> and <MultiCodeExample> components allow pulling code examples from files in the repository. The files have to be placed into src/code-examples in the microsite folder. The path parameter refers to them relative to that folder, for example path="basics/example.json" refers to src/code-examples/basics/example.json

The language is derived from the file suffix.

Some parameters available on the markdown code blocks above can be passed as properties, for example highlightLines, noPromptLines. title has to be passed on the level of the multi code block, the layout does not allow for per-language titles.

Single language

you write:md
<CodeExample path="example.graphql" title="GraphQL code sample" />
GraphQL code samplegraphql
type Person {
  id: ID!
  name: String!
  age: Int
}

Multiple languages

Similarly to standard code blocks, you can render multiple code examples combined into one code block, with a dropdown option to switch between the code examples.

This functionality requires the Add-On for Code Examples to be installed.

Primary theme (default)

you write:md
<MultiCodeExample title="Multilanguage code samples">
  <CodeExample path="example.js" highlightLines={[3]} />
  <CodeExample path="example.java"/>
  <CodeExample path="example.console" noPromptLines={[3, 4]} />
</MultiCodeExample>
Multi-language code samples in primary theme
// Arrow function sample
const arrowFuncSample = () => {
  console.log('this is an arrow function example');
};

Secondary theme

<MultiCodeExample title="Multilanguage code samples" secondaryTheme>
  <CodeExample path="example.js" highlightLines={[3]} />
  <CodeExample path="example.java"/>
  <CodeExample path="example.console" noPromptLines={[3, 4]} />
</MultiCodeExample>
Multi-language code samples in primary theme
// Arrow function sample
const arrowFuncSample = () => {
  console.log('this is an arrow function example');
};