The different ways of adding a theme

support
#1

OK so I think I’ve got a handle on the different ways to use a theme, so I thought I’d post this to try to summarize it for people after me so they don’t have to do as much legwork (hopefully). This summary assumes you’re using git. Please feel free to correct what I’m saying here - I have no interest in looking like a git or hugo expert, I just want to save people time.

  1. Using git clone.
    This clones a copy of a git repository to a subdirectory in the /themes folder.
    Positives: easy and quick
    Negatives: Your repository for your website will have a copy of the theme inside of it.

  2. Using git submodule.
    This clones a copy of a git repository to a subdirectory in the /themes folder, but registers it with the website repository using a .gitmodules file.
    Positives: You’ve now made clear to git the repository inside of another repository, so the dependencies are now clear.
    Negatives: git commands to clone your website repository are a little more complicated to do it recursively, etc. Seems to be somewhat unpopular on the web.

  3. Using git subtree.
    This clones a copy of a git repository to a subdirectory in the /themes folder, using a different approach than submodules to register its relationship to the repository above.
    https://www.atlassian.com/git/tutorials/git-subtree
    Positives: It seems to simplify the later cloning of your website repository, as the consumer of your repository doesn’t need to know about the subrepository.
    Negatives: If you are developing the theme at the same time, it seems that commits are little more complicated, and it’s best practice to split the commits across repository boundaries to keep the messages clear.

  4. Move the theme directory.
    You can have a theme repository cloned in another folder, and use themesDir = "../.."
    in config.toml, for example, to point to the proper folder above the theme repository.
    Positives: Completely separate repositories, easy to develop your website and the theme at the same time. Works fine for local testing.
    Negatives: Doesn’t translate to deployment.

  5. Use Hugo modules.
    Use Hugo Modules | Hugo
    You can direct Hugo to retrieve and use the theme repository during deployment.
    Positives: Once set up, it works fine and keeps the build pointing to whichever version of the theme you want.
    Negatives: I believe you are limited to retrieving released versions of a theme - ie those that have been tagged in git. This makes it hard to use for theme development.

  6. Point directly at the theme on github.
    This one isn’t clear to me yet … I’ve asked @pointyfar if he could clarify what he said over here, and I’m sure he’ll be able to help. It seems like he has had success doing this in config.toml: theme = "github.com/username/themeName".
    Positives: A useful solution for production, and also seems to be an optimal solution for testing out a theme repository in a production environment prior to labeling and releasing it. This may seem to be a minor draw, but it’s what is holding me back right now.
    Negatives: I can’t seem to get it to work.

I’d love to hear any advice folks would be willing to give on any of these … thanks in advance. :slight_smile:

Carmine

#2

I don’t see any further questions on your previous thread asking for clarification?

It works as simply as I stated:

theme = "github.com/user/repo"

This assumes your site is a hugo module. So you would do beforehand:

hugo mod init "your-mod-name"

As to why you couldn’t get it to work, I wouldn’t know. Refer to Requesting Help to see what information you would need to provide for us to be able to help.

#3

4 is 1,2,3 or 5 just at another location
6 is 5 with the Github repo being a theme
3 is not simplifying later cloning, it’s complicating updates.

method 1) put a subfolder into themes
method 2) clone as submodule into themes
method 3) add as module

method 1 is simplest, but hardest updatable
method 2 is inbetween
method 3 is complicatest, but easiest updatable

If you don’t faint when you see a dos-box, shell or other terminal then do method 3. Else do method 1. Forget all other methods afterwards.

#4

@pointyfar oh threads close in 2 days … I had other things to figure out. When I turned back to your production solution, it didn’t work for me. At that point I couldn’t ask you for clarification in the preexisting thread.

So thanks for clarifying #6! #6 is the same as #5 … to make it work, you have to already have hugo mod init run on your website repository. Then putting the url of the theme directly in the themes parameter allows hugo to pick up the module directly. Similar to doing hugo mod get. Ah, now that I know #6 is a module solution I see it right here:

And I figured out the final thing regarding hugo modules - had to go back to go:

If you want to point to a branch of a repository, or a commit that hasn’t been released, you use hugo mod get https://github.com/username/themeName@commitHash. This was useful to me for testing a theme feature that had to be tested in a production environment (Netlify forms).

Hopefully other folks run into this thread when they’re learning about themes and it helps them.

Thanks,

Carmine