savioxavier/termlink

Clickable links in the terminal for Go

termlink

Clickable links in the terminal for Go

^*

Termlink is a Go package that allows you to create fully customizable clickable links in the terminal. It is the Go version of Sindre Sorhus' popular terminal-link library.

It includes multiple features including dynamic and fully customizable colored links in terminal, along with smart hyperlink support detection.

🛠️ Install

Using go get:

go get github.com/savioxavier/termlink

---

🔗 Usage

• Basic regular link:

import (
	"fmt"

	"github.com/savioxavier/termlink"
)

func main() {
	fmt.Println(termlink.Link("Example", "https://example.com"))
}

• Customizable colored link:

import (
	"fmt"

	"github.com/savioxavier/termlink"
)

func main() {
	fmt.Println(termlink.ColorLink("Example", "https://example.com", "italic green"))
}

• Check if your current terminal supports hyperlinks:

import (
	"fmt"

	"github.com/savioxavier/termlink"
)

func main() {
	fmt.Println(termlink.SupportsHyperlinks())
	// prints either true or false, depending on your terminal
}

• Since termlink.Link returns a string, you can use it with your favorite text color formatting libraries such as fatih/color, mgutz/ansi, etc. Alternatively, you can use termlink.ColorLink as well.

import (
	"fmt"

	"github.com/fatih/color"
	"github.com/savioxavier/termlink"
)

func main() {
	// With fatih/color package
	color.Cyan(termlink.Link("Example link using the fatih/color package", "https://example.com"))
}

Note For unsupported terminals, the link will be printed in parentheses after the text (see below image)

---

🍵 Examples

More examples can be found in the examples/ directory.

For a quick demo, execute the following commands in your terminal:

git clone https://github.com/savioxavier/termlink.git
cd termlink/
go get github.com/savioxavier/termlink
go run examples/start.go

---

🔮 Features

• termlink.Link(text, url, [shouldForce])

  • Creates a regular, clickable link in the terminal
  • For unsupported terminals, the link will be printed in parentheses after the text: Example Link (https://example.com).
  • The shouldForce is an optional boolean parameter which allows you to force the above unsupported terminal hyperlinks format text (url) to be printed, even in supported terminals

• termlink.ColorLink(text, url, color, [shouldForce])

  • Creates a clickable link in the terminal with custom color formatting
  • Examples of color options include:
    • Foreground only: green, red, blue, etc.
    • Background only: bgGreen, bgRed, bgBlue, etc.
    • Foreground and background: green bgRed, bgBlue red, etc.
    • With formatting: green bold, red bgGreen italic, italic blue bgGreen, etc.
  • The shouldForce is an optional boolean parameter which allows you to force the above unsupported terminal hyperlinks format text (url) to be printed, even in supported terminals

shouldForce can be used in the following manner:

termlink.Link(text, url, true)
termlink.ColorLink(text, url, color, true)

You don't always need to specify this argument. By default, this parameter is false

• termlink.SupportsHyperlinks():

  • Returns true if the terminal supports hyperlinks, false otherwise.

---

🧪 Tests

You can run unit tests locally by running the following command:

go test -v

Tests can be found in termlink_test.go

---

❤️ Support

You can support further development of this project by giving it a 🌟 and help me make even better stuff in the future by buying me a ☕

Also, if you liked this repo, consider checking out my other projects, that would be real cool!

---

💫 Attributions and special thanks

• terminal-link - Sindre Sorhus' original package for providing inspiration for this package.
• supports-hyperlinks - Zkat's package for additional hyperlink handling support.

_{^{* The paperclip icon shown in the demo at the top of this README isn't included when you create the link, it's purely for decorative purposes only.}}

termlink's Issues

Write unit tests

Description

Unit tests need to be written for this package - using a mixture of the assert package from stretchr/testify and Go's native testing library.

The tests need to support both hyperlink supporting and non-hyperlink supporting terminals, by using this package's SupportsHyperlinks() method. A basic test would look something like this:

func TestBasicLink(t *testing.T) {
	if termlink.SupportsHyperlinks() {
		assert.Equal(t, termlink.Link("Hello", "https://google.com"), "\x1b]8;;https://google.com\aHello\x1b]8;;\a\x1b[m")
	} else {
		assert.Equal(t, termlink.Link("Hello", "https://google.com"), "Hello (\u200Bhttps://google.com)\u001b[m")
	}
}

go test -v

The tests would need to be run in both terminals - one that supports hyperlinks, and one that doesn't. I'll be using a few AI assisted tools to speed up testing. A few basic tests would do fine as of now, more tests can be added later.

If all the tests work as expected, then it's all good to go!

Assigning this issue to myself. Should be an easy enough job.

Support alacritty

Hi Im about to use this library for a project of mine. I have tested in and discovered that alacritty is currently not supported. Alacritty supports an URL behaviour similar to other terminals:

echo -e '\e]8;;http://example.com\aThis is a link\e]8;;\a'

Possible to support this. So far I havent seen any Env var that alacritty sets that we can use to detect the users terminal. Maybe I will provide a PR if I have an Idea.

Btw, you aware of this list https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda?

Force non-linking behavior?

I'm building a CLI app that has the ability to generate usage documentation for itself as Markdown.

Under normal circumstances — e.g., using the CLI on terminal — I want the linking behavior, which works.

However, when I generate Markdown containing the descriptions of the CLI commands (which contain the links), I get the raw ASCII output for the terminal.

For regular expressions, the �[32;49m�]8;;https://github.com/google/re2/wiki/Syntax�RE2 syntax�]8;;��[m�[0m is supported.

What I'd like to have is something that would allow me to programmatically force the non-linked behavior, so that the Markdown has this instead.

For regular expressions, the RE2 syntax (https://github.com/google/re2/wiki/Syntax) is supported.

I can do it by running the generation command in a completely different terminal (e.g., Apple's Terminal.app), but it'd be nice if I didn't have to.

Extra space after the opening paren

In Terminals which do not support linking, there is an extra space after the opening paren.

Code:

fmt.Sprintf("%s", termlink.Link("RE2 syntax", "https://github.com/google/re2/wiki/Syntax"))

Display in Apple's Terminal.app (which does not support linking):

RE2 syntax ( ​https://github.com/google/re2/wiki/Syntax)

What's weird is that when I copy-paste it from the Terminal, the paste here in GitHub doesn't have it.

RE2 syntax (​https://github.com/google/re2/wiki/Syntax)

Any ideas?