MD040 - Fenced Code Blocks Should Have a Language Specified
Severity: Warning
Category: Code
Auto-fix: Not available
Rule Description
This rule ensures that fenced code blocks specify a language for syntax highlighting. Language tags improve readability and enable proper syntax highlighting in rendered output.
Why This Rule Exists
Language specifications are important because:
- Enables syntax highlighting in rendered markdown
- Improves code readability and comprehension
- Helps readers quickly identify the programming language
- Ensures consistent code block presentation
- Required by many documentation tools (including mdBook)
Examples
❌ Incorrect (violates rule)
```
function hello() {
console.log("Hello, world!");
}
```
```
SELECT * FROM users WHERE active = true;
```
✅ Correct
```javascript
function hello() {
console.log("Hello, world!");
}
```
```sql
SELECT * FROM users WHERE active = true;
```
```bash
echo "Shell commands also benefit from highlighting"
```
```text
Plain text can be explicitly marked
```
Configuration
[MD040]
allowed_languages = [] # List of allowed languages (empty = all allowed)
language_optional = false # Whether language tag is optional (default: false)
Common Language Tags
| Language | Tags |
|---|---|
| JavaScript | js, javascript |
| TypeScript | ts, typescript |
| Python | py, python |
| Rust | rs, rust |
| Shell | sh, bash, shell |
| JSON | json |
| YAML | yml, yaml |
| Markdown | md, markdown |
| Plain Text | text, txt |
| TOML | toml |
| HTML | html |
| CSS | css |
| SQL | sql |
When to Disable
Consider disabling this rule if:
- Your markdown renderer doesn't support syntax highlighting
- You have many code blocks where language is obvious from context
- You're using custom code block processors that don't require language tags
Disable in Config
# .mdbook-lint.toml
disabled_rules = ["MD040"]
Disable Inline
<!-- mdbook-lint-disable MD040 -->
```
Code block without language tag
```
<!-- mdbook-lint-enable MD040 -->
Related Rules
- MD046 - Code block style
- MD048 - Code fence style
- MDBOOK001 - Code blocks should have language tags (mdBook-specific)