From c193c4dd4476d1d8538658cc6dab32bd90a3e4a1 Mon Sep 17 00:00:00 2001 From: Celeste Horgan Date: Tue, 14 Jul 2020 12:53:45 -0700 Subject: [PATCH] Update readme Signed-off-by: Celeste Horgan --- README.md | 56 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 7c4809287f..d4c13cb77c 100644 --- a/README.md +++ b/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). -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. +## Running the website using a container -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! \ No newline at end of file