Merge pull request #22518 from celestehorgan/update-readme

Update README to encourage building in containers
This commit is contained in:
Kubernetes Prow Robot 2020-07-30 11:47:07 -07:00 committed by GitHub
commit 9f1676e16c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 40 additions and 16 deletions

View File

@ -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! 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 git clone https://github.com/kubernetes/website.git
cd website 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 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: To build and test the site locally, run:
```bash ```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. 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). 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) - [Slack](https://kubernetes.slack.com/messages/sig-docs)
- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-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. 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/) * [Documentation Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/)
* [Localizing Kubernetes Documentation](https://kubernetes.io/docs/contribute/localization/) * [Localizing Kubernetes Documentation](https://kubernetes.io/docs/contribute/localization/)
## Localization `README.md`'s # Localization `README.md`'s
| Language | Language | | Language | Language |
|---|---| |---|---|
@ -72,10 +96,10 @@ For more information about contributing to the Kubernetes documentation, see:
|[Italian](README-it.md)|[Ukrainian](README-uk.md)| |[Italian](README-it.md)|[Ukrainian](README-uk.md)|
|[Japanese](README-ja.md)|[Vietnamese](README-vi.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). 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! Kubernetes thrives on community participation, and we appreciate your contributions to our website and our documentation!