https://github.com/markdumay/hugo-theme-vanity
A lightweight and responsive Hugo theme to create vanity URLs for Go packages
https://github.com/markdumay/hugo-theme-vanity
golang hugo-theme vanity
Last synced: 11 months ago
JSON representation
A lightweight and responsive Hugo theme to create vanity URLs for Go packages
- Host: GitHub
- URL: https://github.com/markdumay/hugo-theme-vanity
- Owner: markdumay
- License: mit
- Created: 2021-09-14T18:12:45.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2022-04-18T08:48:06.000Z (about 4 years ago)
- Last Synced: 2025-04-10T22:12:34.615Z (about 1 year ago)
- Topics: golang, hugo-theme, vanity
- Language: CSS
- Homepage:
- Size: 396 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Hugo Theme Go-Vanity
A lightweight and responsive Hugo theme to create vanity URLs for Go packages
About •
Prerequisites •
Installation •
Configuration •
Usage •
Contributing •
Donate •
License
## About
- [Online Demo][demo]
- [Example Site Source][example_site]
Go uses URLs such as `github.com/uber-go/atomic` to import packages. This import statement links directly to the repository hosted on `github.com`. Go supports [vanity import paths][golang_remote_path] to decouple the import path and the code repository. For example, the `atomic` package is made available at `go.uber.org/atomic`, which redirects to GitHub under the hood.
Inspired by the [Uber Go][uber_go_url] landing page, this repository simplifies the creation and maintenance of a website to list and resolve the packages using a vanity base url (e.g. `example.com`). The repository is implemented as a theme called `go-vanity` for [Hugo][hugo_url]. The generated static site can be deployed on any capable host. The next sections describe the prerequisites, installation, and configuration of a vanity site.
## Prerequisites
The following prerequisites need to be met in order to use the `go-vanity` theme correctly.
- **A (local) machine with Hugo and Git installed** - Hugo is needed to test the configuration and to generate the static site. The [quickstart][hugo_quickstart] describes the key steps how to get Hugo, including Git, up and running.
- **A web host is required** - A web host is required to host the landing page and the related content generated by Hugo. The [about section][hugo_about] of Hugo displays a list of popular hosting providers.
- **A registered domain name is required** - A domain name (such as `example.com`) is required to be used as basis for the vanity url. The DNS should point to your web host.
## Installation
The `go-vanity` theme can be installed as a regular Hugo theme, either as Hugo module or as Git submodule.
Hugo Module
> Hugo Modules require Go version 1.14 or later to be installed on your system. [Download and install][golang_download] Go as needed.
From your project's root directory, initiate the hugo module system if needed:
```console
$ hugo mod init github.com//
```
Add the theme's repository to your `config.toml`:
```toml
theme = ["github.com/markdumay/hugo-theme-vanity"]
```
Git Submodule
Run the following command from within your project's root directory.
```console
$ git submodule add https://github.com/markdumay/hugo-theme-vanity.git themes/go-vanity
```
Add the theme to your `config.toml`:
```toml
theme = "go-vanity"
```
## Configuration
Further refine the `config.toml` once the theme has been installed. The `baseURL` is used as the base path for your vanity URL. The landing page will display a default paginator if `paginate` is set in the main configuration. Additionally, a copyright notice is added to the landing page's footer when specified.
The theme uses one parameter: `redirect`. When `redirect` is set to `false`, individual package URLs will not redirect automatically. This allows you to test the settings and to inspect the generated HTML code.
```toml
baseURL = "http://example.com/"
languageCode = "en-us"
title = "example.go"
# uncomment the next line when using Hugo Modules:
# theme = ["github.com/markdumay/hugo-theme-vanity"]
# uncomment the next line when using Git Submodules:
# theme = "go-vanity"
copyright = "Copyright © 2021 Author Name; all rights reserved."
paginate = 5
[params]
redirect = true
```
Each package should have its own content file. This file requires two additional variables in the frontmatter: `repository` and `godoc`. The `https://` prefix for these URLs is added automatically by the `go-vanity` theme. The configuration of `example.com/package` should be defined in `content/package.md`. Lastly, the file should include the tag `package` for the package to be rendered on the landing page.
```yaml
---
title: "package"
date: 2021-09-14T13:20:55+02:00
draft: false
repository: github.com/owner/repo
godoc: pkg.go.dev/example.com/package
tags: [package]
---
```
## Usage
### Accessing the Landing Page
Once configured, run or deploy your Hugo site as usual. When running locally, the landing page is available at `localhost:1313`. The URL `localhost:1313/package` will redirect to `github.com/owner/repo`. When deployed in production, the URLs will change to `example.com` and `example.com/package` respectively.
> When running locally, `hugo server -b http://example.com` replaces `localhost:1313` with `example.com`. This allows you to visually verify the rendering of the pages. This may lead to server binding errors though.
As mentioned in the previous section, setting `redirect` to `false` in the `config.toml` allows you to inspect the generated code for each package.
### Publishing and Installing a Module
> If you have setup a new DNS entry, please allow for some time to propagate all the changes. DNS changes can take up to 24 hours to be fully resolved. Tools like [DNS Checker][dns_checker_url] can help you verify the propagation status.
In order for the Go tools to use your vanity URL you should deploy your generated site to production first. Be sure `redirect` is set to `true` in the `config.toml`. Once your vanity site has been deployed to production, you can verify the status of a package by invoking `curl` from the command line.
```console
$ curl https://example.com/package
```
The response should include valid meta tags for `go-import` and `go-source`. Additionally, the `head` should include a `refresh` directive redirecting page visitors to the correct repository.
If the deployment was successful, you can follow the regular steps to [publish a Go module][publish_go_module]. In particular, the last step should return a valid response for your package and tagged version:
```console
$ GOPROXY=proxy.golang.org go list -m example.com/package@v0.1.0
```
Use the following command to install the package in your Go project.
```console
$ go get example.com/package@v0.1.0
```
## Contributing
1. Clone the repository and create a new branch
```console
$ git checkout https://github.com/markdumay/hugo-theme-vanity.git -b name_for_new_branch
```
2. Make and test the changes
3. Submit a Pull Request with a comprehensive description of the changes
## Credits
The `go-vanity` theme is inspired by the following blog posts and sources:
- Márk Sági-Kazár - [Vanity import paths in Go][mark_sagi_kazar_url]
- Nate Finch - [Vanity Imports with Hugo][nate_finch_vanity_url]
- Uber Go - [Uber's open-source software for Go][uber_go_url]
## Donate
## License
The `hugo-theme-vanity` codebase is released under the [MIT license][license]. The documentation (including the "README") is licensed under the Creative Commons ([CC BY-NC 4.0)][cc-by-nc-4.0] license.
[cc-by-nc-4.0]: https://creativecommons.org/licenses/by-nc/4.0/
[hugo_url]: https://gohugo.io/
[hugo_about]: https://gohugo.io/about/what-is-hugo/
[hugo_quickstart]: https://gohugo.io/getting-started/quick-start/
[nate_finch_vanity_url]: https://npf.io/2016/10/vanity-imports-with-hugo/
[mark_sagi_kazar_url]: https://sagikazarmark.hu/blog/vanity-import-paths-in-go/
[golang_download]: https://golang.org/dl/
[golang_remote_path]: https://golang.org/cmd/go/#hdr-Remote_import_paths
[uber_go_url]: http://go.uber.org
[dns_checker_url]: https://dnschecker.org
[publish_go_module]: https://golang.org/doc/modules/publishing
[blog]: https://github.com/markdumay
[license]: https://github.com/markdumay/hugo-theme-vanity/blob/main/LICENSE
[repository]: https://github.com/markdumay/hugo-theme-vanity.git
[demo]: https://go-vanity-demo.markdumay.org/
[example_site]: https://github.com/markdumay/hugo-theme-vanity/tree/main/exampleSite