Deploying to github

Following the quickstart instructions Host on GitHub Pages | Hugo the prerequisites say "create a Hugo site and test it locally with hugo server, which I did successfully.

But Step 1 and 2 say “create a GitHub repo” and “push your local repo to GitHub”. After creating a repo on GitHub and cloning it locally, the local repo has only README, LICENSE and .gitignore, so the create and test a Hugo site should come after cloning the local repo.

I did that, so the local repo now has .github/workflows/hugo.yaml and the whole “website/” folder that works properly with hugo server. But when I push to GitHub the action fails on the Build with Hugo step: “Error: Unable to locate config file or config directory. Perhaps you need to create a new site”

.github/workflows/hugo.yaml and website/hugo.toml are present. What other config file is the build action looking for?

Your repo structure should look something like this:

Whether these files are present depends on how you built your site:

  • go.mod
  • go.sum
  • package-lock.json
  • package.json
  • postcss.config.js

Thanks - that works. The quickstart instructions should be fixed to not create a quickstart directory in the local repo.

The documentation is fine.

If you followed the quick start guide you’ve already done a git init here:

And when you create a repository on GitHub you are presented with these instructions:


There’s no need to clone anything.

I did not and do not see those instructions anywhere on

  • the command line at git init:
  • or even

Yes, it is possible to push without pulling, but people can have used GitHub for years without ever doing so. In any case, it couldn’t hurt for the Hugo instructions to be explicit. This is a quckstart, and users of it can be expected to have varying levels of experience.

Those instructions are displayed in your browser when you create a new repository on GitHub. We are not including them in our documentation.

They are not.

I almost included the screenshot above, then deleted it. But here it is.

You need to click the “create repository” button to see the instructions.

Maybe adding something like:

Use an existing repository for your hugo site:

git clone repopath/reponame
cd reponame
hugo new site . --force

And a hint what happens with duplicates

They are not displayed if you create a README.

As an experienced software developer but new user of Hugo I believe others could be helped by a clue as simple as "Step one - create a GitHub repository (don’t check “Add a README file”). But this is your site, suit yourself.

Let’s revisit this when more than one person has a problem… these instructions have been in place for years.

1 Like

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.