Build Hugo site with GitHub Actions and deploy to GitHub Pages #1245

umarcor · 2020-10-04T23:44:41Z

In this PR, a GitHub Actions workflow is added for building a web site with Hugo and deploying it to GitHub Pages (branch gh-pages).

The content of the README is split to multiple markdown sources.
Markdown sources from the root and from subdir doc are moved to site/content .
- Documentation sources regarding completions are placed in site/content/completions.
- Documentation sources regarding documentation generation are placed in site/content/docgen.
Hugo configuration files are added to site. @bep's docuapi theme is used.
In a GitHub Actions workflow, Hugo is installed, the theme is installed, the site is built, and the site is uploaded as an artifact as well as pushed to branch gh-pages.
The logo from the README is used in the site (with a different font color).
Any contributor that forks the repo and pushes some change, will have the site automatically built and uploaded to username.github.io/cobra.

See:

Proposed README: https://github.com/umarcor/cobra/blob/ci-site/README.md
Proposed site: https://umarcor.github.io/cobra
Example CI run: https://github.com/umarcor/cobra/actions/runs/288401296 (note the artifact)

Ref #985 #1243 #1244

spf13 · 2021-01-13T17:08:46Z

I've opened cobra.dev source to a few contributors. https://github.com/spf13/cobra.dev .
I'd love to support however I can.

umarcor · 2021-01-15T04:43:55Z

@spf13, thanks a lot! I will repurpose this PR and probably split it between here and spf13/cobra.dev.

Just something I'm unsure about: where is cobra.dev deployed from? spf13/cobra.dev contains the sources of a Hugo site. However, I did not see any branch with the artifacts and as far as I am aware, GitHub can only build Jekyll sites from sources. Hence, I assume that the site is not hosted on GitHub Pages. Do you have some private pipeline/CI to take care of that?

spf13 · 2021-01-15T14:57:58Z

It's currently hosted on firebase hosting. It looks like I never set up any autodeploy, but I'm happy to do that. Doing a quick search found https://github.com/marketplace/actions/hugo-on-fire which seems like the ideal solution.

…

On Thu, Jan 14, 2021 at 11:44 PM Unai Martinez-Corral < ***@***.***> wrote: @spf13 <https://github.com/spf13>, thanks a lot! I will repurpose this PR and probably split it between here and spf13/cobra.dev. Just something I'm unsure about: where is cobra.dev deployed from? spf13/ cobra.dev contains the sources of a Hugo site. However, I did not see any branch with the artifacts and as far as I am aware, GitHub can only build Jekyll sites from sources. Hence, I assume that the site is not hosted on GitHub Pages. Do you have some private pipeline/CI to take care of that? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1245 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABKKZECMQHNSVOZIDLG3VLSZ7BZRANCNFSM4SEAT2RQ> .

umarcor · 2021-01-15T15:17:13Z

@spf13, nice and thanks.

For now, it's enough to know that we can handle it with an Action in a GitHub Actions workflow. I will probably propose PRs to be autodeployed to gh-pages of the contributor's fork. That will allow any contributor to push changes and see the results automatically deployed to their username.github.io/cobra or username.github.io/cobra.dev site.

We'll discuss later whether the "official" deployment needs to be done here, in spf13/cobra.dev or somewhere else; that's a minor technical thing.

github-actions · 2021-03-17T00:21:47Z

This PR is being marked as stale due to a long period of inactivity

spf13 · 2021-11-02T20:24:36Z

@umarcor what's the status on this. I think your new site is far superior to the existing one. I did a small amount of management to bring it up to date so it builds again, but still prefer yours.

Let me know how I can help with this.

umarcor · 2021-11-02T22:46:06Z

@spf13, see #1428. That's the first subset of this PR: moving all markdown sources related to the documentation into a single directory.

However, co-maintainers have been struggling to merge PRs in the last months, so I kept this docs/site stuff on hold until I get some other "less disruptive" modifications accepted (see https://github.com/spf13/cobra/pulls/umarcor). We are heading for a release (see #1496) and I listed all my ready-to-merge PRs there.

Then, I'll focus on #1428 (subset of this), #1245 (this) and #1430.

I'd be glad if you could review and maybe approve #1245 and #1430. The latter is not strictly related to the doc/site, but it is a minor reorganisation of the codebase.

umarcor · 2022-02-25T09:20:34Z

This PR is not stale, but blocked by #1428. Please, remove the kind/stale label.
See #1245 (comment).

@bep

…e with [Hugo](https://gohugo.io/) and deploying it to GitHub Pages (branch `gh-pages`). - The content of the README is split to multiple markdown sources. - Markdown sources from the root and from subdir `doc` are moved to `site/content` . - Documentation sources regarding completions are placed in `site/content/completions`. - Documentation sources regarding documentation generation are placed in `site/content/docgen`. - Hugo configuration files are added to `site`. @bep's [docuapi](https://github.com/bep/docuapi) theme is used. - In a GitHub Actions workflow, Hugo is installed, the theme is installed, the site is built, and the site is uploaded as an artifact as well as pushed to branch `gh-pages`. - The logo from the README is used in the site (with a different font color). - Any contributor that forks the repo and pushes some change, will have the site automatically built and uploaded to `username.github.io/cobra`. See: - Proposed README: https://github.com/umarcor/cobra/blob/ci-site/README.md - Proposed site: https://umarcor.github.io/cobra - Example CI run: https://github.com/umarcor/cobra/actions/runs/288401296 (note the artifact) Ref #985 #1243 #1244 Merge spf13/cobra#1245

github-actions · 2023-06-20T17:45:09Z