How to Use the Command 'highlight' (with Examples)

The highlight command is a versatile tool designed for developers and tech enthusiasts who frequently work with source code files. It provides the ability to output syntax-highlighted source code in a variety of formats, including HTML, LaTeX, RTF, and more. This makes it an essential tool for creating readable and aesthetically pleasing presentations of code. Whether you’re preparing documentation, a blog post, or a presentation, the highlight command ensures your code is not only functional but also visually appealing.

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 working on projects, there often arises a need to share source code files in a manner that is both accessible and readable. Converting a piece of code into a fully formatted HTML document means the code can be easily shared via web resources and viewed in any browser. This eliminates compatibility issues and ensures that the code’s syntax is highlighted according to a chosen theme, enhancing readability and comprehension.

Explanation:

• --out-format=html: Specifies that the output should be in HTML format, transforming the raw source code into a web-ready document.
• --style theme_name: Defines the style or theme for syntax highlighting. Themes apply a set of predefined colors to the syntax elements, allowing you to customize the appearance of your code.
• --syntax language: Indicates the programming language of the source code, ensuring that the syntax highlighting is appropriate for that language.
• path/to/source_code: This is the path to the source code file you want to convert. Replace it with the actual path to your file.

Example Output:

An HTML file displaying the source code, where keywords, strings, comments, etc., are displayed in colors as specified by the chosen theme.

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:

There are instances when you need to embed code snippets in a larger HTML document, like a blog post or an article. In such cases, generating a complete HTML document for a small code snippet is overkill. Instead, creating an HTML fragment makes it much easier to integrate the highlighted code into existing web content without redundant wrappers.

Explanation:

• --out-format=html: Again specifies HTML for output to ensure compatibility with web pages.
• --fragment: Outputs only an HTML fragment of the code so it can be easily embedded within other HTML content without the full HTML document overhead.
• --syntax language: Specifies the language used in the code snippet to ensure accurate syntax highlighting.
• source_file: Refers to the file containing the source code snippet you wish to convert.

Example Output:

A snippet of HTML code representing the source code, formatted in highlighted syntax with minimal extraneous HTML code, ready for insertion into a larger HTML document.

Use Case 3: Inline the CSS Styling in Every Tag

Code:

highlight --out-format=html --inline-css --syntax language source_file

Motivation:

When embedding code into HTML, relying on external CSS files can complicate deployment, particularly if the environment has restrictions on linking external files. Inlining CSS styling ensures that all style rules are embedded directly within the HTML tags of the code fragment. This simplifies deployment and maintains consistency in styling on pages where external stylesheets cannot be guaranteed.

Explanation:

• --out-format=html: Selects HTML output, as before.
• --inline-css: Inlines CSS styles within each HTML tag, which means the style details travel with the document, leading to easier self-contained file sharing.
• --syntax language: Ensures the style rules applied are correct for the syntax of the specified language.
• source_file: The file containing the code to be formatted.

Example Output:

HTML code with inline CSS styles applied to each HTML element, removing the need for external stylesheets and ensuring consistent styling across different environments.

Use Case 4: List All Supported Languages, Themes, or Plugins

Code:

highlight --list-scripts langs|themes|plugins

Motivation:

Knowing which languages and themes the highlight command supports can help you make informed decisions about how to prepare your files for output. Listing supported items ensures you know the scope of compatibility and flexibility you have with your documents before starting the syntax highlight process.

Explanation:

• --list-scripts: Invokes a command to list items supported by the highlight tool.
• langs|themes|plugins: Specifies what to list. Replace with langs to list supported programming languages, themes to list available themes, or plugins for available plugins.

Example Output:

A list in the terminal showing supported languages, themes, or plugins as specified in the command. This list informs you about the capabilities of the highlight command.

Use Case 5: Print a CSS Stylesheet for a Theme

Code:

highlight --out-format=html --print-style --style theme_name --syntax language --stdout

Motivation:

When you want consistent styling in separate HTML documents, a CSS stylesheet is essential. By printing a CSS file, you can maintain the same syntax highlighting style across different code files, enhancing visual coherence in presentations or multiple web pages.

Explanation:

• --out-format=html: Ensures that the CSS style is formatted suitably for HTML usage.
• --print-style: Specifically generates a CSS style sheet for the specified theme.
• --style theme_name: Specifies which theme’s CSS rules should be extracted.
• --syntax language: Alignment with a specific programming language, aiding in accuracy.
• --stdout: Outputs the CSS stylesheet directly to standard output, making it accessible for manual capture or redirected storage.

Example Output:

A CSS stylesheet printed in the terminal, containing all relevant style rules for a specified theme. You can copy this directly for use in your web projects or save it as a separate stylesheet file for future use.

Conclusion:

The highlight command is an incredibly versatile tool that enhances the presentation of source code across documents, websites, and more. Whether you are creating an HTML document, embedding a code snippet, using inline styles, or managing supported resources, the command accommodates diverse requirements, ensuring your code looks great and is easy to read. The provided examples and explanations aim to simplify your journey in transforming plain code into visually appealing, syntax-highlighted documents.