From 009a44b866c367f37932c4aeee79982eb718ecee Mon Sep 17 00:00:00 2001
From: Piotr Murach <pmurach@gmail.com>
Date: Sat, 28 Sep 2024 14:12:27 +0200
Subject: [PATCH] Add an API section about the link_to method and the attrs
 option to the readme

---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/README.md b/README.md
index 069d697..0d0c8cc 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,47 @@ In cases when the terminal cannot support hyperlinks, an alternative is printed:
 # TTY toolkit -> https://ttytoolkit.org
 ```
 
+## API
+
+### link_to
+
+The `link_to` method accepts two arguments, the name and the URL. The second
+URL argument is optional.
+
+For example, to create a hyperlink to `https://ttytoolkit.org`
+named `TTY Toolkit`:
+
+```ruby
+link.link_to("TTY Toolkit", "https://ttytoolkit.org")
+```
+
+To create a hyperlink where the name is the same as the URL:
+
+```ruby
+link.link_to("https://ttytoolkit.org")
+```
+
+#### :attrs
+
+The `link_to` method accepts the `:attrs` keyword to define attributes for a
+hyperlink. Note that currently, hyperlink-capable terminals support only the
+`id` attribute. However, there is no limitation on the attribute names to
+allow future support.
+
+For example, to define the `id` attribute:
+
+```ruby
+link.link_to("TTY Toolkit", "https://ttytoolkit.org", attrs: {id: "tty-toolkit"})
+```
+
+To define many attributes such as `id`, `lang` and `title`:
+
+```ruby
+link.link_to("TTY Toolkit", "https://ttytoolkit.org", attrs: {
+  id: "tty-toolkit", lang: "en", title: "Terminal Apps The Easy Way"
+})
+```
+
 ## Supported Terminals
 
 The **TTY::Link** supports hyperlink generation in the following terminals: