Lynx is a Hugo theme designed to be a simple links page, similar to Linktree. Lynx differs by being extremely simple and performant. In this tutorial, I will tell you how to host your own Lynx site on GitHub Pages.

Lynx Preview

Installing Hugo

To progress, you will need to install Hugo and Git. Hugo is an open-source static site generator known for its speed and flexibility, it will be the base for our GitHub Pages site. Git is a command-line tool used to interface with the Git system.

1
2
3

sudo apt install hugo git
# or MacOS
brew install hugo git

Setting Up Your Site

Now let’s set up your site and add the Lynx theme. First, create a site with Hugo’s new site command. Next open your site’s folder and initialize it, once completed add the Lynx theme as a submodule. This will create a symlink to the Lynx repository, so new versions will be pulled when it’s updated.

1
2
3
4
5
6
7
8

# Create site named "lynx"
hugo new site lynx

# Change directory to lynx
cd lynx

# Initialize folder & add theme as a submodule so it gets updated as Lynx does.
git init && git submodule add -b stable https://github.com/jpanther/lynx.git themes/Lynx

Example Config

Next, copy this base config to config.toml and tweak to your liking. You can preview your site by running hugo server and clicking the link it generates (e.g. localhost:1313). Full configuration options here.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# Site Config
baseURL = "https://username.github.io" # Add /reponame for project site
languageCode = "en-us"
title = "name | Lynx"
theme = "Lynx"

enableRobotsTXT = true
[outputs]
  home = ["HTML"]

# SEO
[params]
  env = "production"
  title = "page title"
  author = "Your name here"
  description = "My social links, powered by Hugo & Lynx"
  keywords = [ "Lynx", "Linktree", "About" ]

# Lynx Config
[author]
  image = "img/image.jpg" # Image path or link
  name = "Your name here"
  headline = "Description/bio"
  links = [
    { github = "https://github.com/username" },
    { x = "https://x.com/username" },
    { email = "mailto:hello@your_domain.com" },
    { link = "https://link-to-some-website.com" }
  ]

enableEmoji = true
disableKinds = ["taxonomy", "term"]

[markup.highlight]
  noClasses = false
[markup.goldmark.renderer]
  unsafe = true

Adding GitHub Workflow & Deploying

Once you feel like your site is complete, save this workflow file to .github/workflows/gh-pages.yml in your site’s folder. Now all that’s left to do is upload your site-folder’s contents to GitHub and set GitHub Pages’ deployment branch to gh-pages.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

name: github pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --gc --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public