d2.txt

*d2.txt*                                         suppport for d2 diagram files

                                  *d2-vim*

==============================================================================
CONTENTS                                                          *d2-contents*

1. Introduction               (|d2-intro|)
2. Commands                   (|d2-commands|)
3. ASCII Preview              (|d2-ascii-preview|)
4. Settings                   (|d2-settings|)

==============================================================================
INTRO                                                                *d2-intro*

The Vim plugin for .d2 files.

See https://d2lang.com

==============================================================================
COMMANDS                                                          *d2-commands*

:D2Fmt                                                                  *:D2Fmt*
  Format the current buffer using `d2 fmt`. This modifies the buffer content
  to follow D2's standard formatting conventions.

:D2FmtToggle                                                      *:D2FmtToggle*
  Toggle automatic formatting on save. When enabled, |:D2Fmt| is called
  automatically before each save operation.

:D2Validate                                                          *:D2Validate*
  Validate the current buffer using `d2 validate`. This checks for syntax
  errors and populates the quickfix or location list with any issues found.
  Does not modify the buffer.

:D2ValidateToggle                                              *:D2ValidateToggle*
  Toggle automatic validation on save. When enabled, |:D2Validate| is called
  automatically after each save operation.

:D2Play                                                              *:D2Play*
  Open the current buffer in the D2 online playground at play.d2lang.com.
  This creates a shareable link for your diagram.

:D2Preview                                                        *:D2Preview*
  Render the current buffer as ASCII text and display it in a preview window.
  Uses `d2 input.d2 output.txt` to generate the ASCII representation.

:D2PreviewToggle                                              *:D2PreviewToggle*
  Toggle the ASCII preview window. If the preview is currently open, close it.
  If closed, open a new preview with the current buffer's ASCII render.

:D2PreviewUpdate                                              *:D2PreviewUpdate*
  Update the existing ASCII preview window with the current buffer content.
  Only works if a preview window is already open.

:D2AsciiToggle                                                *:D2AsciiToggle*
  Toggle automatic ASCII rendering on save. When enabled, the ASCII preview
  window is automatically updated after each save operation.

:D2PreviewSelection                                          *:D2PreviewSelection*
  Render the currently selected text as ASCII. This is a global command that
  works in any file. Use in visual mode to preview D2 code snippets from
  anywhere - markdown files, documentation, code comments, etc.

:D2ReplaceSelection                                          *:D2ReplaceSelection*
  Replace the currently selected D2 code with its ASCII render. This is a 
  global command that works in any file. Use in visual mode to convert D2 
  code directly to ASCII text in place.

:D2PreviewCopy                                                    *:D2PreviewCopy*
  Copy the content of the ASCII preview window to both the system clipboard
  and Vim's yank register. This allows pasting with both 'p' (yank register)
  and Ctrl+V (system clipboard). Only works when a preview window is open.

<Leader>d2                                                            *<Leader>d2*
  Context-sensitive mapping:
  - Visual mode (any file): Render selected text as ASCII (|:D2PreviewSelection|)
  - Normal mode (D2 files): Render entire buffer as ASCII (|:D2Preview|)

<Leader>rd2                                                          *<Leader>rd2*
  Replace selected D2 code with ASCII render (|:D2ReplaceSelection|).
  Available in visual mode for any file. Permanently replaces the selected
  text with the ASCII diagram output.

<Leader>yd2                                                          *<Leader>yd2*
  Copy ASCII preview content to clipboard and yank register (|:D2PreviewCopy|).
  Available in normal mode for any file. Requires an open preview window.

==============================================================================
ASCII PREVIEW                                                *d2-ascii-preview*

The ASCII preview feature renders D2 diagrams as text in a vertical split pane
within Vim. This provides a live preview of your diagrams without requiring
external tools or graphics support.

Requirements: D2 version 0.7.1 or higher is required for ASCII output.

Use cases:
- Quick previews during development
- Working in terminal-only environments  
- Sharing diagrams in text-only contexts
- Understanding diagram structure while editing

The preview window automatically updates when you save your D2 file (if
|g:d2_ascii_autorender| is enabled, which is the default).

ASCII MODES                                                   *d2-ascii-modes*

D2 supports two ASCII rendering modes:

Extended Mode (default):
  Uses Unicode box-drawing characters for cleaner output. Produces diagrams
  with smooth lines and proper corners using characters like ┌─┐│└┘.

Standard Mode:
  Uses basic ASCII characters for maximum compatibility. Produces diagrams
  using only standard ASCII characters like +---|.

The mode is controlled by |g:d2_ascii_mode|. When set to "standard", the
--ascii-mode=standard flag is passed to the d2 command.

==============================================================================
SETTINGS                                                          *d2-settings*

                                                           *g:d2_fmt_autosave*
Enable or disable automatic formatting on save.
Default: 1 (enabled)

                                                             *g:d2_fmt_command*
Customize the command used for formatting.
Default: "d2 fmt"

                                                       *g:d2_fmt_fail_silently*
Control whether formatting errors are displayed.
Default: 0 (show errors)

                                                      *g:d2_validate_autosave*
Enable or disable automatic validation on save.
Default: 0 (disabled)

                                                        *g:d2_validate_command*
Customize the command used for validation.
Default: "d2 validate"

                                                  *g:d2_validate_fail_silently*
Control whether validation errors are displayed.
Default: 0 (show errors)

                                                             *g:d2_list_type*
Choose between quickfix and location list for displaying validation errors.
Options: "quickfix" or "locationlist"
Default: "quickfix"

                                                           *g:d2_play_command*
Customize the command used for playground.
Default: "d2 play"

                                                              *g:d2_play_theme*
Set the theme ID for the playground.
Default: 0

                                                             *g:d2_play_sketch*
Enable sketch mode for the playground (hand-drawn appearance).
Default: 0 (disabled)

                                                          *g:d2_ascii_command*
Customize the command used for ASCII rendering.
Default: "d2"

                                                     *g:d2_ascii_preview_width*
Set the width of the ASCII preview window in columns (vertical split).
Default: half the screen width (&columns / 2)

                                                        *g:d2_ascii_autorender*
Enable or disable automatic ASCII rendering on save.
Default: 1 (enabled)

                                                             *g:d2_ascii_mode*
Set the ASCII rendering mode. Options: "extended" or "standard".
Extended uses Unicode box-drawing characters, standard uses basic ASCII.
Default: "extended"

                                                   *g:d2_block_string_syntaxes*

This option declares a map from vim syntax names to the tags that |d2-vim|
should enable each within block strings.

Default: >
  let g:d2_block_string_syntaxes = {
        \ 'd2': ['d2'],
        \ 'markdown': ['md', 'markdown'],
        \ 'javascript': ['javascript', 'js'],
        \ 'html': ['html'],
        \ 'json': ['json'],
        \ 'c': ['c'],
        \ 'go': ['go'],
        \ 'sh': ['sh', 'ksh', 'bash'],
        \ 'css': ['css'],
        \ 'vim': ['vim'],
        \ }
<
Example: >
  x: |`js let x = 3 `|
<
To extend the default with another syntax, say TypeScript: >
  let g:d2_block_string_syntaxes = {'typescript': ['typescript', 'ts']}
<
Now the following block strings will have syntax highlighting: >
  x: |`typescript let x = 3 `|
  x: |`ts let x = 3 `|

To extend the default with another tag on a syntax, say html: >
  let g:d2_block_string_syntaxes = {'html': ['htm']}
<
Now the following block string will have HTML syntax highlighting: >
  x: |`htm <html> hello world </html> `|

The user value of |g:d2_block_string_syntaxes| is merged with the default so
the following block strings continue to have syntax highlighting: >
  x: |`js let x = 3 `|
  x: |`html <html> hello world </html> `|
<
To disable block string syntaxes: >
  let g:d2_block_string_syntaxes = v:false
<
The value of |g:markdown_fenced_languages| is automatically synced with
|g:d2_block_string_syntaxes|. See https://github.com/tpope/vim-markdown for
documentation on |g:markdown_fenced_languages|.

note: In markdown block strings, |d2-vim| disables indented code blocks
  highlighting as there's no way to make markdown.vim aware of the indent of
  the block string and so it ends up wrongly highlighting 4 space indent block
  strings as indented code blocks.

  Indented code blocks are rarely used anyway.
  You almost always want to use a fenced code block instead.
  See https://spec.commonmark.org/0.30/#indented-code-blocks
  See https://spec.commonmark.org/0.30/#fenced-code-blocks

note: Line continuations are known to be buggy within fenced d2 code blocks
  of top level markdown files.

==============================================================================
 vim: ft=help tw=78 et ts=2 sw=0 sts=0 fo-=t norl