Inline code highlighting

Starlight shows inline code in the prose in one colour, with no syntax highlighting. A short expression such as a function call is then harder to read than the same code in a block. A {:lang} suffix at the end of the inline code gives it the syntax colours of that language. A site can also set a default language for all inline code.

Tip

If most of the code on your site is in one language, set it as the default in astro.config.mjs. All inline code then gets syntax highlighting, with no extra Markdown syntax.

Readers see

• In JavaScript, [] + {} is "[object Object]".
• In Python, from __future__ import braces raises SyntaxError: not a chance.
• In CSS, .modal { z-index: 99999 !important } is a cry for help.
• In a shell, rm -rf node_modules fixes most things.

You write

> - In JavaScript, `[] + {}{:js}` is `"[object Object]"{:js}`.
> - In Python, `from __future__ import braces{:py}` raises `SyntaxError: not a chance{:py}`.
> - In CSS, `.modal { z-index: 99999 !important }{:css}` is a cry for help.
> - In a shell, `rm -rf node_modules{:sh}` fixes most things.

Each piece of inline code with a suffix gets the colours and the background of the site’s code blocks. The plugin removes the suffix, so readers see only the code. Inline code without a suffix, such as astro.config.mjs, keeps the plain style of Starlight.

Syntax

Syntax	Where
`<code>{:<lang>}`	Inside the backticks, at the end of the code
`<code>`{:<lang>}	Directly after the closing backtick

<lang> is a language name or alias that Expressive Code knows, as in a code block: js, py, sh, css and others. Languages that the site adds in the shiki.langs option of Expressive Code work too. The suffix must follow the code or the backtick with no space between them.

Tip

If possible, use the first syntax, with the suffix inside the backticks. It is the same syntax as rehype-pretty-code, and it is valid in .md and .mdx files with no change.

Caution

MDX reads a {:js} after the closing backtick as a JavaScript expression, and the build fails. If you need to use this syntax with MDX, write a backslash before it: `res.ok`\{:js}. Some plugins read .md files as MDX too, such as starlight-versions and starlight-md-txt, so the backslash is needed in .md files on those sites. The backslash works in .md files on every site.

Behaviour

• Colours:
  • The inline code uses the site’s Expressive Code themes: the background and the token colours of the dark theme and the light theme.
  • The colours change with Starlight’s theme menu, the same as the code blocks.
  • The colours have the same contrast correction as the code blocks.
• The suffix:
  • The plugin removes the suffix from the page, in both forms.
  • Inline code without a suffix does not change, unless the site sets a default language.
• Warnings:
  • If Expressive Code does not know the language, the code shows as normal inline code and the build logs a warning with the file name. The plugin removes the suffix.
• Screen readers and copy:
  • The highlighted code is a normal code element. Screen readers and the copied text get the same characters as before.
• Without JavaScript:
  • The highlighting happens at build time, so it works without JavaScript. Pages with no code blocks get the colours too.

Options

inlineHighlighting

Adds syntax colours to inline code with a {:lang} suffix. Set it to false to turn the feature off.

Type

false | object

Default

On

inlineHighlighting.defaultLanguage

The language of inline code with no suffix. {:txt} keeps one piece of inline code plain.

Type

string | false

Default

false

A default language

Some sites have one main language, such as the API docs of a Python package. The defaultLanguage option highlights inline code with no suffix in that language:

astro.config.mjs

codeblocks({
  inlineHighlighting: { defaultLanguage: 'py' },
});

With this configuration, `len(items)` gets the Python colours. A suffix wins over the default, so `fetch(url){:js}` is still JavaScript. To keep one piece of inline code plain, such as a file name, add {:txt}: `pyproject.toml{:txt}`. The suffixes {:text}, {:plain} and {:plaintext} do the same.

If Expressive Code does not know the default language, inline code without a suffix stays plain, and the build logs one warning. On this site, the option adds about 900 highlighted pieces of inline code and no measurable build time.

Turn the feature off

Turn the feature off for the whole site with inlineHighlighting: false:

astro.config.mjs

codeblocks({
  inlineHighlighting: false,
});

With inlineHighlighting: false, the suffix stays in the prose as text.

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

Limitations

• Inline code cannot use the attributes or directives of code blocks, such as focus or line states.
• The plugin does not support the token form of rehype-pretty-code, such as {:.entity.name.function}.
• The code must be on one line. Expressive Code highlights it as a code block of one line. An unclosed string colours the rest of the code as a string.

Related

• Code links: make text inside a code block a link.
• Code mentions: link a phrase in the prose to lines of a code block.