Code Block Language Reference

Code Block Language Reference

When writing documentation in Markdown or MDX, specifying the correct language identifier for code blocks ensures proper syntax highlighting and improves readability. This reference guide covers common language identifiers and provides examples of how to use them.

Basic Syntax

In Markdown, you can create a code block by wrapping your code with three backticks (```) at the beginning and end. To specify a language, add its identifier right after the opening backticks:

```javascript
const greeting = 'Hello, world!';
console.log(greeting);
```

The rendered output will have syntax highlighting appropriate for the specified language:

const greeting = 'Hello, world!';
console.log(greeting);

Common Language Identifiers

Here’s a comprehensive list of language identifiers you can use in your documentation:

Web Development

Identifier	Language/Format	Use Case
html	HTML	Markup for web pages
xml	XML	Extensible Markup Language
svg	SVG	Scalable Vector Graphics
css	CSS	Stylesheets
scss	SCSS	Sass CSS pre-processor
less	LESS	LESS CSS pre-processor
javascript or js	JavaScript	Client-side scripting
jsx	JSX	React component syntax
typescript or ts	TypeScript	Typed JavaScript
tsx	TSX	TypeScript with JSX
json	JSON	Data interchange format
jsonc	JSON with comments	Configuration files

Backend Development

Identifier	Language/Format	Use Case
python or py	Python	General-purpose programming
ruby or rb	Ruby	General-purpose programming
php	PHP	Server-side scripting
java	Java	General-purpose programming
csharp or cs	C#	.NET development
go or golang	Go	Systems programming
rust	Rust	Systems programming
kotlin	Kotlin	Android development
swift	Swift	iOS/macOS development
sql	SQL	Database queries

Command Line & Configuration

Identifier	Language/Format	Use Case
bash or shell	Bash/Shell	Command line scripts
powershell or ps	PowerShell	Windows scripting
yaml or yml	YAML	Configuration files
toml	TOML	Configuration files
ini	INI	Configuration files
dockerfile	Dockerfile	Container configurations
diff	Diff	Code changes/patches
ignore	Gitignore	Git ignore patterns

Markup & Documentation

Identifier	Language/Format	Use Case
markdown or md	Markdown	Documentation
mdx	MDX	Markdown with JSX
tex or latex	LaTeX	Scientific documents
asciidoc or adoc	AsciiDoc	Documentation

Special Cases & Examples

Shell/Terminal Commands (bash, shell, sh)

Use these identifiers for command-line instructions:

```sh
# Install dependencies
npm install

# Start development server
npm run dev
```

Result:

# Install dependencies
npm install

# Start development server
npm run dev

Highlighting Differences (diff)

Perfect for showing changes between code versions:

```diff
- const oldFunction = () => {
-   return "old implementation";
- }
+ const newFunction = () => {
+   return "new and improved implementation";
+ }
```

Result:

const oldFunction = () => {
  return "old implementation";
}
const newFunction = () => {
  return "new and improved implementation";
}

Configuration Files

For .gitignore, .dockerignore, etc.:

# Dependencies

node_modules/
.pnp
.pnp.js

# Testing

coverage/

# Production

build/
dist/

Result:

# Dependencies
node_modules/
.pnp
.pnp.js

# Testing
coverage/

# Production
build/
dist/

GitHub Flavored Markdown

GitHub and some other platforms support additional languages:

• mermaid - For diagrams
• graphql - For GraphQL queries
• plantuml - For UML diagrams

Example of Mermaid diagram:

```mermaid
graph TD;
 A-->B;
 A-->C;
 B-->D;
 C-->D;
```

No Language Specified

If you don’t specify a language, the code block will be displayed without syntax highlighting:

```text
This is a plain text code block with no language specified.
It will not have any specific syntax highlighting.
```

Result:

This is a plain text code block with no language specified.
It will not have any specific syntax highlighting.

Language Aliases

Many languages have multiple identifiers that can be used:

• JavaScript: javascript, js
• TypeScript: typescript, ts
• Python: python, py
• Ruby: ruby, rb
• Shell: bash, shell, sh

Use whichever feels most natural for your documentation style.

Best Practices

1. Be consistent - Choose one identifier per language and use it consistently throughout your documentation.

2. Use appropriate identifiers - Match the identifier to the actual language for accurate syntax highlighting.

3. For mixed content - When a code block contains mixed languages (like HTML with embedded JavaScript), choose the predominant language.

4. For configuration files - Use the exact format identifier when possible (dockerfile, nginx, yaml).

5. For command output - If showing terminal output that isn’t meant to be executed, you can use text or omit the language identifier.

Starlight-Specific Features

In the Starlight documentation framework, you can enhance code blocks with additional features:

Line Highlighting

You can highlight specific lines using curly braces:

```js {3-4}
function example() {
    const a = 1;
    // These lines will be highlighted
    const highlightedLine = true;
    return a;
}
```

Title for Code Blocks

```js title="example.js"
function greet() {
    return 'Hello world!';
}
```

Supported Languages in Your Project

The exact list of supported languages for syntax highlighting depends on the syntax highlighter used in your project. Most documentation sites use either:

• Prism.js
• Shiki
• Highlight.js

Check your project’s configuration to see which highlighter is in use and what languages are supported.