help.html

{{ define "main" }}
<article class="prose max-w-5xl">
<p>
{{go}} links provide short, memorable links for the websites you and your team use most.

<h2>Creating {{go}} links</h2>

<p>
All {{go}} links have a <strong>short name</strong> and a <strong>destination link</strong> that the {{go}} link points to.
Some notes on short names:

<ul>
  <li>names must start with a letter or number
  <li>names may contain letters, numbers, hyphens, and periods
  <li>names are <strong>not</strong> case-sensitive ({{go}}/foo is the same as {{go}}/FOO)
  <li>hyphens are ignored when resolving links ({{go}}/meetingnotes is the same as {{go}}/meeting-notes)
</ul>

<p>
In simple cases, the destination link is an absolute URL, such as <strong>https://www.google.com/</strong>.

<!-- example non-functional form -->
<div class="flex flex-wrap mx-4">
  <div class="flex">
    <label class="flex my-2 px-2 items-center bg-gray-100 border border-r-0 border-gray-300 rounded-l-md text-gray-700">http://{{go}}/</label>
    <input disabled type=text size=15 value="search" class="p-2 my-2 rounded-r-md border-gray-300">
    <span class="flex m-2 items-center">&rarr;</span>
  </div>
  <input disabled type=text size=30 value="https://www.google.com/" class="p-2 my-2 mr-2 max-w-full rounded-md border-gray-300">
  <button disabled type=submit class="py-2 px-4 my-2 rounded-md bg-blue-500 border-blue-500 text-white hover:bg-blue-600 hover:border-blue-600">Create</button>
</div>

<h2>Resolving links</h2>

<p>
When logged in to your Tailscale network, {{go}} links can be entered directly into any browser or command line utility such as curl.
You do not need any additional browser extensions.

<p>
Any additional path provided after the short name will be added to the end of the destination link.
For example, if <strong>{{go}}/who</strong> goes to your company directory at <strong>http://directory/</strong>,
then <strong>{{go}}/who/amelie</strong> will go to <strong>http://directory/amelie</strong>.

<p>
<a href="#advanced">Advanced destination links</a> allow you to further customize this behavior.

<h2 id="advanced">Advanced destination links</h2>

<p>
To have more control over how {{go}} links are resolved, destination links can use <a href="https://pkg.go.dev/text/template">Go template syntax</a>.
Templates are provided a data structure with the following fields:

<ul>
  <li><code>.Path</code> is the remaining path value after the short name (without a leading slash).
    For the link <strong>{{go}}/who/amelie</strong>, the value of <code>.Path</code> is <code>amelie</code>.
  <li><code>.Now</code> is a <a href="https://pkg.go.dev/time#Time">time.Time</a> value representing the current date and time.
  <li><code>.User</code> is the current user resolving the link.
    This is the email address of the user or <code>{username}@github</code> for tailnets that use GitHub authentication.
</ul>

Templates also have access to the following template functions:

<ul>
  <li><code>PathEscape</code> is the <a href="https://pkg.go.dev/net/url#PathEscape">url.PathEscape</a> function for escaping values inside a URL path.
  <li><code>QueryEscape</code> is the <a href="https://pkg.go.dev/net/url#QueryEscape">url.QueryEscape</a> function for escaping values inside a URL query.
  <li><code>TrimPrefix</code> is the <a href="https://pkg.go.dev/strings#TrimPrefix">strings.TrimPrefix</a> function for removing a leading prefix.
  <li><code>TrimSuffix</code> is the <a href="https://pkg.go.dev/strings#TrimSuffix">strings.TrimSuffix</a> function for removing a trailing suffix.
  <li><code>ToLower</code> is the <a href="https://pkg.go.dev/strings#ToLower">strings.ToLower</a> function for mapping all Unicode letters to their lower case.
  <li><code>ToUpper</code> is the <a href="https://pkg.go.dev/strings#ToUpper">strings.ToUpper</a> function for mapping all Unicode letters to their upper case.
  <li><code>Match</code> is the <a href="https://pkg.go.dev/regexp#MatchString">regexp.MatchString</a> function for matching a regular expression pattern.
</ul>

<p>
The most common use of advanced destination links is to put the additional path in a custom location in the destination link.
For example, you might set the destination for <strong>{{go}}/search</strong> to:

<pre>{{`https://www.google.com/{{if .Path}}search?q={{QueryEscape .Path}}{{end}}`}}</pre>

When a user visits <strong>{{go}}/search</strong> with no additional path, they will be directed to <a href="https://www.google.com/">https://www.google.com/</a>.
If they include an additional path like <strong>{{go}}/search/pangolins</strong>, they will be directed to <a href="https://www.google.com/search?q=pangolins">https://www.google.com/search?q=pangolins</a>.

<h3>Examples</h3>

<table>
  <tr>
    <td>Include path in query</td>
    <td>{{go}}/search</td>
    <td>{{`https://cloudsearch.google.com/{{if .Path}}cloudsearch/search?q={{QueryEscape .Path}}{{end}}`}}</td>
  </tr>
  <tr>
    <td>Include path in destination path</td>
    <td>{{go}}/slack</td>
    <td>{{`https://company.slack.com/{{if .Path}}channels/{{PathEscape .Path}}{{end}}`}}</td>
  </tr>
  <tr>
    <td>Include path in hostname</td>
    <td>{{go}}/varz</td>
    <td>{{`http://{{if .Path}}{{.Path}}{{else}}host{{end}}.example/debug/varz`}}</td>
  </tr>
  <tr>
    <td>Include today's date in wiki page</td>
    <td>{{go}}/today</td>
    <td>{{`http://wiki/{{.Now.Format "01-02-2006"}}`}}</td>
  </tr>
</table>

<h2 id="api">Application Programming Interface (API)</h2>

<p>
There is no formal API, but many endpoints lend themselves to programmatic access.

<p>
Include a "+" after a link to get information about a link without resolving it:

<pre>$ curl -L {{go}}/search+
{{`{
"Short": "search",
"Long": "https://cloudsearch.google.com/{{if .Path}}cloudsearch/search?q={{QueryEscape .Path}}{{end}}",
"Created": "2022-06-08T04:27:32.829906577Z",
"LastEdit": "2022-06-13T04:42:08.396702416Z",
"Owner": "amelie@company.com",
"Clicks": 8
}`}}
</pre>

<p>
Visit <a href="/.export">{{go}}/.export</a> to export all saved links and their metadata in <a href="https://jsonlines.org/">JSON Lines format</a>.
This is useful to create data snapshots that can be restored later.

<pre>$ curl -L {{go}}/.export
{{`{"Short":"go","Long":"http://go","Created":"2022-05-31T13:04:44.741457796-07:00","LastEdit":"2022-05-31T13:04:44.741457796-07:00","Owner":"amelie@example.com","Clicks":1}
{"Short":"slack","Long":"https://company.slack.com/{{if .Path}}channels/{{PathEscape .Path}}{{end}}","Created":"2022-06-17T18:05:43.562948451Z","LastEdit":"2022-06-17T18:06:35.811398Z","Owner":"amelie@example.com","Clicks":4}`}}
</pre>

<p>
Create a new link by sending a POST request with a <code>short</code> and <code>long</code> value:

<pre>$ curl -L -H Sec-Golink:1 -d short=cs -d long=https://cs.github.com/ {{go}}
{{`{"Short":"cs","Long":"https://cs.github.com/","Created":"2022-06-03T22:15:29.993978392Z","LastEdit":"2022-06-03T22:15:29.993978392Z","Owner":"amelie@example.com"}`}}
</pre>

</article>
{{ end }}