Clean up some of the build procedures a bit. (#3489)

.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

.spelling

@@ -265,6 +265,8 @@ learnings
 LibreSSL
 lifecycle
 LightStep
+linter
+linters
 liveness
 logInfo
 loopback

Makefile

@@ -13,19 +13,19 @@ baseurl := "$(URL)"
 endif
 
 build:
-	$(docker) scripts/build_site.sh
+	@$(docker) scripts/build_site.sh
 
-gen:
+gen: build
-	$(docker) scripts/gen_site.sh "" -minify -no_aliases
+	@$(docker) scripts/gen_site.sh "" -minify -no_aliases
 
 opt:
-	$(docker) scripts/opt_site.sh
+	@$(docker) scripts/opt_site.sh
 
-lint:
+lint: build gen
-	$(docker) scripts/lint_site.sh
+	@$(docker) scripts/lint_site.sh
 
-serve:
+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
+	@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

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)
+* [Editing and building](#editing-and-building)
-* [Linting](#linting)
-* [Site infrastructure](#site-infrastructure)
 * [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
+To learn how to edit and build this repo's content, please refer to
-image that contains Hugo. To build and serve the site, simply go to the root of the tree and do:
+[Creating and Editing Pages](https://preliminary.istio.io/about/contribute/creating-and-editing-pages/).
-
-```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.
 
 ## Versions and releases
 

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 >}}