Personal short URL resolver
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd/gum
etc
.gitignore
.goxc.json
.travis.yml
LICENSE
README.md
VERSION
go.mod
go.sum
gum.go
gum_test.go
redirect.go
redirect_test.go
static.go
static_test.go

README.md

gum

GoDoc Build Status

Gum is a personal short URL resolver written in Go. It is primarily designed to be used with statically generated sites.

This is the URL resolver I run behind willnorris.com (and my short domain wjn.me). For example, wjn.me/c/gum redirects to this project on GitHub. So far, I've only implemented those handlers I use on my own site, but everything should be easily usable by others.

Building with go 1.11 is recommended.

Getting Started

Install the package using:

go get willnorris.com/go/gum/cmd/gum

Once installed, ensure $GOPATH/bin is in your $PATH, then run using:

gum

This will start gum on port 4594. Test this by navigating to http://localhost:4594/ and you should see a blank page (since no redirects have been configured yet).

Path Redirects

Path redirects allow a specified path prefix, and all URLs under that prefix, to be redirected to a destination URL. The portion of the URL after the prefix is resolved relative to the destination. Note that this means that the destination should normally include a trailing slash.

Path redirects are specified with the redirect flag, which takes a value of the form prefix=destination. For example, to redirect all /w URLs to the English version of Wikipedia, run:

gum -redirect "w=https://en.wikipedia.org/wiki/"

Load http://localhost:4594/w/URL_shortening and you should be redirected to the appropriate Wikipedia article. An empty prefix or a value of "/" will redirect all URLs.

The redirect flag can be repeated multiple times. Longer prefix values will take precedence over shorter ones following the behavior of http.ServeMux.

Static File Redirects

Gum can parse HTML file and automatically register redirects based on the links specified in the files. Gum will look for files with both a rel="canonical" and rel="shortlink" link. If found, it will configure redirects from the shortlink URL path to the canonical URL. For example, assume an HTML file with the contents:

<html>
  <link rel="canonical" href="http://example.com/post/123">
  <link rel="shortlink" href="http://x.com/t123">
</html>

Gum will configure a redirect from /t123 to http://example.com/post/123. Note that only the path of the shortlink is used for creating the redirect.

Static file redirects are configured with the static_dir flag, which identifies the root directory containing the HTML files. Gum will recursively parse all files with a .html file extension, looking for the appropriate link tags. It will additionally watch the specified directory for any changes and will automatically load new or updated files.

Note that when using gum with a static site generator, static_dir should identify the folder containing the generated HTML files (for example, the _site folder when using jekyll), not the source files.

Static file redirects will take precedence over equivalent path redirects.

Alternate Short URLs

An HTML file can also specify multiple alternate short URLs to register for a given canonical URL. This is useful, for example, if you have legacy short URLs that you want to continue resolving. Alternate short URLs are specified on the rel="shortlink" link as a space separated list of URLs in the data-alt-href attribute. For example:

<link rel="shortlink" href="http://x.com/t123"
  data-alt-href="http://x.com/b/123 http://x.com/b/456">

Gum will resolve all of the shortlinks /t123, /b/123, and /b/456 to the relevant canonical URL.

License

Gum is copyright Google, but is not an official Google product. It is available under a BSD License.