Merge pull request #22518 from celestehorgan/update-readme

Update README to encourage building in containers

README.md

@@ -4,37 +4,61 @@
 
 This repository contains the assets required to build the [Kubernetes website and documentation](https://kubernetes.io/). We're glad that you want to contribute!
 
-## Running the website locally using Hugo
+# Using this repository
 
-See the [official Hugo documentation](https://gohugo.io/getting-started/installing/) for Hugo installation instructions. Make sure to install the Hugo extended version specified by the `HUGO_VERSION` environment variable in the [`netlify.toml`](netlify.toml#L10) file.
+You can run the website locally using Hugo, or you can run it in a container runtime. We strongly recommend using the container runtime, as it gives deployment consistency with the live website.
 
-Before building the site, clone the Kubernetes website repository:
+## Prerequisites
 
-```bash
+To use this repository, you need the following installed locally:
+
+- [yarn](https://yarnpkg.com/)
+- [npm](https://www.npmjs.com/)
+- [Go](https://golang.org/)
+- [Hugo](https://gohugo.io/)
+- A container runtime, like [Docker](https://www.docker.com/).
+
+Before you start, install the dependencies. Clone the repository and navigate to the directory:
+
+```
 git clone https://github.com/kubernetes/website.git
 cd website
+```
+
+The Kubernetes website uses the [Docsy Hugo theme](https://github.com/google/docsy#readme). Even if you plan to run the website in a container, we strongly recommend pulling in the submodule and other development dependencies by running the following:
+
+```
+# install dependencies
+yarn
+
+# pull in the Docsy submodule
 git submodule update --init --recursive --depth 1
 ```
 
-**Note:**  The Kubernetes website deploys the [Docsy Hugo theme](https://github.com/google/docsy#readme).
+## Running the website using a container
-If you have not updated your website repository, the `website/themes/docsy` directory is empty. The site cannot build
-without a local copy of the theme.
 
-Update the website theme:
+To build the site in a container, run the following to build the container image and run it:
 
-```bash
-git submodule update --init --recursive --depth 1
 ```
+make container-image
+make container-serve
+```
+
+Open up your browser to http://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.
+
+## Running the website locally using Hugo
+
+Make sure to install the Hugo extended version specified by the `HUGO_VERSION` environment variable in the [`netlify.toml`](netlify.toml#L10) file.
 
 To build and test the site locally, run:
 
 ```bash
-hugo server --buildFuture
+make serve
 ```
 
 This will start the local Hugo server on port 1313. Open up your browser to http://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.
 
-## Get involved with SIG Docs
+# Get involved with SIG Docs
 
 Learn more about SIG Docs Kubernetes community and meetings on the [community page](https://github.com/kubernetes/community/tree/master/sig-docs#meetings).
 
@@ -43,7 +67,7 @@ You can also reach the maintainers of this project at:
 - [Slack](https://kubernetes.slack.com/messages/sig-docs)
 - [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)
 
-## Contributing to the docs
+# Contributing to the docs
 
 You can click the **Fork** button in the upper-right area of the screen to create a copy of this repository in your GitHub account. This copy is called a *fork*. Make any changes you want in your fork, and when you are ready to send those changes to us, go to your fork and create a new pull request to let us know about it.
 
@@ -60,7 +84,7 @@ For more information about contributing to the Kubernetes documentation, see:
 * [Documentation Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/)
 * [Localizing Kubernetes Documentation](https://kubernetes.io/docs/contribute/localization/)
 
-## Localization `README.md`'s
+# Localization `README.md`'s
 
 | Language  | Language |
 |---|---|
@@ -72,10 +96,10 @@ For more information about contributing to the Kubernetes documentation, see:
 |[Italian](README-it.md)|[Ukrainian](README-uk.md)|
 |[Japanese](README-ja.md)|[Vietnamese](README-vi.md)|
 
-## Code of conduct
+# Code of conduct
 
 Participation in the Kubernetes community is governed by the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
 
-## Thank you!
+# Thank you!
 
 Kubernetes thrives on community participation, and we appreciate your contributions to our website and our documentation!