Setting Up Code Syntax Highlighting in Hugo

Introduction

Code syntax highlighting is essential for any development blog. It makes code more readable and helps readers understand the structure and logic of your code examples. Hugo provides built-in support for syntax highlighting, and in this post, we’ll explore how to set it up and customize it.

Built-in Syntax Highlighting

Hugo uses Chroma as its default syntax highlighter. It’s fast, supports many languages, and is easy to configure.

Basic Configuration

Add the following to your hugo.toml:

[markup]
  [markup.highlight]
    # Enable syntax highlighting
    codeFences = true
    # Guess the language if not specified
    guessSyntax = true
    # Show line numbers
    lineNos = true
    # Style for line numbers
    lineNumbersInTable = true
    # Use classes instead of inline styles
    noClasses = false
    # Default style
    style = "monokai"

Available Styles

Hugo comes with several built-in styles. Here are some popular ones:

• monokai
• dracula
• github
• solarized-dark
• solarized-light
• vs
• vs2015

Example with Different Styles

# Monokai style
def hello_world():
    print("Hello, World!")

# GitHub style
def hello_world():
    print("Hello, World!")

Customizing Highlighting

Custom CSS

You can override the default styles by adding custom CSS:

/* Custom syntax highlighting styles */
.highlight {
    background-color: #1a1a1a;
    border-radius: 4px;
    padding: 1em;
}

.highlight .line-numbers {
    color: #666;
    border-right: 1px solid #444;
    padding-right: 1em;
}

Language-Specific Styling

Target specific languages for custom styling:

/* Python-specific styles */
.highlight .language-python {
    font-family: 'Fira Code', monospace;
}

/* JavaScript-specific styles */
.highlight .language-javascript {
    font-family: 'JetBrains Mono', monospace;
}

Advanced Features

Line Highlighting

Highlight specific lines in your code:

    

        
        
        
    
def calculate_sum(numbers):
    total = 0
    for num in numbers:
        if num > 0:
            total += num
    return total

Inline Code

For inline code snippets, use backticks:

Use `print()` to output text to the console.

Performance Considerations

Lazy Loading

Enable lazy loading for code blocks:

[params.code]
  lazyLoading = true

Code Block Optimization

Optimize code block rendering:

[params.performance]
  minifyCode = true
  removeComments = true

Best Practices

1. Language Specification: Always specify the language for code blocks
2. Line Numbers: Use line numbers for longer code snippets
3. Copy Button: Enable copy functionality for code blocks
4. Consistent Style: Stick to one highlighting style throughout your blog
5. Mobile Optimization: Ensure code blocks are readable on mobile devices

Troubleshooting

Common Issues

1. Missing Language Support

   • Solution: Check if the language is supported by Chroma
   • Alternative: Use a generic language like text

2. Style Not Applying

   • Solution: Clear your browser cache
   • Check if custom CSS is properly loaded

3. Performance Issues

   • Solution: Enable lazy loading
   • Consider using code splitting

Conclusion

Proper code syntax highlighting is crucial for a development blog. It improves readability and makes your code examples more professional and accessible. By following the guidelines in this post, you can set up and customize syntax highlighting to match your blog’s style and requirements.

Next Steps

In the next post, we’ll explore deployment strategies for your Hugo blog, including various hosting options and CI/CD pipelines.

This post is part of a series on building a development blog with Hugo. Check out the previous posts for more information!