How to use the command 'highlight' (with examples)
The ‘highlight’ command is a versatile tool that outputs syntax-highlighted source code to a variety of formats. It provides a convenient way to format and display source code files with customizable themes and styles. Whether it’s generating complete HTML documents, listing supported languages and themes, or printing CSS stylesheets, the ‘highlight’ command offers a range of use cases to suit your needs.
Use case 1: Produce a complete HTML document from a source code file
Code:
highlight --out-format=html --style theme_name --syntax language path/to/source_code
Motivation: When you want to showcase your source code in an HTML document with a specific theme and syntax highlighting, this use case is perfect. It allows you to generate a complete HTML document ready for embedding or publishing.
Explanation:
--out-format=html: Specifies the output format as HTML.--style theme_name: Specifies the theme for the source code highlighting.--syntax language: Specifies the language syntax of the source code.path/to/source_code: The path to the source code file you want to highlight.
Example output:
<!DOCTYPE html>
<html>
<head>
<title>Highlighted Source Code</title>
<link rel="stylesheet" type="text/css" href="theme_name.css">
</head>
<body>
<pre><code class="language">...</code></pre>
...
</body>
</html>
Use case 2: Produce an HTML fragment, suitable for inclusion in a larger document
Code:
highlight --out-format=html --fragment --syntax language source_file
Motivation: This use case is useful when you only need to highlight a specific code snippet and want to include it within a larger HTML document. It generates an HTML fragment that can be easily embedded without the need for a complete HTML structure.
Explanation:
--fragment: Generates an HTML fragment instead of a complete document.source_file: The source code file you want to highlight.
Example output:
<pre><code class="language">...</code></pre>
Use case 3: Inline the CSS styling in every tag
Code:
highlight --out-format=html --inline-css --syntax language source_file
Motivation: When you want to simplify the distribution and deployment of your source code highlighting, inlining the CSS styling in every HTML tag eliminates the need for separate stylesheet files.
Explanation:
--inline-css: Applies the CSS styling directly in each HTML tag.source_file: The source code file you want to highlight.
Example output:
<pre><code class="language" style="color:#FF0000;">...</code></pre>
Use case 4: List all supported languages, themes, or plugins
Code:
highlight --list-scripts langs|themes|plugins
Motivation: When you want to check the available languages, themes, or plugins supported by ‘highlight’ to select the most appropriate ones for your source code highlighting.
Explanation:
--list-scripts: Lists the available scripts, which can be ’langs’, ’themes’, or ‘plugins’.
Example output:
Available languages:
- HTML
- JavaScript
- Python
Available themes:
- Default
- Monokai
- Solarized Dark
Available plugins:
- LineNumbers
Use case 5: Print a CSS stylesheet for a theme
Code:
highlight --out-format=html --print-style --style theme_name --syntax language --stdout
Motivation: Printing a CSS stylesheet for a specific theme allows you to customize the styling further or include it directly in your HTML document.
Explanation:
--print-style: Prints the CSS stylesheet for the specified theme and syntax.--style theme_name: Specifies the theme for which the CSS stylesheet is generated.--syntax language: Specifies the language syntax for the CSS stylesheet.--stdout: Outputs the CSS stylesheet to the standard output.
Example output:
.language {
color: #FF0000;
font-family: 'Courier New', monospace;
...
}
Conclusion:
The ‘highlight’ command provides a versatile set of tools for generating syntax-highlighted source code in various formats. Whether you need to create complete HTML documents, HTML fragments, or list supported languages and themes, this command has you covered. With customizable styles and themes, it’s easy to showcase your source code in a visually appealing way. Start using the ‘highlight’ command today to enhance your code documentation and presentation.
