docs: add hugo website

[dvdksn]

Relates to #3999

After chatting with @milosgajdos about removing the registry docs from Docker's official documentation website, we thought it would be nice if the distribution docs had it's own website.

This PR makes the docs/ directory a Hugo website, and updates the files accordingly.

Site preview: http://registry.surge.sh/

The theme used for the website is: https://geekdocs.de/

Also included

• Dockerfile for building the site
• Bake targets
• Tests checking for broken links (including external links)

Didn't include docs-test in the GitHub actions workflow yet.

Not included

Deployment/hosting

#3999 specifies GitHub pages, but AFAIK that requires that we host the docs in a repo named distribution/distribution.github.io. So we may want to consider an alternative hosting solution. We use Netlify for the Docker docs, for example.

[milosgajdos]

Yass! This is awesome, thanks @dvdksn

@Jamstah @davidspek @thaJeztah should we create the docs repository as originally suggested? I had a look at Netlify and they do have an OSS program, though that'd require getting through some CNCF bureaucracy and there are some other issues.

I think @Jamstah actually suggested in the original issue to have a dedicated repository. Maybe we could revisit that so we can host the docs pages on GH?

[Jamstah]

I prefer one repo :)

We would only need to use distribution/distribution.github.io if we wanted to host on https://distribution.github.io/. You can use a custom domain on any repo, do we know what the CNCF do for custom domains? IS that a question for @SteveLasker?

[milosgajdos]

if we wanted to host on distribution.github.io

Personally, I feel this would be a good first step with a follow-up to CNCF for DNS changes on their side + potentially some sync of the static pages where that may be.

I can chase @SteveLasker today as he's familiar with most of the CNCF things, but that shouldnt stop us from making a decision about this.

I'll wait for the other folks to weigh in

[Jamstah]

The github pages url of this repo is https://distribution.github.io/distribution/

If we're going to use a temporary url, we can use that one.

[Jamstah]

I know most of these changes are nothing to do with the work you've done (which looks amazing btw), but they are things I think we'd want to clean up before publishing.

Happy to make some changes to this branch (if github lets me), or make a PR to your branch, or just PR the main branch, if you prefer, but as you've done the bulk of the work, I thought you might want it in the same pr.

Where does the Docker come from here? Should be Distribution Registry or something.

We should list other hosting services, quay.io for example is also free.

We should list other container tools, perhaps podman. And also say which version of the OCI Distribution spec we comply to. Maybe call it compatibility instead of requirements?

Image name should be updated to the ones built from this project and expanded to the full reference (docker.io/distribution/registry:edge). Especially when this is done: #4014

We should probably do a search for "Docker Registry" in the docs and replace with "Distribution Registry" or something.

[milosgajdos]

Happy to make some changes to this branch (if github lets me), or make a PR to your branch, or just PR the main branch

Yeah, we need to debrand this from Docker I agree. In fact I have started doing the cleanup in the official images description: docker-library/docs#2375

Maybe you can open a PR @Jamstah and then @dvdksn just rebases once your changes are in?

We still need to agree on the follow-up to this PR etc so I see no reason why we shouldnt clean up the docs before we publish them wherever that may be. Thoughts?

[dvdksn]

@Jamstah yep, noticed these too and I think we should change them for sure. Didn't want to jump the gun though and also not sure about the naming sometimes (e.g. Distribution Registry, CNCF Distribution, or just "Distribution", etc)

Feel free to make changes in this PR directly

[dvdksn]

Maybe you can open a PR @Jamstah and then @dvdksn just rebases once your changes are in?

We could do this too but there were quite a lot of formatting changes and link fixes done by myself here, so maybe easier to handle it all here?

[milosgajdos]

Sounds good @dvdksn. Let's do that in this PR then

[Jamstah]

My take here: 83dd4ff

[Jamstah]

@dvdksn I assume that your repo isn't auto buliding to your preview site?

[Jamstah]

I guess we also want this: https://gohugo.io/hosting-and-deployment/hosting-on-github/

But that could be on a separate pr.

[milosgajdos]

I like your updates @Jamstah 👍 Added 2 comments but theyre not a blocker for me.

[Jamstah]

Have made the fixes I think we need, would be good to see them in a preview.

I'd like to see the set up for publishing to github pages, but also happy to follow on with that work in another PR if you've had enough @dvdksn :)

[dvdksn]

@Jamstah thank you - I reuploaded the preview site with your changes. I added a GHA workflow just now, but whether it works is a different question 😅 I only added main builds for now since I am not sure if it's possible to (easily) do branch deploys for PRs with github pages.

[milosgajdos]

CC: @crazy-max if you could spare a few cycles on checking the GH action 😄

I also understand we'll have to change the repo settings and point pages to docs/ directory 🤔 once this is merged

[dvdksn]

I also understand we'll have to change the repo settings and point pages to docs/ directory 🤔 once this is merged

I think that when we deploy to Pages with GitHub Actions, it's all controlled by YAML and there's no need to mess with the repo settings.

• actions/upload-pages-artifact@v2 creates a tarball of the site and uploads as a workflow artifact
• actions/deploy-pages@v2 deploys using the artifact

[milosgajdos]

Let's merge and iterate. These are the docs that don't break the code, so smaller blast radius.

[Jamstah]

You do need to turn on pages in the settings, you just select GitHub actions as the source.

I did a test run in my personal org, and got a permissions error, but I didn't chase it any further as I saw you merged this :)

@milosgajdos can you turn on the pages setting, then we can rerun the workflow and see if it works right.

[milosgajdos]

yeah I did it eventually but something is broken...we also need to rename the dockerhub.md file to distribution.md 😅 I'll look into it tomorrow...but something is already working https://distribution.github.io/distribution/ --> the index page 😄