mirror of https://github.com/istio/istio.io.git
Clean up some of the build procedures a bit. (#3489)
This commit is contained in:
Martin Taillefer
GitHub
parent
9a2eb88dd8
commit
0e1dd164e7
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -265,6 +265,8 @@ learnings
|
|||
LibreSSL
|
||||
lifecycle
|
||||
LightStep
|
||||
linter
|
||||
linters
|
||||
liveness
|
||||
logInfo
|
||||
loopback
|
||||
|
|
|
|||
18
Makefile
18
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
|
||||
|
|
|
|||
98
README.md
98
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 >}}
|
||||
|
|
|
|||
Loading…
Reference in New Issue