Exploring the D2 Command for Diagram Scripting (with examples)

D2 is a modern diagram scripting language designed to turn text into diagrams efficiently. It offers a variety of user-friendly features, making it highly accessible for creating visually appealing diagrams in both SVG and PNG formats. Whether you are a developer, designer, or educator, D2 assists in transforming complex ideas into easy-to-understand visual structures. This article will explore several use cases of the D2 command, providing practical examples and explanations for each.

Use case 1: Compile and render a D2 source file into an output file

Code:

d2 path/to/input_file.d2 path/to/output_file.ext

Motivation:

Consider you have created a detailed architecture of a microservices system in D2 script and now wish to share it with your team in a presentable format. By compiling and rendering the D2 file into an SVG or PNG, you can provide high-quality visuals for presentations, reports, or documentation, ensuring that everyone involved has a clear view of the system’s design.

Explanation:

• d2: The command used to invoke the D2 diagram scripting tool.
• path/to/input_file.d2: This is the source file that contains the text-based representation of your diagram.
• path/to/output_file.ext: This is the target file for your rendered diagram, where .ext is typically SVG or PNG based on your project requirements.

Example output:

Upon execution, the command reads your input D2 file, processes the contained script, and generates a visual diagram saved at the specified output path. The result may look like a neatly organized diagram illustrating microservices interconnections.

Use case 2: Watch live changes made to a D2 source file in the default web browser

Code:

d2 --watch path/to/input_file.d2 path/to/output_file.ext

Motivation:

Imagine you are iterating rapidly over the design of a complex data flow diagram in collaboration with a team. Immediate feedback from your peers is crucial for refining this design. Watching live changes in your default web browser allows you to visualize updates instantly, facilitating a dynamic workflow and improving team collaboration.

Explanation:

• --watch: This flag tells D2 to monitor the source file for live changes.
• path/to/input_file.d2: Specifies the input file to be watched and rendered.
• path/to/output_file.ext: Indicates the output file where rendered changes are visualized.

Example output:

With this command, each update to the source file is visually reflected in the default browser almost instantly. Stakeholders can continuously monitor modifications as they occur in real-time.

Use case 3: Format a D2 source file

Code:

d2 fmt path/to/input_file.d2

Motivation:

When working on large diagrams, your D2 scripts can easily become cluttered, making them hard to read or maintain. Using the format functionality cleans up your code, enforces consistency, and ensures that your script remains organized and developer-friendly, thus facilitating easier collaboration and understanding.

Explanation:

• fmt: This subcommand is used to format the given D2 source file.
• path/to/input_file.d2: This specifies the path to the D2 source file that you want to format.

Example output:

The command parses your D2 source file, formats it, and reorganizes it for optimal clarity. The newly formatted file keeps the same functional integrity but is now more readable.

Use case 4: List available themes

Code:

d2 themes

Motivation:

To enhance the aesthetics of your diagram, D2 offers multiple themes that can change the colors, backgrounds, and overall appearance of your diagram. Listing available themes helps you choose a style that fits your branding or presentation needs, thus improving the visual impression of the final output.

Explanation:

• themes: This command is used to print a list of all available themes in the D2 toolset.

Example output:

Executing this command provides a comprehensive list of themes with their respective IDs, descriptions, and stylistic details. This output enables informed decisions when customizing your diagram’s appearance.

Use case 5: Use a different theme for the output file

Code:

d2 --theme theme_id path/to/input_file.d2 path/to/output_file.ext

Motivation:

In some cases, the default appearance of your diagram may not align with your project’s visual requirements. By selecting a different theme, you can tailor the appearance to suit a particular aesthetic, ensuring it aligns with corporate branding or specific design criteria, thus achieving a polished look for presentations or publications.

Explanation:

• --theme theme_id: This option specifies the theme you want to apply. The theme_id should correspond to one of the IDs from the themes command output.
• path/to/input_file.d2: The path to the source D2 file with your script.
• path/to/output_file.ext: The path where the rendered file will be stored, supporting either SVG or PNG formats.

Example output:

After running the command with the desired theme, your output file possesses a visually distinct style, potentially incorporating new color schemes, fonts, or layout adjustments that enhance the overall aesthetic.

Use case 6: Make rendered diagrams look like hand sketches

Code:

d2 --sketch true path/to/input_file.d2 path/to/output_file.ext

Motivation:

In scenarios where a formal diagram feels too rigid or impersonal, such as in creative presentations or informal brainstorming sessions, turning your diagrams into hand-drawn sketches can provide a human touch. This feature enhances the relatability of the diagrams, sparking creativity and engagement from audiences.

Explanation:

• --sketch true: This option applies a sketch-like effect to the rendered diagrams, mimicking the appearance of hand-drawn sketches.
• path/to/input_file.d2: The source D2 script file.
• path/to/output_file.ext: The output file where the sketched diagram will be stored.

Example output:

By setting the sketch mode, the output diagram adopts a more informal, hand-crafted aesthetic. Lines may appear slightly uneven, and text might resemble handwriting, offering a unique, creative charm.

Conclusion:

The D2 command offers a robust set of features for developing and refining visual diagrams from textual content. Through practical examples and detailed explanations, we explored how to compile and render diagrams, watch live changes, format scripts, apply themes, and create sketches. Mastering these use cases empowers you to convey complex ideas effectively, enhancing both individual projects and collaborative ventures.