istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

sync new file to /about/contribute (#6620)

This commit is contained in:
helight 2020-02-27 16:56:43 +08:00 committed by GitHub
parent a804d49342
commit ad802b7818
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 1089 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
content/zh/about/contribute/build/index.md Normal file
View File

@ -0,0 +1,91 @@
---
title: Build and serve the website locally
description: Explains how to locally build, test, serve, and preview the website.
weight: 5
keywords: [contribute, serve, Docker, Hugo, build]
---
After making your contribution to our website, ensure the changes
render as you expect. To ensure you can preview your changes locally, we have
tools that let you build and view them easily. We use automated tests to check
the quality of all contributions. Before submitting your changes in a Pull
Request (PR), you should run the tests locally too.
## Before you begin
To guarantee the tests you run locally use the same versions as the tests
running on the Istio Continuous Integration (CI), we provide a Docker image with
all the tools needed, including our site generator: [Hugo](https://gohugo.io/).
To build, test, and preview the site locally, you need to install
[Docker](https://www.docker.com/get-started) on your system.
## Preview your changes
To preview your changes to the site, go to the root of your fork of
`istio/istio.io` and run the following command:
{{< text bash >}}
$ make serve
{{< /text >}}
If your changes have no build errors, the command builds the site and starts a
local web server to host it. To see the local build of the site, go to
`http://localhost:1313` on your web browser.
If you need to make and serve the site from a remote server, you can use
`ISTIO_SERVE_DOMAIN` to provide the IP address or DNS Domain of the server, for
example:
{{< text bash >}}
$ make ISTIO_SERVE_DOMAIN=192.168.7.105 serve
{{< /text >}}
The example builds the site and starts a web server, which hosts the site on the
remote server at the `192.168.7.105` IP address. Like before, you can then
connect to the web server at `http://192.168.7.105:1313`.
### Test your changes
We use linters and tests to ensure a quality baseline for the site's content
through automated checks. These checks must pass without failure for us to
approve your contribution. Make sure you run the checks locally before you
submit your changes to the repository through a PR. We perform the following
automated checks:
- HTML proofing: ensures all links are valid along with other checks.
- Spell check: ensures content is spelled correctly.
- Markdown Style check: ensures the markup used complies with our Markdown style
rules.
To run these checks locally, use the following command:
{{< text bash >}}
$ make lint
{{< /text >}}
If the spell checker reports errors, the following are the most likely causes:
- A real typo: Fix the typo on your Markdown files.
- The error is reported for a command, field, or symbol name: Place
\`back-ticks\` around the content with the error.
- The error is reported for a correct word or proper name not present in the
tool's dictionary: Add the word to the `.spelling` file at the root of the
`istio/istio.io` repository.
Due to poor Internet connectivity, you could have trouble with the link checker.
If you can't get good connectivity, you can set the checker to prevent it from
checking external links. Set the `INTERNAL_ONLY` environment variable to `True`
when running the linter, for example:
{{< text bash >}}
$ make INTERNAL_ONLY=True lint
{{< /text >}}
When your content passes all the checks, submit it to the repository through a
PR. Visit [Working with GitHub](/about/contribute/github) for more
information.

336
content/zh/about/contribute/code-blocks/index.md Normal file
View File

@ -0,0 +1,336 @@
---
title: Add Code Blocks
description: Explains how to include code in your documentation.
weight: 7
keywords: [contribute, documentation, guide, code-block]
---
Code blocks in the Istio documentation are embedded preformatted block of
content. We use Hugo to build our website, and it uses the `text` and
`text_import` shortcodes to add code to a page.
Using this markup allows us to provide our readers with a better experience.
The rendered code blocks can be easily copied, printed, or downloaded.
Use of these shortcodes is required for all content contributions. If your
content doesn't use the appropriate shortcodes, it won't be merged until it
does. This page contains several examples of embedded blocks and the formatting
options available.
The most common example of code blocks are Command Line Interface (CLI)
commands, for example:
{{< text markdown >}}
{{</* text bash */>}}
$ echo "Hello"
{{</* /text */>}}
{{< /text >}}
The shortcode requires you to start each CLI command with a `$` and it renders the
content as follows:
{{< text bash >}}
$ echo "Hello"
{{< /text >}}
You can have multiple commands in a code block, but the shortcode only
recognizes a single output, for example:
{{< text markdown >}}
{{</* text bash */>}}
$ echo "Hello" >file.txt
$ cat file.txt
Hello
{{</* /text */>}}
{{< /text >}}
By default and given the set `bash` attribute, the commands render using bash
syntax highlighting and the output renders as plain text, for example:
{{< text bash >}}
$ echo "Hello" >file.txt
$ cat file.txt
Hello
{{< /text >}}
For readability, you can use `\` to continue long commands on new lines, for example:
{{< text markdown >}}
{{</* text bash */>}}
$ echo "Hello" \
>file.txt
$ echo "There" >>file.txt
$ cat file.txt
Hello
There
{{</* /text */>}}
{{< /text >}}
Hugo renders the multi-line command without issue:
{{< text bash >}}
$ echo "Hello" \
>file.txt
$ echo "There" >>file.txt
$ cat file.txt
Hello
There
{{< /text >}}
Your {{<gloss workload>}}workloads{{</gloss>}} can be coded in various
programming languages. Therefore, we have implemented support for multiple
combinations of syntax highlighting in code blocks.
## Add syntax highlighting
Let's start with the following "Hello World" example:
{{< text markdown >}}
{{</* text plain */>}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{</* /text */>}}
{{< /text >}}
The `plain` attribute renders the code without syntax highlighting:
{{< text plain >}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{< /text >}}
You can set the language of the code in the block to highlight its syntax. The
previous example set the syntax to `plain`, and the rendered code block doesn't
have any syntax highlighting. However, you can set the syntax to GoLang, for
example:
{{< text markdown >}}
{{</* text go */>}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{</* /text */>}}
{{< /text >}}
Then, Hugo adds the appropriate highlighting:
{{< text go >}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{< /text >}}
### Supported syntax
Code blocks in Istio support the following languages with syntax highlighting:
- `plain`
- `markdown`
- `yaml`
- `json`
- `java`
- `javascript`
- `c`
- `cpp`
- `csharp`
- `go`
- `html`
- `protobuf`
- `perl`
- `docker`
- `bash`
By default, the output of CLI commands is considered plain text and renders
without syntax highlighting. If you need to add syntax highlighting to the
output, you can specify the language in the shortcode. In Istio, the most
common examples are YAML or JSON outputs, for example:
{{< text markdown >}}
{{</* text bash json */>}}
$ kubectl -n istio-system logs $(kubectl -n istio-system get pods -l istio-mixer-type=telemetry -o jsonpath='{.items[0].metadata.name}') mixer | grep \"instance\":\"newlog.logentry.istio-system\"
{"level":"warn","ts":"2017-09-21T04:33:31.249Z","instance":"newlog.logentry.istio-system","destination":"details","latency":"6.848ms","responseCode":200,"responseSize":178,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.291Z","instance":"newlog.logentry.istio-system","destination":"ratings","latency":"6.753ms","responseCode":200,"responseSize":48,"source":"reviews","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.263Z","instance":"newlog.logentry.istio-system","destination":"reviews","latency":"39.848ms","responseCode":200,"responseSize":379,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.239Z","instance":"newlog.logentry.istio-system","destination":"productpage","latency":"67.675ms","responseCode":200,"responseSize":5599,"source":"ingress.istio-system.svc.cluster.local","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.233Z","instance":"newlog.logentry.istio-system","destination":"ingress.istio-system.svc.cluster.local","latency":"74.47ms","responseCode":200,"responseSize":5599,"source":"unknown","user":"unknown"}
{{</* /text */>}}
{{< /text >}}
Renders the commands with bash syntax highlighting and the output with the
appropriate JASON syntax highlighting.
{{< text bash json >}}
$ kubectl -n istio-system logs $(kubectl -n istio-system get pods -l istio-mixer-type=telemetry -o jsonpath='{.items[0].metadata.name}') mixer | grep \"instance\":\"newlog.logentry.istio-system\"
{"level":"warn","ts":"2017-09-21T04:33:31.249Z","instance":"newlog.logentry.istio-system","destination":"details","latency":"6.848ms","responseCode":200,"responseSize":178,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.291Z","instance":"newlog.logentry.istio-system","destination":"ratings","latency":"6.753ms","responseCode":200,"responseSize":48,"source":"reviews","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.263Z","instance":"newlog.logentry.istio-system","destination":"reviews","latency":"39.848ms","responseCode":200,"responseSize":379,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.239Z","instance":"newlog.logentry.istio-system","destination":"productpage","latency":"67.675ms","responseCode":200,"responseSize":5599,"source":"ingress.istio-system.svc.cluster.local","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.233Z","instance":"newlog.logentry.istio-system","destination":"ingress.istio-system.svc.cluster.local","latency":"74.47ms","responseCode":200,"responseSize":5599,"source":"unknown","user":"unknown"}
{{< /text >}}
## Dynamically import code into your document
The previous examples show how to format the code in your document.
However, you can use the `text_import` shortcode to import content or
code from a file too. The file can be stored in the documentation repository or
in an external source with Cross-Origin Resource Sharing (CORS) enabled.
### Import code from a file in the `istio.io` repository
Use the `file` attribute to import content from a file in the Istio
documentation repository, for example:
{{< text markdown >}}
{{</* text_import file="test/snippet_example.txt" syntax="plain" */>}}
{{< /text >}}
The example above renders the content in the file as plain text:
{{< text_import file="test/snippet_example.txt" syntax="plain" >}}
Set the language of the content through the `syntax=` field to get the
appropriate syntax highlighting.
### Import code from an external source through a URL
Similarly, you can dynamically import content from the Internet. Use the `url`
attribute to specify the source. The following example imports the same file, but
from a URL:
{{< text markdown >}}
{{</* text_import url="https://raw.githubusercontent.com/istio/istio.io/master/test/snippet_example.txt" syntax="plain" */>}}
{{< /text >}}
As you can see, the content is rendered in the same way as before:
{{< text_import url="https://raw.githubusercontent.com/istio/istio.io/master/test/snippet_example.txt" syntax="plain" >}}
If the file is from a different origin site, CORS should be enabled on that
site. Note the GitHub raw content site (`raw.githubusercontent.com`) may be used
here.
### Import a code snippet from a larger file {#snippets}
Sometimes, you don't need the contents of the entire file. You can control which
parts of the content to render using _named snippets_. Tag the code you want
in the snippet with comments containing the `$snippet SNIPPET_NAME` and
`$endsnippet` tags. The content between the two tags represents the snippet. For
example, take the following file:
{{< text_import file="test/snippet_example.txt" syntax="plain" >}}
The file has three separate snippets: `SNIP1`, `SNIP2`, and `SNIP3`. The
convention is name snippets using all caps. To reference a specific snippet in
your document, set the value of the `snippet` attribute in the shortcode to the
name of the snippet, for example:
{{< text markdown >}}
{{</* text_import file="test/snippet_example.txt" syntax="plain" snippet="SNIP1" */>}}
{{< /text >}}
The resulting code block only includes the code of the `SNIP1` snippet:
{{< text_import file="test/snippet_example.txt" syntax="plain" snippet="SNIP1" >}}
You can use the `syntax` attribute of the `text_import` shortcode to
specify the syntax of the snippet. For snippets containing CLI commands, you can
use the `outputis` attribute to specify the output's syntax.
## Link to files in GitHub {#link-2-files}
Some code blocks need to reference files from [Istio's GitHub repository](https://github.com/istio/istio).
The most common example is referencing YAML configuration files. Instead of
copying the entire contents of the YAML file into your code block, you can
surround the relative path name of the file with `@` symbols. This markup
renders the path should as a link to the file from the current release branch in
GitHub, for example:
{{< text markdown >}}
{{</* text bash */>}}
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
{{</* /text */>}}
{{< /text >}}
The path renders as a link that takes you to the corresponding file:
{{< text bash >}}
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
{{< /text >}}
By default, these links point to the current release branch of the `istio/istio`
repository. For the link to point to a different Istio repository
instead, you can use the `repo` attribute, for example:
{{< text markdown >}}
{{</* text syntax="bash" repo="api" */>}}
$ cat @README.md@
{{</* /text */>}}
{{< /text >}}
The path renders as a link to the `README.md` file of the `istio/api` repository:
{{< text syntax="bash" repo="api" >}}
$ cat @README.md@
{{< /text >}}
Sometimes, your code block uses `@` for something else. You can turn the link
expansion on and off with the `expandlinks` attribute, for example:
{{< text markdown >}}
{{</* text syntax="bash" expandlinks="false" */>}}
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
{{</* /text */>}}
{{< /text >}}
## Advanced features
To use the more advanced features for preformatted content which are described
in the following sections, use the extended form of the `text` sequence
rather than the simplified form shown so far. The expanded form uses normal HTML
attributes:
{{< text markdown >}}
{{</* text syntax="bash" outputis="json" */>}}
$ kubectl -n istio-system logs $(kubectl -n istio-system get pods -l istio-mixer-type=telemetry -o jsonpath='{.items[0].metadata.name}') mixer | grep \"instance\":\"newlog.logentry.istio-system\"
{"level":"warn","ts":"2017-09-21T04:33:31.249Z","instance":"newlog.logentry.istio-system","destination":"details","latency":"6.848ms","responseCode":200,"responseSize":178,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.291Z","instance":"newlog.logentry.istio-system","destination":"ratings","latency":"6.753ms","responseCode":200,"responseSize":48,"source":"reviews","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.263Z","instance":"newlog.logentry.istio-system","destination":"reviews","latency":"39.848ms","responseCode":200,"responseSize":379,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.239Z","instance":"newlog.logentry.istio-system","destination":"productpage","latency":"67.675ms","responseCode":200,"responseSize":5599,"source":"ingress.istio-system.svc.cluster.local","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.233Z","instance":"newlog.logentry.istio-system","destination":"ingress.istio-system.svc.cluster.local","latency":"74.47ms","responseCode":200,"responseSize":5599,"source":"unknown","user":"unknown"}
{{</* /text */>}}
{{< /text >}}
The available attributes are:
| Attribute | Description
|--------------|------------
|`file` | The path of a file to show in the preformatted block.
|`url` | The URL of a document to show in the preformatted block.
|`syntax` | The syntax of the preformatted block.
|`outputis` | When the syntax is `bash`, this specifies the command output's syntax.
|`downloadas` | The default file name used when the user [downloads the preformatted block](#download-name).
|`expandlinks` | Whether or not to expand [GitHub file references](#link-2-files) in the preformatted block.
|`snippet` | The name of the [snippet](#snippets) of content to extract from the preformatted block.
|`repo` | The repository to use for [GitHub links](#link-2-files) embedded in preformatted blocks.
### Download name
You can define the name used when someone chooses to download the code block
with the `downloadas` attribute, for example:
{{< text markdown >}}
{{</* text syntax="go" downloadas="hello.go" */>}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{</* /text */>}}
{{< /text >}}
If you don't specify a download name, Hugo derives one automatically based on
one of the following available possible names:
- The title of the current page for inline content
- The name of the file containing the imported code
- The URL of the source of the imported code

81
content/zh/about/contribute/formatting/index.md Normal file
View File

@ -0,0 +1,81 @@
---
title: Follow Formatting Standards
description: Explains the standard markup used to format Istio documentation.
weight: 9
aliases:
keywords: [contribute]
---
This page shows the formatting standards for the Istio documentation. Istio uses
Markdown to markup the content and Hugo to build the website. To ensure
consistency across our documentation, we have agreed on these formatting standards.
## Don't use capitalization for emphasis
Only use the original capitalization found in the code or configuration files
when referencing those values directly. Use back-ticks \`\` around the
referenced value to make the connection explicit. For example, use
`IstioRoleBinding`, not `Istio Role Binding` or `istio role binding`.
If you are not referencing values or code directly, use normal sentence
capitalization, for example, "The Istio role binding configuration takes place
in a YAML file."
## Use angle brackets for placeholders
Use angle brackets for placeholders in commands or code samples. Tell the reader
what the placeholder represents. For example:
{{< text markdown >}}
1. Display information about a pod:
{{</* text bash */>}}
$ kubectl describe pod <pod-name>
{{</* /text */>}}
Where `<pod-name>` is the name of one of your pods.
{{< /text >}}
## Use **bold** to emphasize user interface elements
|Do | Don't
|------------------|------
|Click **Fork**. | Click "Fork".
|Select **Other**. | Select 'Other'.
## Use _italics_ to emphasize new terms
|Do | Don't
|-------------------------------------------|---
|A _cluster_ is a set of nodes ... | A "cluster" is a set of nodes ...
|These components form the _control plane_. | These components form the **control plane**.
Use the `gloss` shortcode and add glossary entries for new terms.
## Use `back-ticks` around file names, directories, and paths
|Do | Don't
|-------------------------------------|------
|Open the `foo.yaml` file. | Open the foo.yaml file.
|Go to the `/content/en/docs/tasks` directory. | Go to the /content/en/docs/tasks directory.
|Open the `/data/args.yaml` file. | Open the /data/args.yaml file.
## Use `back-ticks` around inline code and commands
|Do | Don't
|----------------------------|------
|The `foo run` command creates a `Deployment`. | The "foo run" command creates a `Deployment`.
|For declarative management, use `foo apply`. | For declarative management, use "foo apply".
Use code-blocks for commands you intend readers to execute. Only use inline code
and commands to mention specific labels, flags, values, functions, objects,
variables, modules, or commands.
## Use `back-ticks` around object field names
|Do | Don't
|-----------------------------------------------------------------|------
|Set the value of the `ports` field in the configuration file. | Set the value of the "ports" field in the configuration file.
|The value of the `rule` field is a `Rule` object. | The value of the "rule" field is a `Rule` object.

134
content/zh/about/contribute/front-matter/index.md Normal file
View File

@ -0,0 +1,134 @@
---
title: Front matter
description: Explains the front matter used in our documentation and the fields available.
weight: 4
keywords: [metadata,navigation,table-of-contents]
---
The front matter is YAML code in between triple-dashed lines at the top of each
file and provides important management options for our content. For example, the
front matter allows us to ensure that existing links continue to work for pages
that are moved or deleted entirely. This page explains the features currently
available for front matters in Istio.
The following example shows a front matter with all the required fields
filled by placeholders:
{{< text yaml >}}
---
title: <title>
description: <description>
weight: <weight>
keywords: [<keyword1>,<keyword2>,...]
aliases:
- <previously-published-at-this-URL>
---
{{< /text >}}
You can copy the example above and replace all the placeholders with the
appropriate values for your page.
## Required front matter fields
The following table shows descriptions for all the **required** fields:
|Field | Description
|-------------------|------------
|`title` | The page's title.
|`description` | A one-line description of the content on the page.
|`weight` | The order of the page relative to the other pages in the directory.
|`keywords` | The keywords on the page. Hugo uses this list to create the links under "See Also".
|`aliases` | Past URLs where the page was published. See [Renaming, moving, or deleting pages](#rename-move-or-delete-pages) below for details on this item
### Rename, move, or delete pages
When you move pages or delete them completely, you must ensure that the existing
links to those pages continue to work. The `aliases` field in the front matter
helps you meet this requirement. Add the path to the page before the move or
deletion to the `aliases` field. Hugo implements automatic redirects from the
old URL to the new URL for our users.
On the _target page_, which is the page where you want users to land, add the `<path>`
of the _original page_ to the front-matter as follows:
{{< text plain >}}
aliases:
- <path>
{{< /text >}}
For example, you could find our FAQ page in the past under `/help/faq`. To help our users find the FAQ page, we moved the page one level up to `/faq/` and changed the front matter as follows:
{{< text plain >}}
---
title: Frequently Asked Questions
description: Questions Asked Frequently.
weight: 12
aliases:
- /help/faq
---
{{< /text >}}
The change above allows any user to access the FAQ when they visit `https://istio.io/faq/` or `https://istio.io/help/faq/`.
Multiple redirects are supported, for example:
{{< text plain >}}
---
title: Frequently Asked Questions
description: Questions Asked Frequently.
weight: 12
aliases:
- /faq
- /faq2
- /faq3
---
{{< /text >}}
## Optional front matter fields
However, Hugo supports many front matter fields and this page only covers those
implemented on istio.io.
The following table shows the most commonly used **optional** fields:
|Field | Description
|-------------------|------------
|`linktitle` | A shorter version of the title that is used for links to the page.
|`subtitle` | A subtitle displayed below the main title.
|`icon` | A path to the image that appears next to the title.
|`draft` | If true, the page is not shown in the site's navigation.
|`skip_byline` | If true, Hugo doesn't show a byline under the main title.
|`skip_seealso` | If true, Hugo doesn't generate a "See also" section for the page.
Some front matter fields control the auto-generated table of contents (ToC).
The following table shows the fields and explains how to use them:
|Field | Description
|--------------------|------------
|`skip_toc` | If true, Hugo doesn't generate a ToC for the page.
|`force_inline_toc` | If true, Hugo inserts an auto-generated ToC in the text instead of in the sidebar to the right.
|`max_toc_level` | Sets the heading levels used in the ToC. Values can go from 2 to 6.
|`remove_toc_prefix` | Hugo removes this string from the beginning of every entry in the ToC
Some front matter fields only apply to so-called _bundle pages_. You can
identify bundle pages because their file names begin with an underscore `_`, for
example `_index.md`. In Istio, we use bundle pages as our section landing pages.
The following table shows the front matter fields pertinent to bundle pages.
|Field | Description
|----------------------|------------
|`skip_list` | If true, Hugo doesn't auto-generate the content tiles of a section page.
|`simple_list` | If true, Hugo uses a simple list for the auto-generated content of a section page.
|`list_below` | If true, Hugo inserts the auto-generated content below the manually-written content.
|`list_by_publishdate` | If true, Hugo sorts the auto-generated content by publication date, instead of by weight.
Similarly, some front matter fields apply specifically to blog posts. The
following table shows those fields:
|Field | Description
|-----------------|------------
|`publishdate` | Date of the post's original publication
|`last_update` | Date when the post last received a major revision
|`attribution` | Optional name of the post's author
|`twitter` | Optional Twitter handle of the post's author
|`target_release` | The release used on this blog. Normally, this value is the current major Istio release at the time the blog is authored or updated.

383
content/zh/about/contribute/shortcodes/index.md Normal file
View File

@ -0,0 +1,383 @@
---
title: Use Shortcodes
description: Explains the shortcodes available and how to use them.
weight: 8
aliases:
- /docs/welcome/contribute/writing-a-new-topic.html
- /docs/reference/contribute/writing-a-new-topic.html
- /about/contribute/writing-a-new-topic.html
- /create
keywords: [contribute]
---
Hugo shortcodes are special placeholders with a certain syntax that you can add
to your content to create dynamic content experiences, such as tabs,
images and icons, links to other pages, and special content layouts.
This page explains the available shortcodes and how to use them for your
content.
## Add images
Place image files in the same directory as the markdown file using them. To make
localization easier and enhance accessibility, the preferred image
format is SVG. The following example shows the shortcode with the required
fields needed to add an image:
{{< text html >}}
{{</* image width="75%" ratio="45.34%"
link="./<image.svg>"
caption="<The caption displayed under the image>"
*/>}}
{{< /text >}}
The `link` and `caption` fields are required, but the shortcode also supports
optional fields, for example:
{{< text html >}}
{{</* image width="75%" ratio="45.34%"
link="./<image.svg>"
alt="<Alternate text used by screen readers and when loading the image fails>"
title="<Text that appears on mouse-over>"
caption="<The caption displayed under the image>"
*/>}}
{{< /text >}}
If you don't include the `title` field, Hugo uses the text set in `caption`. If
you don't include the `alt` field, Hugo uses the text in `title` or in `caption`
if `title` is also not defined.
The `width` field sets the size of the image relative to the surrounding text and
has a default of 100%.
The `ratio` field sets the height of the image relative to its width. Hugo
calculates this value automatically for image files in the folder.
However, you must calculate it manually for external images.
Set the value of `ratio` to `([image height]/[image width]) * 100`.
## Add icons
You can embed common icons in your content with the following content:
{{< text markdown >}}
{{</* warning_icon */>}}
{{</* idea_icon */>}}
{{</* checkmark_icon */>}}
{{</* cancel_icon */>}}
{{</* tip_icon */>}}
{{< /text >}}
The icons are rendered within the text. For example: {{< warning_icon >}},
{{< idea_icon >}}, {{< checkmark_icon >}}, {{< cancel_icon >}} and {{< tip_icon >}}.
## Add links to other pages
The Istio documentation supports three types of links depending on their target.
Each type uses a different syntax to express the target.
- **External links**. These are links to pages outside of the Istio
documentation or the Istio GitHub repositories. Use the standard Markdown
syntax to include the URL. Use the HTTPS protocol, when you reference files
on the Internet, for example:
{{< text markdown >}}
[Descriptive text for the link](https://mysite/myfile.html)
{{< /text >}}
- **Relative links**. These links target pages at the same level of the current
file or further down the hierarchy. Start the path of relative links with a
period `.`, for example:
{{< text markdown >}}
[This links to a sibling or child page](./sub-dir/child-page.html)
{{< /text >}}
- **Absolute links**. These links target pages outside the hierarchy of the
current page but within the Istio website. Start the path of absolute links
with a slash `/`, for example:
{{< text markdown >}}
[This links to a page on the about section](/about/page/)
{{< /text >}}
Regardless of type, links do not point to the `index.md` file with the content,
but to the folder containing it.
### Add links to content on GitHub
There are a few ways to reference content or files on GitHub:
- **{{</* github_file */>}}** is how you reference individual files in GitHub
such as yaml files. This shortcode produces a link to
`https://raw.githubusercontent.com/istio/istio*`, for example:
{{< text markdown >}}
[liveness]({{</* github_file */>}}/samples/health-check/liveness-command.yaml)
{{< /text >}}
- **{{</* github_tree */>}}** is how you reference a directory tree in GitHub.
This shortcode produces a link to `https://github.com/istio/istio/tree*`, for example:
{{< text markdown >}}
[httpbin]({{</* github_tree */>}}/samples/httpbin)
{{< /text >}}
- **{{</* github_blob */>}}** is how you reference a file in GitHub sources.
This shortcode produces a link to `https://github.com/istio/istio/blob*`, for example:
{{< text markdown >}}
[RawVM MySQL]({{</* github_blob */>}}/samples/rawvm/README.md)
{{< /text >}}
The shortcodes above produce links to the appropriate branch in GitHub, based on
the branch the documentation is currently targeting. To verify which branch
is currently targeted, you can use the `{{</* source_branch_name */>}}`
shortcode to get the name of the currently targeted branch.
## Version information
To display the current Istio version in your content by retrieving the current
version from the web site, use the following shortcodes:
- `{{</* istio_version */>}}`, which renders as {{< istio_version >}}
- `{{</* istio_full_version */>}}`, which renders as {{< istio_full_version >}}
## Glossary terms
When you introduce a specialized Istio term in a page, the supplemental
acceptance criteria for contributions require you include the term in the
glossary and markup its first instance using the `{{</* gloss */>}}` shortcode.
The shortcode produces a special rendering that invites readers to click on the
term to get a pop-up with the definition. For example:
{{< text markdown >}}
Mixer uses {{</*gloss*/>}}adapters{{</*/gloss*/>}} to interface to backends.
{{< /text >}}
Is rendered as follows:
Mixer uses {{< gloss >}}adapters{{< /gloss >}} to interface to backends.
If you use a variant of the term in your text, you can still use this shortcode
to include the pop up with the definition. To specify a substitution, just
include the glossary entry within the shortcode. For example:
{{< text markdown >}}
Mixer uses an {{</*gloss adapters*/>}}adapter{{</*/gloss*/>}} to interface to a backend.
{{< /text >}}
Renders with the pop up for the `adapters` glossary entry as follows:
Mixer uses an {{< gloss adapters >}}adapter{{</ gloss >}} to interface to a backend.
## Callouts
To emphasize blocks of content, you can format them as warnings, ideas, tips, or
quotes. All callouts use very similar shortcodes:
{{< text markdown >}}
{{</* warning */>}}
This is an important warning
{{</* /warning */>}}
{{</* idea */>}}
This is a great idea
{{</* /idea */>}}
{{</* tip */>}}
This is a useful tip from an expert
{{</* /tip */>}}
{{</* quote */>}}
This is a quote from somewhere
{{</* /quote */>}}
{{< /text >}}
The shortcodes above render as follows:
{{< warning >}}
This is an important warning
{{< /warning >}}
{{< idea >}}
This is a great idea
{{< /idea >}}
{{< tip >}}
This is a useful tip from an expert
{{< /tip >}}
{{< quote >}}
This is a quote from somewhere
{{< /quote >}}
Use callouts sparingly. Each type of callout serves a specific purpose and
over-using them negates their intended purposes and their efficacy. Generally,
you should not include more than one callout per content file.
## Use boilerplate text
To reuse content while maintaining a single source for it, use boilerplate shortcodes. To embed
boilerplate text into any content file, use the `boilerplate` shortcode as follows:
{{< text markdown >}}
{{</* boilerplate example */>}}
{{< /text >}}
The shortcode above includes the following content from the `example.md`
Markdown file in the `/content/en/boilerplates/` folder:
{{< boilerplate example >}}
The example shows that you need to include the filename of the Markdown file
with the content you wish to insert at the current location. You can find the existing
boilerplate files are located in the `/content/en/boilerplates` directory.
## Use tabs
To display content that has multiple options or formats, use tab sets
and tabs. For example:
- Equivalent commands for different platforms
- Equivalent code samples in different languages
- Alternative configurations
To insert tabbed content, combine the `tabset` and `tabs` shortcodes,
for example:
{{< text markdown >}}
{{</* tabset category-name="platform" */>}}
{{</* tab name="One" category-value="one" */>}}
ONE
{{</* /tab */>}}
{{</* tab name="Two" category-value="two" */>}}
TWO
{{</* /tab */>}}
{{</* tab name="Three" category-value="three" */>}}
THREE
{{</* /tab */>}}
{{</* /tabset */>}}
{{< /text >}}
The shortcodes above produce the following output:
{{< tabset category-name="platform" >}}
{{< tab name="One" category-value="one" >}}
ONE
{{< /tab >}}
{{< tab name="Two" category-value="two" >}}
TWO
{{< /tab >}}
{{< tab name="Three" category-value="three" >}}
THREE
{{< /tab >}}
{{< /tabset >}}
The value of the `name` attribute of each tab contains the text displayed for
the tab. Within each tab, you can have normal Markdown content, but tabs have [limitations](#tab-limitations).
The `category-name` and `category-value` attributes are optional and make the
selected tab to stick across visits to the page. For example, a visitor selects
a tab and their selection is saved automatically with the given name and value. If
multiple tab sets use the same category name and values, their selection is
automatically synchronized across pages. This is particularly useful when there
are many tab sets in the site that hold the same types of formats.
For example, multiple tab sets could provide options for `GCP`,
`BlueMix` and `AWS`. You can set the value of the `category-name` attribute to `environment` and
the values for the `category-value` attributes to `gcp`, `bluemix`, and `aws`.
Then, when a reader selects a tab in one page, their choice will carry
throughout all tab sets across the website automatically.
### Tab limitations
You can use almost any Markdown in a tab, with the following exceptions:
- *Headers*. Headers in a tab appear in the table of contents but
clicking on the link in the table of contents won't automatically select
the tab.
- *Nested tab sets*. Don't nest tab sets. Doing so leads to a terrible reading
experience and can cause significant confusion.
## Use banners and stickers
To advertise upcoming events, or publicize something
new, you can automatically insert time-sensitive banners and stickers into the
generated site in order. We've implemented the following shortcodes for promotions:
- **Countdown stickers**: They show how much time is left before a big event
For example: "37 days left until ServiceMeshCon on March 30". Stickers have some visual
impact for readers prior to the event and should be used sparingly.
- **Banners**: They show a prominent message to readers about a
significant event that is about to take place, is taking place, or has taken place.
For example "Istio 1.5 has been released, download it today!" or "Join us at ServiceMeshCon
on March 30". Banners are full-screen slices displayed to readers during the
event period.
To create banners and stickers, you create Markdown files in either the
`events/banners` or `events/stickers` folders. Create one Markdown file
per event with dedicated front-matter fields to control their behavior. The
following table explains the available options:
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>title</code></td>
<td>The name of the event. This is not displayed on the web site, it's intended for diagnostic messages.</td>
</tr>
<tr>
<td><code>period_start</code></td>
<td>The starting date at which to start displaying the item in <code>YYYY-MM-DD</code> format.
Instead of a date, this can also be the value <code>latest_release</code>, which then uses the latest known
Istio release as the start date. This is useful when creating a banner saying "Istio x.y.z has just been released".
</td>
</tr>
<tr>
<td><code>period_end</code></td>
<td>The last date on which to display the item in <code>YYYY-MM-DD</code> format. This value is mutually
exclusive with <code>period_duration</code> below.
</td>
</tr>
<tr>
<td><code>period_duration</code></td>
<td>How many days to display the item to the user. This value is mutually exclusive with
<code>period_end</code> above.
</td>
</tr>
<tr>
<td><code>max_impressions</code></td>
<td>How many times to show the content to the user during
the event's period. A value of 3 would mean the first three pages visited by the user during the period will display
the content, and the content will be hidden on subsequent page loads. A value of 0, or omitting the field completely,
results in the content being displayed on all page visits during the period.
</td>
</tr>
<tr>
<td><code>timeout</code></td>
<td>The amount of time the content is visible to the user on a given page. After that much time passes, the item will be removed from the page.</td>
</tr>
<tr>
<td><code>link</code></td>
<td>You can specify a URL, which turns the whole item into a clickable target. When the user clicks on the item,
the item is no longer shown to the user. The special value `latest_release` can be used here to introduce a link
to the current release's announcement page.
</td>
</tr>
</tbody>
</table>

64
content/zh/about/contribute/terminology/index.md Normal file
View File

@ -0,0 +1,64 @@
---
title: Terminology Standards
description: Explains the terminology standards used in the Istio documentation.
weight: 11
aliases:
- /docs/welcome/contribute/style-guide.html
- /docs/reference/contribute/style-guide.html
keywords: [contribute, documentation, guide, code-block]
---
To provide clarity to our users, use the standard terms in this section
consistently within the documentation.
## Service
Avoid using the term **service**. Research shows that different folks understand
different things under that term. The following table shows acceptable
alternatives that provide greater specificity and clarity to readers:
|Do | Don't
|--------------------------------------------|-----------------------------------------
| Workload A sends a request to Workload B. | Service A sends a request to Service B.
| New workload instances start when ... | New service instances start when ...
| The application consists of two workloads. | The service consists of two services.
Our glossary establishes the agreed-upon terminology, and provides definitions to
avoid confusion.
## Envoy
We prefer to use "Envoy” as it’s a more concrete term than "proxy" and
resonates if used consistently throughout the docs.
Synonyms:
- "Envoy sidecar” - ok
- "Envoy proxy” - ok
- "The Istio proxy” -- best to avoid unless you’re talking about advanced
scenarios where another proxy might be used.
- "Sidecar” -- mostly restricted to conceptual docs
- "Proxy" -- only if context is obvious
Related Terms:
- Proxy agent - This is a minor infrastructural component and should only show
up in low-level detail documentation. It is not a proper noun.
## Miscellaneous
|Do | Don't
|----------------|------
| addon | `add-on`
| Bookinfo | `BookInfo`, `bookinfo`
| certificate | `cert`
| colocate | `co-locate`
| configuration | `config`
| delete | `kill`
| Kubernetes | `kubernetes`, `k8s`
| load balancing | `load-balancing`
| Mixer | `mixer`
| multicluster | `multi-cluster`
| mutual TLS | `mtls`
| service mesh | `Service Mesh`
| sidecar | `side-car`, `Sidecar`