Certain cli styles create clickable links, if your IDE or terminal supports them.
The details of the styles that create hyperlinks will prrobably change in the near future, based on user feedback.
The hyperlinks that are included in this manual are demonstrative
only, except for the https: links. They look like a hyperlink, and
you can click on them, but they do nothing. I.e. a .run link will
not run the linked expression if you click on it.
As of today, the latest release of RStudio (version v2022.07.0+548)
supports all hyperlink types discussed here. Certain terminals, e.g.
iTerm on macOS, Linux terminals based on VTE (GNOME terminal) support
.href, .email and .file links.
You can use ansi_has_hyperlink_support() to check if your terminal or
IDE has hyperlink support in general, and ansi_hyperlink_types() to
check if various types of hyperlinks are supported.
If your hyperlink support is not detected properly in your IDE or terminal, please open a cli issue at https://github.com/r-lib/cli/issues.
Before we delve into the various types of hyperlinks, a general comment about link texts. Some link styles support a custom link text:
.href
.help
.topic
.vignette
.run
Others, i.e. .email, .file, .fun and .url do not support custom
link text.
The generic syntax for link text is the same as for Markdown hyperlinks:
Note that it is not possible to add link text to a vector of URLs. E.g. this will create a list of three URLs, all clickable:
urls <- paste0("https://httpbin.org/status/", c(200, 403, 404))
cli::cli_text("Some httpbin URLs: {.url {urls}}.")#> Some httpbin URLs: <https://httpbin.org/status/200>, #> <https://httpbin.org/status/403>, and #> <https://httpbin.org/status/404>.
There are two cli styles to link to generic URLs. .url does not
allow custom link text, but \href does.
cli_text(
"See the cli homepage at {.url https://cli.r-lib.org} for details."
)#> See the cli homepage at <https://cli.r-lib.org> for details.
cli_text(
"See the {.href [cli homepage](https://cli.r-lib.org)} for details."
)#> See the cli homepage for details.
This is how these links look without hyperlink support:
local({
withr::local_options(cli.hyperlink = FALSE)
cli_text(
"See the cli homepage at {.url https://cli.r-lib.org} for details."
)
cli_text(
"See the {.href [cli homepage](https://cli.r-lib.org)} for details."
)
})#> See the cli homepage at <https://cli.r-lib.org> for details. #> See the cli homepage (<https://cli.r-lib.org>) for details.
Note that cli does not encode the url, so you might need to call
utils::URLencode() on it, especially, if it is substituted in
via {}.
weirdurl <- utils::URLencode("https://example.com/has some spaces")
cli_text("See more at {.url {weirdurl}}.")#> See more at <https://example.com/has%20some%20spaces>.
The .file style now automatically creates a file: hyperlink.
Because file: hyperlinks must contain an absolute path, cli tries to
convert relative paths, and paths starting with ~ to aboslute path.
cli_text("... edit your {.file ~/.Rprofile} file.}")
#> ... edit your ~/.Rprofile file.}
.file cannot use a custom link text. If you custom link text, then
you can use .href with a file: URL.
prof <- path.expand("~/.Rprofile")
cli_text("... edit your {.href [R profile](file://{prof})}.")#> ... edit your R profile.
You may add a line number to a file name, separated by :. Handlers
typically place the cursor at that line after opening the file.
You may also add a column number, after the line number, separated by
another :.
cli_text("... see line 5 in {.file ~/.Rprofile:5}.")
#> ... see line 5 in ~/.Rprofile:5.
In RStudio file: URLs open within RStudio. If you click on a file
link outside of RStudio, typically the operating system is consulted
for the application to open it.
One issue with using .href file files is that it does not look great
if hyperlinks are not available. This will be improved in the future:
local({
withr::local_options(cli.hyperlink = FALSE)
prof <- path.expand("~/.Rprofile")
cli_text("... edit your {.href [R profile](file://{prof})}.")
})
#> ... edit your R profile (<file:///Users/gaborcsardi/.Rprofile>).
.fun automatically creates links to the manual page of the function,
provided the function name is in the packagename::functionname form:
cli::cli_text("... see {.fun stats::lm} to learn more.")#> ... see `stats::lm()` to learn more.
For a custom link text, use .help instead of .fun.
cli::cli_text("... see {.help [{.fun lm}](stats::lm)} to learn more.")#> ... see `lm()` to learn more.
The same message without hyperlink support looks like this:
local({
withr::local_options(cli.hyperlink = FALSE)
cli::cli_text("... see {.help [{.fun lm}](stats::lm)} to learn more.")
})#> ... see `lm()` (`?stats::lm()`) to learn more.
To link to a help topic that is not a function, use .topic:
cli::cli_text("... the tibble options at {.topic tibble::tibble_options}.")#> ... the tibble options at tibble::tibble_options.
.topic support link text.
To link to a vignette, use .vignette:
cli::cli_text("... see the {.vignette tibble::types} vignette.")#> ... see the tibble::types vignette.
RStudio also supports a special link type that runs R code in the current R session upon clicking.
You can create these links with .run:
cli::cli_text("Run {.run testthat::snapshot_review()} to review")#> Run testthat::snapshot_review() to review
Sometimes you want to show a slightly different expression in the link,
than the one that is evaluated. E.g. the evaluated expression probably
needs to qualify packages with ::, but you might not want to show this:
cli::cli_text(
"Run {.run [snapshot_review()](testthat::snapshot_review())} to review"
)#> Run snapshot_review() to review
To make .run hyperlinks more secure, RStudio will not run code
that is not in the pkg::fun(args) form,
if args contains (, ) or ;,
if it calls a core package (base, stats, etc.),
if it calls a package that is not loaded, and it is not one of testthat, devtools, usethis, rlang, pkgload, or pkgdown which are explicitly allowed.
When RStudio does not run a .run hyperlink, then it shows the code
and the user can copy and paste it to the console, if they consider
it safe to run.
Note that depending on your version of RStudio, the behavior can change.