golink/tmpl/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>.

<p>
<img width=737 height=62 class="mx-4" src="/.static/images/create-link.png">

<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.
</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 }}