prism

Display a styled code block with many configurable options.

Plain syntax highlighting is available with code fences alone.

{{< prism <parameters> >}}
code block contents here
{{< /prism >}}

Options include:

• language: Language-specific syntax highlighting. Supported languages include HTML, CSS, C, JavaScript, shell, Bash, Git, Go, JSON, Markdown, Python, text, and YAML.

Note

To display HTML code examples correctly, you must add the html value to the language field.

• lineNumbers: Set to true to enable line numbering.

• startLineNumbers: Start from a line number other than 1.

• highlightLines: Lines to highlight. Comma separated and hyphenated ranges.

• title: Adds a title to the top of the code block.

• prefix: Add a prefix to single line of code, like mysql>.

• currently broken, prompt: Shows a command line prompt in the left gutter, like user@localhost.

• skipPrompt: Lines to skip displaying the prompt. Comma separated and hyphenated ranges.

• copy: Custom text to copy to the clipboard.

Inline Highlighting

In code examples that use prism, you can highlight pieces of code, such as placeholder values, within the code example using the highlight shortcode. For example, the following code with the highlight shortcode:

{{< prism title="packages/cloud/postEmail/index.js" language="js" lineNumbers="true" >}}
async function main(args) {
     let client = {{<  highlight >}}new MongoClient(uri);{{<  /highlight >}}
{{< /prism >}}

would render as:

    
        
            
async function main(args) {
     let client = <mark>new MongoClient(uri);</mark>

        
    

Note

You cannot use inline highlighting on HTML code examples. This is because Hugo cannot properly escape (display) HTML examples without using the safeHTMLAttr function in the shortcode, which overrides the functionality of prism’s Keep Markup plugin.

Inline highlighting uses the Keep Markdown plugin for Prism.

Download Button

You can render a download button for a code example by adding the title option to the prism code block. This makes the example downloadable as whatever file type you denote in the title. For example, if you add title="src/index.js" to a Prism code block, the code example downloads as index.js when you click the Download button.

You must provide a file extension for the title’s value for the Download button to render. The Download button supports most common MIME types. If you add an extension that is not supported, the file downloads as a .txt file.

Examples

{{< prism language="shell" highlightLines="3" prompt="user@localhost:~$" >}}
curl -X POST "https://api.digitalocean.com/v2/Droplets" \
      -d'{"name":"metadata.example.com","region":"nyc3","size":"s-1vcpu-1gb","private_networking":true,"image":"ubuntu-14-04-x64","user_data":
"'"$(cat ~/user-data.yml)"'",
      "ssh_keys":[ < SSH KEY IDs > ]}' \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json"
{{< /prism >}}

Renders to:

    
        
            
curl -X POST "https://api.digitalocean.com/v2/Droplets" \
      -d'{"name":"metadata.example.com","region":"nyc3","size":"s-1vcpu-1gb","private_networking":true,"image":"ubuntu-14-04-x64","user_data":
"'"$(cat ~/user-data.yml)"'",
      "ssh_keys":[ < SSH KEY IDs > ]}' \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json"

        
    

Prism Maintenance

The JavaScript that powers the Prism shortcode is located in the product-docs/static/prism.js file. The plugin’s CSS is located in the product-docs/assets/sass/prism.css file. These files are imported into the layout via the /product-docs/layouts/partials/scripts.html file.

You can find documentation and updates to prism on the official prism website.

The Download button’s logic is mostly custom and you can find it at the bottom of the prism.js file.