{"id":15501573,"url":"https://github.com/markdumay/hugo-theme-vanity","last_synced_at":"2025-07-23T08:33:25.580Z","repository":{"id":42018041,"uuid":"406475091","full_name":"markdumay/hugo-theme-vanity","owner":"markdumay","description":"A lightweight and responsive Hugo theme to create vanity URLs for Go packages","archived":false,"fork":false,"pushed_at":"2022-04-18T08:48:06.000Z","size":405,"stargazers_count":4,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T22:12:34.615Z","etag":null,"topics":["golang","hugo-theme","vanity"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markdumay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-09-14T18:12:45.000Z","updated_at":"2024-11-02T03:25:05.000Z","dependencies_parsed_at":"2022-08-20T09:40:54.121Z","dependency_job_id":null,"html_url":"https://github.com/markdumay/hugo-theme-vanity","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdumay%2Fhugo-theme-vanity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdumay%2Fhugo-theme-vanity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdumay%2Fhugo-theme-vanity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markdumay%2Fhugo-theme-vanity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markdumay","download_url":"https://codeload.github.com/markdumay/hugo-theme-vanity/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248305849,"owners_count":21081575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","hugo-theme","vanity"],"created_at":"2024-10-02T09:04:51.765Z","updated_at":"2025-04-10T22:12:46.938Z","avatar_url":"https://github.com/markdumay.png","language":"CSS","funding_links":["https://www.buymeacoffee.com/markdumay"],"categories":[],"sub_categories":[],"readme":"# Hugo Theme Go-Vanity\n\n\u003c!-- Tagline --\u003e\n\u003cp align=\"center\"\u003e\n    \u003cb\u003eA lightweight and responsive Hugo theme to create vanity URLs for Go packages\u003c/b\u003e\n    \u003cbr /\u003e\n\u003c/p\u003e\n\n\n\u003c!-- Badges --\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://app.netlify.com/sites/go-vanity-demo/deploys\" alt=\"Netlify Status\"\u003e\n        \u003cimg src=\"https://img.shields.io/netlify/1c25f6cc-a07e-4437-8fce-fe24a3302130\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://stats.uptimerobot.com/xyGVYhLJmV\" alt=\"UptimeRobot Status\"\u003e\n        \u003cimg src=\"https://img.shields.io/uptimerobot/status/m789254382-31ea1d3d7662df896eecb04f\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/markdumay/hugo-theme-vanity/commits/main\" alt=\"Last commit\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/last-commit/markdumay/hugo-theme-vanity.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/markdumay/hugo-theme-vanity/issues\" alt=\"Issues\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/issues/markdumay/hugo-theme-vanity.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/markdumay/hugo-theme-vanity/pulls\" alt=\"Pulls\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/issues-pr-raw/markdumay/hugo-theme-vanity.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/markdumay/hugo-theme-vanity/blob/main/LICENSE\" alt=\"License\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/license/markdumay/hugo-theme-vanity\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!-- Table of Contents --\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#about\"\u003eAbout\u003c/a\u003e •\n  \u003ca href=\"#prerequisites\"\u003ePrerequisites\u003c/a\u003e •\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e •\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e •\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e •\n  \u003ca href=\"#donate\"\u003eDonate\u003c/a\u003e •\n  \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\n\u003c/p\u003e\n\n\n## About\n![./images/screenshot.png](https://raw.githubusercontent.com/markdumay/hugo-theme-vanity/main/images/screenshot.png)\n\n- [Online Demo][demo]\n- [Example Site Source][example_site]\n\nGo 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.\n\nInspired 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.\n\n\u003c!-- TODO: add tutorial deep-link \nDetailed background information is available on the author's [personal blog][blog].\n--\u003e\n\n\n## Prerequisites\nThe following prerequisites need to be met in order to use the `go-vanity` theme correctly.\n- **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.\n- **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.\n- **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.\n\n\n## Installation\nThe `go-vanity` theme can be installed as a regular Hugo theme, either as Hugo module or as Git submodule. \n\n\u003cdetails\u003e\n\u003csummary\u003eHugo Module\u003c/summary\u003e\n\n\u003e Hugo Modules require Go version 1.14 or later to be installed on your system. [Download and install][golang_download] Go as needed. \n\nFrom your project's root directory, initiate the hugo module system if needed:\n```console\n$ hugo mod init github.com/\u003cyour_user\u003e/\u003cyour_project\u003e\n```\n\nAdd the theme's repository to your `config.toml`:\n```toml\ntheme = [\"github.com/markdumay/hugo-theme-vanity\"]\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eGit Submodule\u003c/summary\u003e\n\nRun the following command from within your project's root directory.\n\n```console\n$ git submodule add https://github.com/markdumay/hugo-theme-vanity.git themes/go-vanity\n```\n\nAdd the theme to your `config.toml`:\n```toml\ntheme = \"go-vanity\"\n```\n\u003c/details\u003e\n\n\n## Configuration\nFurther 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.\n\nThe 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. \n\n```toml\nbaseURL = \"http://example.com/\"\nlanguageCode = \"en-us\"\ntitle = \"example.go\"\n# uncomment the next line when using Hugo Modules:\n# theme = [\"github.com/markdumay/hugo-theme-vanity\"]\n# uncomment the next line when using Git Submodules:\n# theme = \"go-vanity\"\ncopyright = \"Copyright © 2021 Author Name; all rights reserved.\"\npaginate = 5\n[params]\n    redirect = true\n```\n\nEach 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.\n\n```yaml\n---\ntitle: \"package\"\ndate: 2021-09-14T13:20:55+02:00\ndraft: false\nrepository: github.com/owner/repo\ngodoc: pkg.go.dev/example.com/package\ntags: [package]\n---\n```\n\n## Usage\n### Accessing the Landing Page\nOnce 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.\n\n\u003e 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.\n\nAs mentioned in the previous section, setting `redirect` to `false` in the `config.toml` allows you to inspect the generated code for each package.\n\n### Publishing and Installing a Module\n\u003e 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.\n\nIn 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.\n\n```console\n$ curl https://example.com/package\n```\n    \nThe 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.\n\nIf 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:\n    \n```console\n$ GOPROXY=proxy.golang.org go list -m example.com/package@v0.1.0\n```\n\nUse the following command to install the package in your Go project.\n```console\n$ go get example.com/package@v0.1.0\n```\n\n## Contributing\n1. Clone the repository and create a new branch \n    ```console\n    $ git checkout https://github.com/markdumay/hugo-theme-vanity.git -b name_for_new_branch\n    ```\n2. Make and test the changes\n3. Submit a Pull Request with a comprehensive description of the changes\n\n\n## Credits\nThe `go-vanity` theme is inspired by the following blog posts and sources:\n- Márk Sági-Kazár - [Vanity import paths in Go][mark_sagi_kazar_url]\n- Nate Finch - [Vanity Imports with Hugo][nate_finch_vanity_url]\n- Uber Go - [Uber's open-source software for Go][uber_go_url]\n\n## Donate\n\u003ca href=\"https://www.buymeacoffee.com/markdumay\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/lato-orange.png\" alt=\"Buy Me A Coffee\" style=\"height: 51px !important;width: 217px !important;\"\u003e\u003c/a\u003e\n\n## License\nThe `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.\n\n\u003c!-- MARKDOWN PUBLIC LINKS --\u003e\n[cc-by-nc-4.0]: https://creativecommons.org/licenses/by-nc/4.0/\n[hugo_url]: https://gohugo.io/\n[hugo_about]: https://gohugo.io/about/what-is-hugo/\n[hugo_quickstart]: https://gohugo.io/getting-started/quick-start/\n[nate_finch_vanity_url]: https://npf.io/2016/10/vanity-imports-with-hugo/\n[mark_sagi_kazar_url]: https://sagikazarmark.hu/blog/vanity-import-paths-in-go/\n[golang_download]: https://golang.org/dl/\n[golang_remote_path]: https://golang.org/cmd/go/#hdr-Remote_import_paths\n[uber_go_url]: http://go.uber.org\n[dns_checker_url]: https://dnschecker.org\n[publish_go_module]: https://golang.org/doc/modules/publishing\n\n    \n\u003c!-- MARKDOWN MAINTAINED LINKS --\u003e\n\u003c!-- TODO: add blog link\n[blog]: https://markdumay.com\n--\u003e\n[blog]: https://github.com/markdumay\n[license]: https://github.com/markdumay/hugo-theme-vanity/blob/main/LICENSE\n[repository]: https://github.com/markdumay/hugo-theme-vanity.git\n[demo]: https://go-vanity-demo.markdumay.org/\n[example_site]: https://github.com/markdumay/hugo-theme-vanity/tree/main/exampleSite\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkdumay%2Fhugo-theme-vanity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkdumay%2Fhugo-theme-vanity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkdumay%2Fhugo-theme-vanity/lists"}