vangen

README

vangen²

Vangen is a tool for generating static HTML for Go vanity import paths. It's a fork of leighmcculloch/vangen.

Go vanity import paths work by serving a HTML file that tells the go get tool where to download the source from. You can still host the source code at Github, BitBucket, but the vanity URL gives you portability and other benefits.

Why

• Maintain Go vanity import paths with a simple definition file vangen.yaml.
• Host Go vanity import paths using static hosting. No need for Google AppEngine, Heroku, etc. Host the files on Github Pages, AWS S3, Google Cloud Storage, etc.

Why a Fork?

• Use YAML instead of JSON for configuration.
• Add pico.css to make the generated HTML a bit nicer and add dark mode.
• Rename "sub packages" to "sub modules", which is more clear IMHO.

Install

Download one of the precompiled releases, use the ready-made container image codeberg.org/xrstf/vangen or install from source:

go get go.xrstf.de/vangen

Usage

1. Create a vangen.yaml (see examples below)
2. Run vangen
3. Host the files outputted in vangen/ at your domain
4. Try it out with go get [domain]/[package]

$ vangen --help
Usage of _build/vangen:
  -c, --config filename    vangen JSON/YAML configuration filename (default "vangen.yaml")
  -o, --output directory   output directory that static files will be written to (default "vangen")
  -V, --version            print program version

Examples

Minimal

The repository type and source properties will be set automatically when url begins with one of the known code hosting sites:

• https://github.com
• https://gitlab.com

Alternatively, you can use type: gitea or type: forgejo to auto-detect the required URLs.

Below is a minimal config for a project hosted on GitHub.

domain: go.xrstf.de
repositories:
  - prefix: optional
    url: https://github.com/leighmcculloch/go-optional
    subs:
      - name: template

For a project on Forgejo:

domain: go.xrstf.de
repositories:
  - prefix: vangen
    main: true
    url: https://codeberg.org/xrstf/vangen
    type: forgejo

This is effectively a shortcut for

domain: go.xrstf.de
repositories:
  - prefix: vangen
    main: true
    url: https://codeberg.org/xrstf/vangen
    type: git
    source:
      home: "https://codeberg.org/xrstf/vangen"
      dir: "https://codeberg.org/xrstf/vangen/tree/main{/dir}"
      file: "https://codeberg.org/xrstf/vangen/blob/main{/dir}/{file}#L{line}"