diff --git a/.circleci/config.yml b/.circleci/config.yml index c99f4556a5..4d7ffc3e00 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -9,6 +9,10 @@ jobs: steps: - checkout + - run: + name: Building Site + command: scripts/build_site.sh + - run: name: Generating Site command: scripts/gen_site.sh "" -no_minify -no_aliases diff --git a/.spelling b/.spelling index fc3bfc6da3..e78c32f3ec 100644 --- a/.spelling +++ b/.spelling @@ -265,6 +265,8 @@ learnings LibreSSL lifecycle LightStep +linter +linters liveness logInfo loopback diff --git a/Makefile b/Makefile index 602768b2b7..3baf0fb4b7 100644 --- a/Makefile +++ b/Makefile @@ -13,19 +13,19 @@ baseurl := "$(URL)" endif build: - $(docker) scripts/build_site.sh + @$(docker) scripts/build_site.sh -gen: - $(docker) scripts/gen_site.sh "" -minify -no_aliases +gen: build + @$(docker) scripts/gen_site.sh "" -minify -no_aliases opt: - $(docker) scripts/opt_site.sh + @$(docker) scripts/opt_site.sh -lint: - $(docker) scripts/lint_site.sh +lint: build gen + @$(docker) scripts/lint_site.sh -serve: - docker run -t -i --sig-proxy=true --rm -v $(shell pwd):/site -w /site -p 1313:1313 $(img) hugo serve --baseURL "http://${ISTIO_SERVE_DOMAIN}:1313/" --bind 0.0.0.0 --disableFastRender +serve: build + @docker run -t -i --sig-proxy=true --rm -v $(shell pwd):/site -w /site -p 1313:1313 $(img) hugo serve --baseURL "http://${ISTIO_SERVE_DOMAIN}:1313/" --bind 0.0.0.0 --disableFastRender netlify: - scripts/gen_site.sh "$(baseurl)" -minify -aliases + @scripts/gen_site.sh "$(baseurl)" -minify -aliases diff --git a/README.md b/README.md index b0e39735f7..4de9334298 100644 --- a/README.md +++ b/README.md @@ -14,106 +14,16 @@ file to learn about the overall Istio project and how to get in touch with us. T contribute to any of the Istio components, please see the Istio [contribution guidelines](https://github.com/istio/community/blob/master/CONTRIBUTING.md). -* [Editing and testing content](#editing-and-testing-content) -* [Linting](#linting) -* [Site infrastructure](#site-infrastructure) +* [Editing and building](#editing-and-building) * [Versions and releases](#versions-and-releases) * [How versioning works](#how-versioning-works) * [Publishing content immediately](#publishing-content-immediately) * [Creating a version](#creating-a-version) -## Editing and testing content +## Editing and building -We use [Hugo](https://gohugo.io/) to generate our sites. To build and test the site locally, we use a docker -image that contains Hugo. To build and serve the site, simply go to the root of the tree and do: - -```bash -$ make serve -``` - -This will build the site and start a web server hosting the site. You can then connect to the web server -at `http://localhost:1313`. - -To make and serve the site from a remote server, override `ISTIO_SERVE_DOMAIN` as follows with the IP address -or DNS Domain of the server as follows: - -```bash -$ export ISTIO_SERVE_DOMAIN=192.168.7.105 -$ make serve -``` -This will build the site and start a web server hosting the site. You can then connect to the web server -at `http://192.168.7.105:1313`. - -All normal content for the site is located in the `content` directory, as well as in sibling translated -directories such as content_zh. - -## Linting - -We use linters to ensure some base quality to the site's content. We currently -run 3 linters as a precommit requirement: - -* HTML proofing, which ensures all your links are valid along with other checks. - -* Spell checking. - -* Style checking, which makes sure your markdown files comply with our common style rules. - -You can run these linters locally using: - -```bash -$ make gen -$ make lint -``` - -If you get spelling errors, you have three choices to address each: - -* It's a real typo, so fix your markdown. - -* It's a command/field/symbol name, so stick some `backticks` around it. - -* It's really valid, so go add the word to the `.spelling` file at the root of the repo. - -And you can set any value to an environment variable named "INTERNAL_ONLY", then the linter will not check external links. It looks like that: - -```bash -$ make INTERNAL_ONLY=True lint -``` - -## Optimizing - -You can run an SVG optimization tool over all SVG content in the site with: - -```bash -$ make opt -``` - -This will go through all SVG files and rewrite them in place. You can then -commit the resulting changes to the repo. The optimized images should look -identical but can be considerably smaller than the original, thus saving -load time for site visitors. - -Note that this repo is registered with the ImgBot GitHub app, which -ensures we have optimal PNG images in our repo. - -## Site infrastructure - -Here's how things work: - -* Primary site content is in the `content` directory. This is mostly -markdown files which Hugo processes into HTML. - -* Additional site content is in the `static` directory. These are files that -Hugo directly copies to the site without any processing. - -* The `src` directory contains the source material for certain files from the -`static` directory. You use - - ```bash - $ make build - ``` - - to build the material from the `src` directory and refresh what's in the `generated` - directory. +To learn how to edit and build this repo's content, please refer to +[Creating and Editing Pages](https://preliminary.istio.io/about/contribute/creating-and-editing-pages/). ## Versions and releases diff --git a/content/about/contribute/creating-and-editing-pages/index.md b/content/about/contribute/creating-and-editing-pages/index.md index d2a85df94a..1954cfea71 100644 --- a/content/about/contribute/creating-and-editing-pages/index.md +++ b/content/about/contribute/creating-and-editing-pages/index.md @@ -9,7 +9,7 @@ aliases: keywords: [contribute] --- -This page shows how to create and maintain Istio documentation topics. +This page shows how to create, test, and maintain Istio documentation topics. ## Before you begin @@ -641,3 +641,61 @@ aliases: - /faq3 --- {{< /text >}} + +## Building and testing the site + +Once you've edited some content files, you'll want to build the site in order to test +your changes. We use [Hugo](https://gohugo.io/) to generate our sites. To build and test the site locally, we use a Docker +image that contains Hugo. To build and serve the site, simply go to the root of the tree and do: + +{{< text bash >}} +$ make serve +{{< /text >}} + +This will build the site and start a web server hosting the site. You can then connect to the web server +at `http://localhost:1313`. + +To make and serve the site from a remote server, override `ISTIO_SERVE_DOMAIN` as follows with the IP address +or DNS Domain of the server as follows: + +{{< text bash >}} +$ make ISTIO_SERVE_DOMAIN=192.168.7.105 serve +{{< /text >}} + +This will build the site and start a web server hosting the site. You can then connect to the web server +at `http://192.168.7.105:1313`. + +All English content for the site is located in the `content` directory, as well as in sibling translated +directories such as `content_zh`. + +### Linting + +We use linters to ensure some base quality to the site's content. These linters must run without +complaining before you can submit your changes into the repository. The linters check: + +- HTML proofing, which ensures all your links are valid along with other checks. + +- Spell checking. + +- Style checking, which makes sure your markdown files comply with our common style rules. + +You can run these linters locally using: + +{{< text bash >}} +$ make lint +{{< /text >}} + +If you get spelling errors, you have three choices to address each: + +- It's a real typo, so fix your markdown. + +- It's a command/field/symbol name, so stick some `backticks` around it. + +- It's really valid, so go add the word to the `.spelling` file which is at the root of the repo. + +If you're having trouble with the link checker due to poor Internet connectivity, you can set any value to an environment variable named +`INTERNAL_ONLY` to prevent the linter from checking external links: + +{{< text bash >}} +$ make INTERNAL_ONLY=True lint +{{< /text >}}