Skip to content
This repository has been archived by the owner on Jan 10, 2025. It is now read-only.

Commit

Permalink
Add support for inline images in VSCode terminal
Browse files Browse the repository at this point in the history
swsnr committed Oct 16, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent f58a5e7 commit a22e9af
Showing 4 changed files with 43 additions and 2 deletions.
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -8,6 +8,10 @@ Use `cargo release` to create a new release.

## [Unreleased]

### Added

- Support images in VSCode integrated terminal, 1.80 or newer (see [GH-266]).

### Changed
- When rendering iTerm2 images append `.png` to the file name reported to the terminal if mdcat rendered an SVG to PNG (see [GH-267]).
Previously, mdcat retained the original file extension, and would ask iTerm2 to download a PNG image to an `.svg` file.
@@ -16,6 +20,7 @@ Use `cargo release` to create a new release.
- Correct some iTerm2 inline image commands to better comply to the specification (see [GH-267]).
- Always terminate OSC commands with ST instead of BEL, as the latter is the legacy form (see [GH-267]).

[GH-266]: https://github.com/swsnr/mdcat/pull/266
[GH-267]: https://github.com/swsnr/mdcat/pull/267

## [2.0.4] – 2023-10-03
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -36,6 +36,7 @@ Then it
| [iTerm2] ||| ✓³ ||
| [kitty] ||| ✓³ | |
| [WezTerm] ||| ✓³ | |
| [VSCode] ||| ✓³ | |

1) mdcat requires that the terminal supports strikethrough formatting and [inline links][osc8].
It will not render strikethrough text and links correctly on terminals that don't support these (e.g. the Linux text console)
@@ -54,6 +55,7 @@ Not supported:
[kitty]: https://sw.kovidgoyal.net/kitty/
[resvg]: https://github.com/RazrFalcon/resvg
[SVG support]: https://github.com/RazrFalcon/resvg#svg-support
[VSCode]: https://code.visualstudio.com/

## Usage

12 changes: 10 additions & 2 deletions mdcat.1.adoc
Original file line number Diff line number Diff line change
@@ -38,6 +38,8 @@ To enable formatting extensions such as inline images, `mdcat` needs to detect t
2. `$TERM_PROGRAM`
3. `$TERMINOLOGY`

For some terminals `mdcat` also checks `$TERM_PROGRAM_VERSION` to determine whether the terminal supports the expected feature set.

See section <<Environment>> below for a detailed description of each environment variable.

=== Pagination
@@ -50,7 +52,7 @@ In particular this disables all image support which relies on proprietary escape

=== Image support

In iTerm2, kitty, Terminology and WezTerm mdcat prints inline images.
In iTerm2, kitty, Terminology, WezTerm, and VSCode (1.80 or newer) mdcat prints inline images.
mdcat supports most standard pixel formats by default.

mdcat silently ignores images larger than 100 MiB, under the assumption that images of that size cannot reasonably be rendered in a terminal.
@@ -59,7 +61,7 @@ mdcat silently ignores images larger than 100 MiB, under the assumption that ima

In Terminology mdcat also renders SVG images, using the built-in support of Terminology.

In iTerm2, kitty and WezTerm mdcat renders SVG images into pixel graphics using the https://github.com/RazrFalcon/resvg[resvg] library.
In iTerm2, kitty, VSCode, and WezTerm mdcat renders SVG images into pixel graphics using the https://github.com/RazrFalcon/resvg[resvg] library.
Currently this library only supports SVG 1, and only the static subset thereof; see https://github.com/RazrFalcon/resvg#svg-support[SVG support] for details.
While this is sufficient for most simple SVG images, complex SVG images may fail to render or render incompletely.

@@ -147,9 +149,14 @@ TERM_PROGRAM::
+
* `iTerm.app`: iTerm2
* `WezTerm`: WezTerm
* `vscode`: VSCode integrated terminal, but only if `$TERM_PROGRAM_VERSION` indicates a sufficient version to support all required features..
+
For all other values `mdcat` proceeds to check `$TERMINOLOGY`.

TERM_PROGRAM_VERSION::

If `$TERM_PROGRAM` is `vscode`, `mdcat` checks this variable to determine whether VSCode has a sufficient version to support all required features.

TERMINOLOGY::

If this variable is `1`, mdcat assumes that the terminal is Terminology.
@@ -227,6 +234,7 @@ https://iterm2.com/documentation-escape-codes.html[Marks].
* https://github.com/kovidgoyal/kitty[kitty]: Inline images (https://sw.kovidgoyal.net/kitty/graphics-protocol.html[kitty Graphics protocol]).
* http://terminolo.gy[Terminology]: Inline images (terminology protocol).
* https://wezfurlong.org/wezterm/[WezTerm]: Inline images (kitty graphics protocol, see above).
* https://code.visualstudio.com/[VSCode] 1.80 or newer, integrated terminal: Inline images (iTerm2 protocol, see above)

== Bugs

26 changes: 26 additions & 0 deletions pulldown-cmark-mdcat/src/terminal/detect.rs
Original file line number Diff line number Diff line change
@@ -42,6 +42,10 @@ pub enum TerminalProgram {
///
/// See <https://wezfurlong.org/wezterm/> for more information.
WezTerm,
/// The built-in terminal in VSCode.
///
/// Since version 1.80 it supports images with the iTerm2 protocol.
VSCode,
}

impl Display for TerminalProgram {
@@ -53,11 +57,24 @@ impl Display for TerminalProgram {
TerminalProgram::Terminology => "Terminology",
TerminalProgram::Kitty => "kitty",
TerminalProgram::WezTerm => "WezTerm",
TerminalProgram::VSCode => "vscode",
};
write!(f, "{name}")
}
}

/// Extract major and minor version from `$TERM_PROGRAM_VERSION`.
///
/// Return `None` if the variable doesn't exist, or has invalid contents, such as
/// non-numeric parts, insufficient parts for a major.minor version, etc.
fn get_term_program_major_minor_version() -> Option<(u16, u16)> {
let value = std::env::var("TERM_PROGRAM_VERSION").ok()?;
let mut parts = value.split('.').take(2);
let major = parts.next()?.parse().ok()?;
let minor = parts.next()?.parse().ok()?;
Some((major, minor))
}

impl TerminalProgram {
fn detect_term() -> Option<Self> {
match std::env::var("TERM").ok().as_deref() {
@@ -71,6 +88,12 @@ impl TerminalProgram {
match std::env::var("TERM_PROGRAM").ok().as_deref() {
Some("WezTerm") => Some(Self::WezTerm),
Some("iTerm.app") => Some(Self::ITerm2),
Some("vscode")
if get_term_program_major_minor_version()
.map_or(false, |version| (1, 80) <= version) =>
{
Some(Self::VSCode)
}
_ => None,
}
}
@@ -130,6 +153,9 @@ impl TerminalProgram {
.with_image_capability(ImageCapability::Kitty(self::kitty::KittyGraphicsProtocol)),
TerminalProgram::WezTerm => ansi
.with_image_capability(ImageCapability::Kitty(self::kitty::KittyGraphicsProtocol)),
TerminalProgram::VSCode => {
ansi.with_image_capability(ImageCapability::ITerm2(ITerm2Protocol))
}
}
}
}

0 comments on commit a22e9af

Please sign in to comment.