mirror of https://github.com/istio/istio.io.git
Rewrite contribution guides to empower reviewers (#6358)
* Rewrite contribution guides to empower reviewers This rewrite includes the following changes: - Implement the new reviewer role. - Restructure the contribution guides into multiple smaller pages to make them easier to reference. - Added separate pages for adding new content and reviewing content. - Added clarifying text for the implemented shortcodes and processes. - Updated all links. - Added color-coded flow chart of the review process. Signed-off-by: rcaballeromx <grca@google.com> * Add content to help identify audience needs. Addressed typos, consistency improvements, and other small fixes. Added a mention and link to our code of conduct to the review process. Signed-off-by: rcaballeromx <grca@google.com>
This commit is contained in:
Rigs Caballero
GitHub
parent
29698c40c5
commit
dc65d56094
|
|
@ -115,8 +115,8 @@ Brooks
|
|||
bt
|
||||
Budinsky
|
||||
c.f.
|
||||
callout
|
||||
callouts
|
||||
Callouts
|
||||
camelCase
|
||||
canaried
|
||||
canarying
|
||||
|
|
@ -245,6 +245,7 @@ GKE-Istio
|
|||
GKE-Workloads
|
||||
GlueCon
|
||||
Gmail
|
||||
GoLang
|
||||
googleapis.com
|
||||
googlegroups.com
|
||||
Grafana
|
||||
|
|
@ -327,6 +328,7 @@ Kube
|
|||
kubebuilder
|
||||
KubeCon
|
||||
kubeconfig
|
||||
kubectl
|
||||
Kubelet
|
||||
kubelet
|
||||
Kubernetes
|
||||
|
|
@ -472,6 +474,7 @@ reimplemented
|
|||
reinject
|
||||
repurposed
|
||||
rethink
|
||||
reusability
|
||||
Reviewer1
|
||||
Reviewer2
|
||||
roadmap
|
||||
|
|
@ -502,12 +505,15 @@ sha256
|
|||
sharded
|
||||
Sharding
|
||||
sharding
|
||||
shortcode
|
||||
shortcodes
|
||||
Shriram
|
||||
sidecar
|
||||
sidecar.env
|
||||
SignalFX
|
||||
sinkInfo
|
||||
SLOs
|
||||
SMEs
|
||||
Snell-Feikema
|
||||
SNI
|
||||
SolarWinds
|
||||
|
|
@ -551,6 +557,7 @@ timeframe
|
|||
timestamp
|
||||
TLS
|
||||
TLS-secured
|
||||
ToC
|
||||
touchpoints
|
||||
Trulia
|
||||
trustability
|
||||
|
|
|
|||
|
|
@ -1,8 +1,28 @@
|
|||
---
|
||||
title: Contributing to the Docs
|
||||
description: Learn how to contribute to improve and expand the Istio documentation.
|
||||
weight: 100
|
||||
title: Contribute Documentation to Istio
|
||||
description: Details how to create and maintain documentation pages.
|
||||
weight: 1
|
||||
aliases:
|
||||
- /docs/welcome/contribute/writing-a-new-topic.html
|
||||
- /docs/welcome/contribute/index.html
|
||||
- /docs/reference/contribute/writing-a-new-topic.html
|
||||
- /about/contribute/writing-a-new-topic.html
|
||||
- /about/contribute/creating-and-editing-pages
|
||||
- /create
|
||||
keywords: [contribute, github, docs, shortcodes, code-blocks, website]
|
||||
list_below: true
|
||||
icon: contribute
|
||||
---
|
||||
|
||||
Welcome to the Istio documentation contribution guides. This section contains
|
||||
all the information you need to contribute documentation, blog posts, and other
|
||||
[content types](/about/contribute/add-content/#content-types).
|
||||
|
||||
The Istio content is multilingual. Within the `content` folder, you can
|
||||
find the following folders for the available languages:
|
||||
|
||||
- The English original content is in the `en` folder.
|
||||
- The Mandarin translation is in the `zh` folder.
|
||||
- The Portuguese translation is in the `pt-br` folder.
|
||||
|
||||
Learn more in the following guides:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,179 @@
|
|||
---
|
||||
title: Add New Documentation
|
||||
description: Details how to contribute new documentation to Istio.
|
||||
weight: 3
|
||||
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]
|
||||
---
|
||||
|
||||
To contribute new documentation to Istio, just follow these steps:
|
||||
|
||||
1. Identify the audience and intended use for the information.
|
||||
1. Choose the [type of content](#content-types) you wish to contribute.
|
||||
1. [Choose a title](#choosing-a-title).
|
||||
1. Write your contribution following our [documentation contribution guides](/about/contribute).
|
||||
1. Submit your contribution to our [GitHub repository](https://github.com/istio/istio.io).
|
||||
1. Follow our [review process](/about/contribute/review) until your contribution
|
||||
is merged.
|
||||
|
||||
## Identify the audience and intended use
|
||||
|
||||
The best documentation starts by knowing the intended readers, their knowledge,
|
||||
and what you expect them to do with the information. Otherwise, you cannot
|
||||
determine the appropriate scope and depth of information to provide, its ideal
|
||||
structure, or the necessary supporting information. The following examples show
|
||||
this principle in action:
|
||||
|
||||
- The reader needs to perform a specific task: Tell them how to recognize when
|
||||
the task is necessary and provide the task itself as a list of numbered steps,
|
||||
don’t simply describe the task in general terms.
|
||||
|
||||
- The reader must understand a concept before they can perform a task: Before
|
||||
the task, tell them about the prerequisite information and provide a link to
|
||||
it.
|
||||
|
||||
- The reader needs to make a decision: Provide the conceptual information
|
||||
necessary to know when to make the decision, the available options, and when
|
||||
to choose one option instead of the other.
|
||||
|
||||
- The reader is an administrator but not a SWE: Provide a script,
|
||||
not a link to a code sample in a developer’s guide.
|
||||
|
||||
- The reader needs to extend the features of the product: Provide an example of
|
||||
how to extend the feature, using a simplified scenario for illustration
|
||||
purposes.
|
||||
|
||||
- The reader needs to understand complex feature relationships: Provide a
|
||||
diagram showing the relationships, rather than writing multiple pages of
|
||||
content that is tedious to read and understand.
|
||||
|
||||
The most important thing to avoid is the common mistake of simply
|
||||
giving readers all the information you have, because you are unsure about
|
||||
what information they need.
|
||||
|
||||
If you need help identifying the audience for you content, we are happy to help
|
||||
and answer all your questions during the [Docs Working Group](https://github.com/istio/community/blob/master/WORKING-GROUPS.md#istio-working-groups)
|
||||
biweekly meetings.
|
||||
|
||||
## Content types
|
||||
|
||||
When you understand the audience and the intended use for the information you
|
||||
provide, you can choose content type that best addresses their needs. To make it
|
||||
easy for you to choose, the following table shows the supported content types,
|
||||
their intended audiences, and the goals each type strives to achieve:
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Content type</th>
|
||||
<th>Goals</th>
|
||||
<th>Audiences</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tr>
|
||||
<td>Concepts</td>
|
||||
<td>Explain some significant aspect of Istio. For example, a concept page
|
||||
describes the configuration model of a feature and explains its functionality.
|
||||
Concept pages don't include sequences of steps. Instead, provide links to
|
||||
corresponding tasks.</td>
|
||||
<td>Readers that want to understand how features work with only basic
|
||||
knowledge of the project.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Reference pages</td>
|
||||
<td>Provide exhaustive and detailed technical information. Common examples
|
||||
include API parameters, command-line options, configuration settings, and
|
||||
advanced procedures. Reference content is generated from the Istio code
|
||||
base and tested for accuracy.
|
||||
</td>
|
||||
<td>Readers with advanced and deep technical knowledge of the project that
|
||||
needs specific bits of information to complete advanced tasks.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Examples</td>
|
||||
<td>Describe a working and stand-alone example that highlights a set of
|
||||
features, an integration of Istio with other projects, or an end-to-end
|
||||
solution for a use case. Examples must use an existing Istio setup as a
|
||||
starting point. Examples must include an automated test since they are maintained for technical accuracy.
|
||||
</td>
|
||||
<td>Readers that want to quickly run the example themselves and
|
||||
experiment. Ideally, readers should be able to easily change the example
|
||||
to produce their own solutions.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Tasks</td>
|
||||
<td>Shows how to achieve a single goal using Istio features. Tasks contain procedures written
|
||||
as a sequence of steps. Tasks provide minimal
|
||||
explanation of the features, but include links to the concepts that
|
||||
provide the related background and knowledge. Tasks must include automated
|
||||
tests since they are tested and maintained for technical accuracy.</td>
|
||||
<td>Readers that want to use Istio features.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Setup pages</td>
|
||||
<td>Focus on the installation steps needed to complete an Istio
|
||||
deployment. Setup pages must include automated tests since they are tested and maintained for technical accuracy.
|
||||
</td>
|
||||
<td>New and existing Istio users that want to complete a deployment.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Blog posts</td>
|
||||
<td>
|
||||
Focus on Istio or products and technologies related to it. Blog posts fall in one of the following three categories:
|
||||
<ul>
|
||||
<li>Posts detailing the author’s experience using and configuring Istio, especially those that articulate a novel experience or perspective.</li>
|
||||
<li>Posts highlighting Istio features.</li>
|
||||
<li>Posts detailing how to accomplish a task or fulfill a specific use case using Istio. Unlike Tasks and Examples, the technical accuracy of blog posts is not maintained and tested after publication.</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td>Readers with a basic understanding of the project who want to learn
|
||||
about it in an anecdotal, experiential, and more informal way.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>News entries</td>
|
||||
<td>
|
||||
Focus on timely information about Istio and related events. News entries typically announce new releases or upcoming events.
|
||||
</td>
|
||||
<td>Readers that want to quickly learn what's new and what's happening in
|
||||
the Istio community.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FAQ entries</td>
|
||||
<td>
|
||||
Provide quick answers to common questions. Answers don't introduce any
|
||||
concepts. Instead, they provide practical advice or insights. Answers
|
||||
must link to tasks, concepts, or examples in the documentation for readers to learn more.
|
||||
</td>
|
||||
<td>Readers with specific questions who are looking for brief answers and
|
||||
resources to learn more.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Operation guides</td>
|
||||
<td>
|
||||
Focus on practical solutions that address specific problems encountered while running Istio in a real-world setting.
|
||||
</td>
|
||||
<td>Service mesh operators that want to fix problems or implement
|
||||
solutions for running Istio deployments.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Choosing a title
|
||||
|
||||
Choose a title for your topic that has the keywords you want search engines to
|
||||
find. All content files in Istio are named `index.md`, but each content file is
|
||||
within a folder that uses the keywords in the topic's title,
|
||||
separated by hyphens, all in lowercase. Keep folder names as short as possible
|
||||
to make cross-references easier to create and maintain.
|
||||
|
||||
## Submit your contribution to GitHub
|
||||
|
||||
If you are not familiar with GitHub, see our [working with GitHub guide](/about/contribute/github)
|
||||
to learn how to submit documentation changes.
|
||||
|
||||
If you want to learn more about how and when your contributions are published,
|
||||
see the [section on branching](/about/contribute/github#branching-strategy) to understand
|
||||
how we use branches and cherry picking to publish our content.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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="operator" */>}}
|
||||
$ cat @README.md@
|
||||
{{</* /text */>}}
|
||||
{{< /text >}}
|
||||
|
||||
The path renders as a link to the `README.md` file of the `istio/operator` repository:
|
||||
|
||||
{{< text syntax="bash" repo="operator" >}}
|
||||
$ 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
|
||||
|
|
@ -1,860 +0,0 @@
|
|||
---
|
||||
title: Creating and Editing Pages
|
||||
description: Explains the mechanics of creating and maintaining documentation pages.
|
||||
weight: 10
|
||||
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]
|
||||
---
|
||||
|
||||
This page shows how to create, test, and maintain Istio documentation topics.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you can work on Istio documentation, you first need to create a fork of the Istio documentation repository as described in
|
||||
[Working with GitHub](/about/contribute/github/).
|
||||
|
||||
## Choosing a page type
|
||||
|
||||
As you prepare to write a new topic, think about which of these page types
|
||||
is the best fit for your content:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>Concept</td>
|
||||
<td>A concept page explains some significant aspect of Istio. For example, a concept page might describe the
|
||||
Mixer's configuration model and explain some of its subtleties.
|
||||
Typically, concept pages don't include sequences of steps, but instead provide links to
|
||||
tasks that do.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Reference</td>
|
||||
<td>A reference page provides exhaustive lists of things like API parameters,
|
||||
command-line options, configuration settings, and procedures.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Examples</td>
|
||||
<td>An example page describes a fully working stand-alone example highlighting a particular set of features. Examples
|
||||
must have easy to follow setup and usage instructions so users can quickly run the sample
|
||||
themselves and experiment with changing the example to explore the system. Examples are tested and maintained for technical accuracy.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Task</td>
|
||||
<td>A task page shows how to do a single thing, typically by giving a short sequence of steps. Task pages have minimal
|
||||
explanation, but often provide links to conceptual topics that provide related background and knowledge. Tasks are tested and maintained for technical accuracy.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Setup</td>
|
||||
<td>A setup page is similar to a task page, except that it is focused on installation
|
||||
activities. Setup pages are tested and maintained for technical accuracy.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Blog Post</td>
|
||||
<td>
|
||||
A blog post is an article on Istio or products and technologies related to it. Typically, posts fall in one of the following three categories:
|
||||
<ul>
|
||||
<li>Posts detailing the author’s experience using and configuring Istio, especially those that articulate a novel experience or perspective.</li>
|
||||
<li>Posts highlighting Istio features.</li>
|
||||
<li>Posts detailing how to accomplish a task or fulfill a specific use case using Istio. Unlike Tasks and Examples, the technical accuracy of blog posts is not maintained and tested after publication.</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>News Entry</td>
|
||||
<td>
|
||||
A news entry post is a timely article on Istio and events related to it. News entries typically announce new releases or upcoming events.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>FAQ</td>
|
||||
<td>
|
||||
A FAQ entry is for quick answers to common customer questions. An answer doesn't normally introduce any new
|
||||
concept and is instead narrowly focused on some practical bit of advice or insight, with links back into the
|
||||
main documentation for the user to learn more.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Ops Guide</td>
|
||||
<td>
|
||||
For practical solutions to address specific problems encountered while running Istio in a real-world setting.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Naming a topic
|
||||
|
||||
Choose a title for your topic that has the keywords you want search engines to find.
|
||||
Create a filename for your topic that uses the words in your title, separated by hyphens,
|
||||
all in lower case.
|
||||
|
||||
## Updating front matter
|
||||
|
||||
Every documentation file needs to start with
|
||||
[front matter](https://gohugo.io/content-management/front-matter/).
|
||||
The front matter is a block of YAML that is between
|
||||
triple-dashed lines at the top of each file. Here's the
|
||||
chunk of front matter you should start with:
|
||||
|
||||
{{< text yaml >}}
|
||||
---
|
||||
title: <title>
|
||||
description: <description>
|
||||
weight: <weight>
|
||||
keywords: [keyword1,keyword2,...]
|
||||
---
|
||||
{{< /text >}}
|
||||
|
||||
Copy the above at the start of your new markdown file and update the information fields.
|
||||
The available front matter fields are:
|
||||
|
||||
|Field | Description
|
||||
|-------------------|------------
|
||||
|`title` | The short title of the page
|
||||
|`linktitle` | An alternate, typically shorter, title for the page which is used in the side bar to reference the page
|
||||
|`subtitle` | An optional subtitle which gets displayed below the main title
|
||||
|`description` | A one-line description of what the page is about
|
||||
|`icon` | An optional path to an image file which gets displayed next to the main title
|
||||
|`weight` | An integer used to determine the sort order of this page relative to other pages in the same directory
|
||||
|`keywords` | An array of keywords describing the page, used to create the web of See Also links
|
||||
|`draft` | When true, prevents the page from showing up in any navigation area
|
||||
|`aliases` | See [Renaming, moving, or deleting pages](#renaming-moving-or-deleting-pages) below for details on this item
|
||||
|`skip_byline` | Set this to true to prevent the page from having a byline under the main title
|
||||
|`skip_seealso` | Set this to true to prevent the page from having a "See also" section generated for it
|
||||
|
||||
A few fields control the auto-generated table of contents present on most pages:
|
||||
|
||||
|Field | Description
|
||||
|--------------------|------------
|
||||
|`skip_toc` | Set this to true to prevent the page from having a table of contents generated for it
|
||||
|`force_inline_toc` | Set this to true to force the generated table of contents to be inserted inline in the text instead of in a sidebar
|
||||
|`max_toc_level` | Set to 2, 3, 4, 5, or 6 to indicate the maximum heading level to show in the table of contents
|
||||
|`remove_toc_prefix` | Set this to a string that will be removed from the start of every entry in the table of contents if present
|
||||
|
||||
A few front-matter fields are specific to section pages (i.e. for files names `_index.md`):
|
||||
|
||||
|Field | Description
|
||||
|----------------------|------------
|
||||
|`skip_list` | Set this to true to prevent the auto-generated content on a section page
|
||||
|`simple_list` | Set this to true to use a simple list layout rather than gallery layout for the auto-generated content of a section page
|
||||
|`list_below` | Set this to true to insert the auto-generated content on a section page below the manually-written content
|
||||
|`list_by_publishdate` | Set this to true to sort the generated content on the page in order in publication date, rather than by page weight
|
||||
|
||||
There are a few more front matter fields available specifically for blog posts:
|
||||
|
||||
|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` | Release this blog is written with in mind (this is normally the current major Istio release at the time the blog is authored or updated)
|
||||
|
||||
## Adding images
|
||||
|
||||
Put image files in the same directory as your markdown file. The preferred image format is SVG.
|
||||
Within markdown, use the following sequence to add the image:
|
||||
|
||||
{{< text html >}}
|
||||
{{</* image width="75%" ratio="45.34%"
|
||||
link="./myfile.svg"
|
||||
alt="Alternate text to display when the image can't be loaded"
|
||||
title="A tooltip displayed when hovering over the image"
|
||||
caption="A caption displayed under the image"
|
||||
*/>}}
|
||||
{{< /text >}}
|
||||
|
||||
The `link` and `caption` values are required, all other values are optional.
|
||||
|
||||
If the `title` value isn't supplied, it'll default to the same as `caption`. If the `alt` value is not supplied, it'll
|
||||
default to `title` or if that's not defined, to `caption`.
|
||||
|
||||
`width` represents the percentage of space used by the image
|
||||
relative to the surrounding text. If the value is not specified, it
|
||||
defaults to 100%.
|
||||
|
||||
`ratio` represents the ratio of the image height compared to the image width. This
|
||||
value is calculated automatically for any local image content, but must be calculated
|
||||
manually when referencing external image content.
|
||||
In that case, `ratio` should be set to (image height / image width) * 100.
|
||||
|
||||
## Adding icons
|
||||
|
||||
You can embed some common icons in your content using:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* warning_icon */>}}
|
||||
{{</* idea_icon */>}}
|
||||
{{</* checkmark_icon */>}}
|
||||
{{</* cancel_icon */>}}
|
||||
{{</* tip_icon */>}}
|
||||
{{< /text >}}
|
||||
|
||||
which look like {{< warning_icon >}}, {{< idea_icon >}}, {{< checkmark_icon >}}, {{< cancel_icon >}} and {{< tip_icon >}}.
|
||||
|
||||
## Linking to other pages
|
||||
|
||||
There are three types of links that can be included in documentation. Each uses a different
|
||||
way to indicate the link target:
|
||||
|
||||
1. **Internet Link**. You use classic URL syntax, preferably with the HTTPS protocol, to reference
|
||||
files on the Internet:
|
||||
|
||||
{{< text markdown >}}
|
||||
[see here](https://mysite/myfile.html)
|
||||
{{< /text >}}
|
||||
|
||||
1. **Relative Link**. You use relative links that start with a period to
|
||||
reference any content that is at the same level as the current file, or below within
|
||||
the hierarchy of the site:
|
||||
|
||||
{{< text markdown >}}
|
||||
[see here](./adir/anotherfile.html)
|
||||
{{< /text >}}
|
||||
|
||||
1. **Absolute Link**. You use absolute links that start with a `/` to reference content outside of the
|
||||
current hierarchy:
|
||||
|
||||
{{< text markdown >}}
|
||||
[see here](/docs/adir/afile/)
|
||||
{{< /text >}}
|
||||
|
||||
### GitHub
|
||||
|
||||
There are a few ways to reference files from GitHub:
|
||||
|
||||
- **{{</* github_file */>}}** is how you reference individual files in GitHub such as yaml files. This
|
||||
produces a link to `https://raw.githubusercontent.com/istio/istio*`
|
||||
|
||||
{{< text markdown >}}
|
||||
[liveness]({{</* github_file */>}}/samples/health-check/liveness-command.yaml)
|
||||
{{< /text >}}
|
||||
|
||||
- **{{</* github_tree */>}}** is how you reference a directory tree in GitHub. This produces a link to
|
||||
`https://github.com/istio/istio/tree*`
|
||||
|
||||
{{< text markdown >}}
|
||||
[httpbin]({{</* github_tree */>}}/samples/httpbin)
|
||||
{{< /text >}}
|
||||
|
||||
- **{{</* github_blob */>}}** is how you reference a file in GitHub sources. This produces a link to
|
||||
`https://github.com/istio/istio/blob*`
|
||||
|
||||
{{< text markdown >}}
|
||||
[RawVM MySQL]({{</* github_blob */>}}/samples/rawvm/README.md)
|
||||
{{< /text >}}
|
||||
|
||||
The above annotations yield links to the appropriate branch in GitHub, relative to the branch that the
|
||||
documentation is currently targeting. If you need to manually construct a URL, you can use the sequence `{{</* source_branch_name */>}}`
|
||||
to get the name of the currently targeted branch.
|
||||
|
||||
## Version information
|
||||
|
||||
You can obtain the current Istio version described by the web site using either of `{{</* istio_version */>}}` or
|
||||
`{{</* istio_full_version */>}}` which render as {{< istio_version >}} and {{< istio_full_version >}} respectively.
|
||||
|
||||
`{{</* source_branch_name */>}}` gets expanded to the name of the branch of the `istio/istio` GitHub repository that the
|
||||
web site is targeting. This renders as {{< source_branch_name >}}.
|
||||
|
||||
## Embedding preformatted blocks
|
||||
|
||||
You can embed blocks of preformatted content using the `text` sequence:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text plain */>}}
|
||||
func HelloWorld() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
{{</* /text */>}}
|
||||
{{< /text >}}
|
||||
|
||||
The above produces this kind of output:
|
||||
|
||||
{{< text plain >}}
|
||||
func HelloWorld() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
{{< /text >}}
|
||||
|
||||
You must indicate the syntax of the content in the preformatted block. Above, the block was marked as
|
||||
being `plain` indicating that no syntax coloring should be applied to the block. Consider the same
|
||||
block, but now annotated with the Go language syntax:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text go */>}}
|
||||
func HelloWorld() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
{{</* /text */>}}
|
||||
{{< /text >}}
|
||||
|
||||
which renders as:
|
||||
|
||||
{{< text go >}}
|
||||
func HelloWorld() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
{{< /text >}}
|
||||
|
||||
Supported syntax are `plain`, `markdown`, `yaml`, `json`, `java`, `javascript`, `c`, `cpp`, `csharp`, `go`, `html`, `protobuf`,
|
||||
`perl`, `docker`, and `bash`.
|
||||
|
||||
### Command-lines
|
||||
|
||||
When showing one or more bash command-lines, you start each command-line with a $:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text bash */>}}
|
||||
$ echo "Hello"
|
||||
{{</* /text */>}}
|
||||
{{< /text >}}
|
||||
|
||||
which produces:
|
||||
|
||||
{{< text bash >}}
|
||||
$ echo "Hello"
|
||||
{{< /text >}}
|
||||
|
||||
You can have as many command-lines as you want, but only one chunk of output is recognized.
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text bash */>}}
|
||||
$ echo "Hello" >file.txt
|
||||
$ cat file.txt
|
||||
Hello
|
||||
{{</* /text */>}}
|
||||
{{< /text >}}
|
||||
|
||||
which yields:
|
||||
|
||||
{{< text bash >}}
|
||||
$ echo "Hello" >file.txt
|
||||
$ cat file.txt
|
||||
Hello
|
||||
{{< /text >}}
|
||||
|
||||
You can also use line continuation in your command-lines:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text bash */>}}
|
||||
$ echo "Hello" \
|
||||
>file.txt
|
||||
$ echo "There" >>file.txt
|
||||
$ cat file.txt
|
||||
Hello
|
||||
There
|
||||
{{</* /text */>}}
|
||||
{{< /text >}}
|
||||
|
||||
which looks like:
|
||||
|
||||
{{< text bash >}}
|
||||
$ echo "Hello" \
|
||||
>file.txt
|
||||
$ echo "There" >>file.txt
|
||||
$ cat file.txt
|
||||
Hello
|
||||
There
|
||||
{{< /text >}}
|
||||
|
||||
By default, the output section is handled using the `plain` syntax. If the output uses a well-known
|
||||
syntax, you can specify it and get proper coloring for it. This is particularly common for YAML or JSON output:
|
||||
|
||||
{{< 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 >}}
|
||||
|
||||
which gives:
|
||||
|
||||
{{< 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 >}}
|
||||
|
||||
### Expanded form
|
||||
|
||||
To use the more advanced features for preformatted content which are described in the following sections, you must 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](#links-to-github-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](#links-to-github-files) embedded in preformatted blocks.
|
||||
|
||||
### Inline vs. imported content
|
||||
|
||||
So far, you've seen examples of inline preformatted content but it's also possible to import content, either
|
||||
from a file in the documentation repository or from an arbitrary URL on the Internet. For this, you use the
|
||||
`text_import` sequence.
|
||||
|
||||
You can use `text_import` with the `file` attribute to reference a file within the documentation repository:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text_import file="test/snippet_example.txt" syntax="plain" */>}}
|
||||
{{< /text >}}
|
||||
|
||||
which renders as:
|
||||
|
||||
{{< text_import file="test/snippet_example.txt" syntax="plain" >}}
|
||||
|
||||
You can dynamically pull in content from the Internet in a similar way, but using the `url` attribute instead of the
|
||||
`file` attribute. Here's the same file, but retrieved from a URL dynamically rather than being baked into the
|
||||
HTML statically:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text_import url="https://raw.githubusercontent.com/istio/istio.io/master/test/snippet_example.txt" syntax="plain" */>}}
|
||||
{{< /text >}}
|
||||
|
||||
which produces the following result:
|
||||
|
||||
{{< 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 that the
|
||||
GitHub raw content site (`raw.githubusercontent.com`) may be used here.
|
||||
|
||||
### Download name
|
||||
|
||||
You can control the name that the browser
|
||||
uses when the user chooses to download the preformatted content by using 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, then it is derived automatically based on the
|
||||
title of the current page for inline content, or from the name of the file or URL for imported
|
||||
content.
|
||||
|
||||
### Links to GitHub files
|
||||
|
||||
If your preformatted content references a file from Istio's GitHub repository, you can surround the relative path name of the file with a pair
|
||||
of @ symbols. These indicate that the path should be rendered as a link to the file from the current branch in GitHub. For example:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text bash */>}}
|
||||
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
|
||||
{{</* /text */>}}
|
||||
{{< /text >}}
|
||||
|
||||
Which renders as:
|
||||
|
||||
{{< text bash >}}
|
||||
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
|
||||
{{< /text >}}
|
||||
|
||||
Normally, links will point to the current release branch of the `istio/istio` repository. If you'd like a link
|
||||
that points to a different Istio repository instead, you can use the `repo` attribute:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text syntax="bash" repo="operator" */>}}
|
||||
$ cat @README.md@
|
||||
{{</* /text */>}}
|
||||
{{< /text >}}
|
||||
|
||||
which renders as:
|
||||
|
||||
{{< text syntax="bash" repo="operator" >}}
|
||||
$ cat @README.md@
|
||||
{{< /text >}}
|
||||
|
||||
If your preformatted content happens to use @ symbols for something else, you can turn off link expansion using the
|
||||
`expandlinks` attribute:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text syntax="bash" expandlinks="false" */>}}
|
||||
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
|
||||
{{</* /text */>}}
|
||||
{{< /text >}}
|
||||
|
||||
### Snippets
|
||||
|
||||
When using imported content, you can control which parts of the content to render using _named snippets_, which represent portions
|
||||
of a file. You declare snippets in a file using the `$snippets` annotation with a paired `$endsnippet` annotation. The content
|
||||
between the two annotations represents the snippet.
|
||||
For example, you could have a text file that looks like this:
|
||||
|
||||
{{< text_import file="test/snippet_example.txt" syntax="plain" >}}
|
||||
|
||||
and in your markdown file, you can then reference a particular snippet with the `snippet` attribute such as:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text_import file="test/snippet_example.txt" syntax="plain" snippet="SNIP1" */>}}
|
||||
{{< /text >}}
|
||||
|
||||
which renders as:
|
||||
|
||||
{{< text_import file="test/snippet_example.txt" syntax="plain" snippet="SNIP1" >}}
|
||||
|
||||
Within a text file, snippets can indicate the syntax of the snippet content and, for bash syntax, can
|
||||
include the syntax of the output. For example:
|
||||
|
||||
{{< text plain >}}
|
||||
$snippet MySnippetFile.txt syntax="bash" outputis="json"
|
||||
{{< /text >}}
|
||||
|
||||
## Glossary terms
|
||||
|
||||
When first introducing a specialized Istio term in a page, it is desirable to annotate the term as being in the glossary. This
|
||||
will produce special rendering inviting the user to click on the term in order to get a pop-up with the definition.
|
||||
|
||||
{{< text markdown >}}
|
||||
Mixer uses {{</*gloss*/>}}adapters{{</*/gloss*/>}} to interface to backends.
|
||||
{{< /text >}}
|
||||
|
||||
which looks like:
|
||||
|
||||
Mixer uses {{<gloss>}}adapters{{</gloss>}} to interface to backends.
|
||||
|
||||
If the term displayed on the page doesn't exactly match the entry in the glossary, you can specify a substitution:
|
||||
|
||||
{{< text markdown >}}
|
||||
Mixer uses an {{</*gloss adapters*/>}}adapter{{</*/gloss*/>}} to interface to a backend.
|
||||
{{< /text >}}
|
||||
|
||||
which looks like:
|
||||
|
||||
Mixer uses an {{<gloss adapters>}}adapter{{</gloss>}} to interface to a backend.
|
||||
|
||||
So even though the glossary entry is for *adapters*, the singular form of *adapter* can be used in the text.
|
||||
|
||||
## Callouts
|
||||
|
||||
You can bring special attention to blocks of content by highlighting warnings, ideas, tips, and quotes:
|
||||
|
||||
{{< 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 >}}
|
||||
|
||||
which looks like:
|
||||
|
||||
{{< 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 >}}
|
||||
|
||||
Please use these callouts sparingly. Callouts are intended for special notes to the user and over-using them
|
||||
throughout the site neutralizes their special attention-grabbing nature.
|
||||
|
||||
## Embedding boilerplate text
|
||||
|
||||
You can embed common boilerplate text into any markdown output using the `boilerplate` sequence:
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* boilerplate example */>}}
|
||||
{{< /text >}}
|
||||
|
||||
which results in:
|
||||
|
||||
{{< boilerplate example >}}
|
||||
|
||||
You supply the name of a boilerplate file to insert at the current location. Available boilerplates are
|
||||
located in the `boilerplates` directory. Boilerplates are just
|
||||
normal markdown files.
|
||||
|
||||
## Using tabs
|
||||
|
||||
If you have some content to display in a variety of formats, it is convenient to use a tab set and display each
|
||||
format in a different tab. To insert tabbed content, you use a combination of `tabset` and `tabs` annotations:
|
||||
|
||||
{{< 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 >}}
|
||||
|
||||
which produces 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 `name` attribute of each tab contains the text to display for the tab. The content of the tab can be almost any normal markdown.
|
||||
|
||||
The optional `category-name` and `category-value` attributes allow the tab setting to be sticky across visits to the page. As the user
|
||||
selects a tab, the selection will be saved automatically with the given name and value. If multiple tab sets use the same category name
|
||||
and values, their setting will be 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, if many tab sets are used to represent a choice between `GCP`, `BlueMix` and `AWS`, they can all use a category name of `environment` and values of
|
||||
`gcp`, `bluemix`, and `aws`. When a user selects a tab in one page, the equivalent tab will automatically be selected in any other tab set of any page visited.
|
||||
|
||||
### Limitations
|
||||
|
||||
You can use almost any markdown in a tab, except for the following:
|
||||
|
||||
- *No headers*. Headers in a tab will appear in the table of contents and yet clicking on the entry in the
|
||||
table of contents will not automatically select the tab.
|
||||
|
||||
- *No nested tab sets*. Don't try it, it's horrible.
|
||||
|
||||
## Banners and stickers
|
||||
|
||||
You can automatically insert time-sensitive banners and stickers into the generated site in order
|
||||
to advertise upcoming events, or publicize something new.
|
||||
|
||||
There are two types of promotions supported:
|
||||
|
||||
- **Countdown stickers** that show how much time is left before something big happens. (e.g. "2 days until Istio 1.5").
|
||||
Stickers have minimal visuals displayed to the user during the event period.
|
||||
|
||||
- **Banners** that display a prominent message to the user to let them know a significant event is about to take place,
|
||||
is taking place, or has taken place. (e.g. "Istio 1.5 has been released, download it today!" or "Join us at KubeCon on March 30").
|
||||
Banners are full-screen slices displayed to the user during the event period.
|
||||
|
||||
To create banners and stickers, you add files to the `events/banners` or `events/stickers` directories. You create one normal markdown
|
||||
file per event. Within these files, you use the following dedicated front-matter fields to control various features:
|
||||
|
||||
<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 banned that says "Istio x.y.z has just been relesed".
|
||||
</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 that 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 ommiting 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. Once 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>
|
||||
|
||||
## Renaming, moving, or deleting pages
|
||||
|
||||
If you move pages around or delete them completely, you should make sure existing links users may have to those pages continue to work.
|
||||
You do this by adding aliases which will cause the user to be redirected automatically from the old URL to a new URL.
|
||||
|
||||
In the page that is the *target* of the redirect (where you'd like users to land), you simply add the
|
||||
following to the front-matter:
|
||||
|
||||
{{< text plain >}}
|
||||
aliases:
|
||||
- <path>
|
||||
{{< /text >}}
|
||||
|
||||
For example
|
||||
|
||||
{{< text plain >}}
|
||||
---
|
||||
title: Frequently Asked Questions
|
||||
description: Questions Asked Frequently.
|
||||
weight: 12
|
||||
aliases:
|
||||
- /help/faq
|
||||
---
|
||||
{{< /text >}}
|
||||
|
||||
With the above in a page saved as `faq/_index.md`, the user will be able to access the page by going
|
||||
to `istio.io/faq/` as normal, as well as `istio.io/help/faq/`.
|
||||
|
||||
You can also add many redirects like so:
|
||||
|
||||
{{< text plain >}}
|
||||
---
|
||||
title: Frequently Asked Questions
|
||||
description: Questions Asked Frequently.
|
||||
weight: 12
|
||||
aliases:
|
||||
- /faq
|
||||
- /faq2
|
||||
- /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/en` 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 with:
|
||||
|
||||
{{< 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 repository.
|
||||
|
||||
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 >}}
|
||||
|
||||
## Using GitHub
|
||||
|
||||
Checkout [Working with GitHub](/about/contribute/github) to learn how to generally use GitHub to submit
|
||||
documentation changes. Of particular interest, see the [section on branching](/about/contribute/github#branching)
|
||||
to understand how we use branches and cherry picking.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Diagram Creation Guidelines
|
||||
description: Provides assets and instructions to create diagrams for the Istio documentation.
|
||||
weight: 40
|
||||
weight: 12
|
||||
keywords: [contribute,diagram,documentation,guide]
|
||||
---
|
||||
|
||||
|
|
@ -27,15 +27,15 @@ To create your diagrams, follow these steps:
|
|||
1. Connect the shapes with the appropriate style of line.
|
||||
1. Label the shapes and lines with descriptive yet short text.
|
||||
1. Add a legend for any labels that apply multiple times.
|
||||
1. [Contribute](/about/contribute/github/#add) you diagram to our
|
||||
1. [Contribute](/about/contribute/add-content) your diagram to our
|
||||
documentation.
|
||||
|
||||
If you create the diagram in Google Draw, follow these steps:
|
||||
|
||||
1. Put your diagram in our [team drive](https://drive.google.com/corp/drive/u/0/folders/1jczscJueUBR3IOvH30q9HAZX0jC7GSyW).
|
||||
1. Once the diagram is complete, export it as SVG and include the SVG
|
||||
1. When the diagram is complete, export it as SVG and include the SVG
|
||||
file in your PR.
|
||||
1. Leave a comment in the MarkDown file containing the diagram with the
|
||||
1. Leave a comment in the Markdown file containing the diagram with the
|
||||
URL to the Google Draw file.
|
||||
|
||||
If your diagram depicts a process, **do not add the descriptions of the steps**
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Working with GitHub
|
||||
description: Shows you how to use GitHub to work on Istio documentation.
|
||||
weight: 30
|
||||
title: Work with GitHub
|
||||
description: Shows you how to use GitHub to contribute to the Istio documentation.
|
||||
weight: 2
|
||||
aliases:
|
||||
- /docs/welcome/contribute/creating-a-pull-request.html
|
||||
- /docs/welcome/contribute/staging-your-changes.html
|
||||
|
|
@ -12,128 +12,84 @@ aliases:
|
|||
keywords: [contribute,community,github,pr]
|
||||
---
|
||||
|
||||
We're excited that you're interested in contributing to improve and expand
|
||||
our docs! Please take a few moments to get familiar with our procedures before
|
||||
you get started.
|
||||
The Istio documentation follows the standard [GitHub collaboration flow](https://guides.github.com/introduction/flow/)
|
||||
for Pull Requests (PRs). This well-established collaboration model helps open
|
||||
source projects manage the following types of contributions:
|
||||
|
||||
To work on Istio documentation, you need to:
|
||||
- [Add](/about/contribute/add-content) new files to the repository.
|
||||
- [Edit](#quick-edit) existing files.
|
||||
- [Review](/about/contribute/review) the added or modified files.
|
||||
- Manage multiple release or development [branches](#branching-strategy).
|
||||
|
||||
The contribution guides assume you can complete the following tasks:
|
||||
|
||||
- Fork the [Istio documentation repository](https://github.com/istio/istio.io).
|
||||
- Create a branch for your changes.
|
||||
- Add commits to that branch.
|
||||
- Open a PR to share your contribution.
|
||||
|
||||
## Before you begin
|
||||
|
||||
To contribute to the Istio documentation, you need to:
|
||||
|
||||
1. Create a [GitHub account](https://github.com).
|
||||
|
||||
1. Sign the [Contributor License
|
||||
Agreement](https://github.com/istio/community/blob/master/CONTRIBUTING.md#contributor-license-agreements).
|
||||
1. Sign the [Contributor License Agreement](https://github.com/istio/community/blob/master/CONTRIBUTING.md#contributor-license-agreements).
|
||||
|
||||
The documentation is published under the [Apache
|
||||
2.0](https://github.com/istio/community/blob/master/LICENSE) license.
|
||||
1. Install [Docker](https://www.docker.com/get-started) on your authoring system
|
||||
to preview and test your changes.
|
||||
|
||||
## How to contribute
|
||||
The Istio documentation is published under the
|
||||
[Apache 2.0](https://github.com/istio/community/blob/master/LICENSE) license.
|
||||
|
||||
There are three ways you can contribute to the Istio documentation:
|
||||
## Perform quick edits {#quick-edit}
|
||||
|
||||
* If you want to edit an existing page, you can open up the page in your
|
||||
browser and select the **Edit This Page on GitHub** option from the gear menu
|
||||
at the top right of each page. This takes you to GitHub to edit and
|
||||
submit the changes.
|
||||
Anyone with a GitHub account who signs the CLA can contribute a quick
|
||||
edit to any page on the Istio website. The process is very simple:
|
||||
|
||||
* If you want to work on the site in general, follow the steps in our
|
||||
[How to add content section](#add).
|
||||
1. Visit the page you wish to edit.
|
||||
1. Add `preliminary` to the beginning of the URL. For example, to edit
|
||||
`https://istio.io/about`, the new URL should be
|
||||
`https://preliminary.istio.io/about`
|
||||
1. Click the pencil icon in the lower right corner.
|
||||
1. Perform your edits on the GitHub UI.
|
||||
1. Submit a Pull Request with your changes.
|
||||
|
||||
* If you want to review an existing pull request (PR), follow the steps in our
|
||||
[How to review content section](#review)
|
||||
Please see our guides on how to [contribute new content](/about/contribute/add-content)
|
||||
or [review content](/about/contribute/review) to learn more about submitting more
|
||||
substantial changes.
|
||||
|
||||
Once your changes are merged, they show up immediately on
|
||||
`preliminary.istio.io`. However, the changes only
|
||||
show up on `istio.io` the next time we produce a new
|
||||
release, which happens around once a quarter.
|
||||
## Branching strategy
|
||||
|
||||
### How to add content {#add}
|
||||
|
||||
To add content you must create a fork of the repository and submit a PR from
|
||||
your fork to the docs main repository. The following steps describe the
|
||||
process:
|
||||
Active content development takes place using the master branch of the
|
||||
`istio/istio.io` repository. On the day of an Istio release, we create a release
|
||||
branch of master for that release. The following button takes you to the
|
||||
repository on GitHub:
|
||||
|
||||
<a class="btn"
|
||||
href="https://github.com/istio/istio.io/">Browse this site's source
|
||||
code</a>
|
||||
|
||||
1. Click the button above to visit the GitHub repository.
|
||||
The Istio documentation repository uses multiple branches to publish
|
||||
documentation for all Istio releases. Each Istio release has a corresponding
|
||||
documentation branch. For example, there are branches called `release-1.0`,
|
||||
`release-1.1`, `release-1.2` and so forth. These branches were created on the
|
||||
day of the corresponding release. To view the documentation for a specific
|
||||
release, see the [archive page](https://archive.istio.io/).
|
||||
|
||||
1. Click the **Fork** button in the upper-right corner of the screen to
|
||||
create a copy of our repository in your GitHub account.
|
||||
This branching strategy allows us to provide the following Istio online resources:
|
||||
|
||||
1. Create a clone of your fork and make any changes you want.
|
||||
- The [public site](/docs/) shows the content from the current
|
||||
release branch.
|
||||
|
||||
1. When you are ready to send those changes to us, push the changes to your
|
||||
fork.
|
||||
- The preliminary site at `https://preliminary.istio.io` shows the content from
|
||||
the master branch.
|
||||
|
||||
1. Go to the index page for your fork, and click **New Pull Request** to let
|
||||
us know about it.
|
||||
|
||||
### How to review content {#review}
|
||||
|
||||
If your review is small, simply comment on the PR directly. If you review the
|
||||
content in detail, follow these steps:
|
||||
|
||||
1. Leave a comment on the PR with the text `/hold`. This command prevents the
|
||||
PR from being merged before you are able to complete your review.
|
||||
|
||||
1. Perform your detailed review. When possible leave specific comments
|
||||
directly on the files and lines affected.
|
||||
|
||||
1. Provide suggestions to the PR owner in your comments when appropriate. For
|
||||
example:
|
||||
|
||||
{{< text markdown >}}
|
||||
Use present tense to avoid verb congruence issues and
|
||||
to make the text easier to understand:
|
||||
|
||||
&96;&96;&96;suggestion
|
||||
|
||||
Pilot maintains an abstract model of the mesh.
|
||||
|
||||
&96;&96;&96;
|
||||
{{< /text >}}
|
||||
|
||||
1. Publish your review to share your comments and suggestions with us and the
|
||||
PR owner. Request changes as the review warrants.
|
||||
|
||||
{{< warning >}}
|
||||
If you don't publish your review, the PR owner and
|
||||
the community cannot see your comments.
|
||||
{{< /warning >}}
|
||||
|
||||
1. Once you publish your review, leave a comment with the text:
|
||||
`/hold cancel`. That command unblocks the PR from being merged.
|
||||
|
||||
## Previewing your work
|
||||
|
||||
When you submit a pull request, your PR page on GitHub shows a link to a
|
||||
staging site built automatically for your PR. This is useful for you to see
|
||||
what the final page looks like to end-users. Folks reviewing your
|
||||
pull request also use this staging site to make sure everything looks good.
|
||||
|
||||
If you created a fork of the repository, you can preview your changes locally.
|
||||
See this
|
||||
[README](https://github.com/istio/istio.io/blob/master/README.md) for
|
||||
instructions.
|
||||
|
||||
## Branching
|
||||
|
||||
We use multiple branches to track documentation for different versions of Istio.
|
||||
The master branch is where active doc work takes place, this is where you should
|
||||
generally be making changes.
|
||||
|
||||
On the day of an Istio release, a release branch is created from master for that
|
||||
release. For example, there are branches called `release-1.0`, `release-1.1`,
|
||||
`release-1.2` and so forth.
|
||||
|
||||
The `istio.io` public site is produced by processing content from the current
|
||||
release branch. The `preliminary.istio.io` site is produced by processing
|
||||
content from the master branch. And the `archive.istio.io` site is
|
||||
produced by processing content from all prior release branches.
|
||||
- The [archive site](https://archive.istio.io) shows the content from all prior
|
||||
release branches.
|
||||
|
||||
Given how branching works, if you submit a change into the master branch,
|
||||
that change will not appear on `istio.io` until the next major Istio release
|
||||
that change won't appear on `istio.io` until the next major Istio release
|
||||
happens. If your documentation change is relevant to the current Istio release,
|
||||
then it's probably worth also applying your change to the current release branch.
|
||||
You can do this easily and automatically by using the special cherry-pick labels
|
||||
|
|
@ -141,14 +97,14 @@ on your documentation PR. For example, if you introduce a correction in a PR to
|
|||
the master branch, you can apply the `cherrypick/release-1.4` label in order to
|
||||
merge this change to the `release-1.4` branch.
|
||||
|
||||
Once your initial PR is merged, automation will create a new PR in the release
|
||||
When your initial PR is merged, automation creates a new PR in the release
|
||||
branch which includes your changes. You may need to add a comment to the PR
|
||||
that reads `@googlebot I consent` in order to satisfy the `CLA` bot that we
|
||||
use.
|
||||
|
||||
On rare occasions, automatic cherry picks don't work. When that happens, the
|
||||
automation will leave a note in the original PR indicating it failed. When
|
||||
that happens, you will need to manually create the cherry pick and deal
|
||||
automation leaves a note in the original PR indicating it failed. When
|
||||
that happens, you must manually create the cherry pick and deal
|
||||
with the merge issues that prevented the process from working automatically.
|
||||
|
||||
Note that we only ever cherry pick changes into the current release branch,
|
||||
|
|
|
|||
|
|
@ -0,0 +1,104 @@
|
|||
---
|
||||
title: Documentation Review Process
|
||||
description: Shows you how changes to the Istio documentation and website are reviewed and approved.
|
||||
weight: 6
|
||||
keywords: [contribute,community,github,pr,documentation,review, approval]
|
||||
---
|
||||
|
||||
The maintainers and working group leads of the Istio Docs Working Group (WG) approve
|
||||
all changes to the [Istio website](/docs/).
|
||||
|
||||
A **documentation reviewer** is a trusted contributor that approves content that
|
||||
meets the acceptance criteria described in the [review criteria](#review-criteria).
|
||||
All content reviews follow the process described in [Reviewing content PRs](#review-content-prs).
|
||||
|
||||
Only Docs Maintainers and WG Leads can merge content into the [istio.io repository](https://github.com/istio/istio.io).
|
||||
|
||||
Content for Istio often needs to be reviewed on short notice and not all content
|
||||
has the same relevance. The last minute nature of contributions and the finite
|
||||
number of reviewers make the prioritization of content reviews necessary to
|
||||
function at scale. This page provides clear review criteria to ensure all review
|
||||
work happens **consistently**, **reliably** and follows the **same quality standards**.
|
||||
|
||||
## Review content PRs
|
||||
|
||||
Documentation reviewers, maintainers, and WG leads follow a clear process to
|
||||
review content PRs to ensure all reviews are consistent. The process is as
|
||||
follows:
|
||||
|
||||
1. The **Contributor** submits a new content PR to the istio.io repository.
|
||||
1. The **Reviewer** performs a review of the content and determines if it meets the
|
||||
acceptance criteria.
|
||||
1. The **Reviewer** adds any technical WG pertinent for the content if the
|
||||
contributor hasn't already.
|
||||
1. The **Contributor** and the **Reviewer** work together until the content
|
||||
meets all required acceptance criteria and the issues are addressed.
|
||||
1. If the content is urgent and meeting the supplemental acceptance criteria
|
||||
requires significant effort, the **Reviewer** files a follow up issue on
|
||||
the istio.io repository to address the problems at a later date.
|
||||
1. The **Contributor** addresses all required and supplemental feedback as
|
||||
agreed by the Reviewer and Contributor. Any feedback filed in the follow up
|
||||
issues is addressed later.
|
||||
1. When a **technical** WG lead or maintainer approves the content PR, the
|
||||
**Reviewer** can approve the PR.
|
||||
1. If a Docs WG maintainer or lead reviewed the content, they not only approve,
|
||||
but they also merge the content. Otherwise, maintainers and leads are automatically
|
||||
notified of the **Reviewer's** approval and prioritize approving and merging
|
||||
the already reviewed content.
|
||||
|
||||
The following diagram depicts the process:
|
||||
|
||||
{{< image width="75%" ratio="45.34%"
|
||||
link="./review-process.svg"
|
||||
alt="Documentation review process"
|
||||
title="Documentation review process"
|
||||
>}}
|
||||
|
||||
- **Contributors** perform the steps in the gray shapes.
|
||||
- **Reviewers** perform the steps in the blue shapes.
|
||||
- **Docs Maintainers and WG Leads** perform the steps in the green shapes.
|
||||
|
||||
## Follow up issues
|
||||
|
||||
When a **Reviewer** files a follow up issue as part of the
|
||||
[review process](#review-content-prs), the GitHub issue must include the
|
||||
following information:
|
||||
|
||||
- Details about the [supplemental acceptance criteria](#supplemental-acceptance-criteria)
|
||||
the content failed to meet.
|
||||
- Link to the original PR.
|
||||
- Username of the technical Subject Matter Experts (SMEs).
|
||||
- Labels to sort the issues.
|
||||
- Estimate of work: Reviewers provide their best estimate of how long it would
|
||||
take to address the remaining issues working alongside the original
|
||||
contributor.
|
||||
|
||||
## Review criteria
|
||||
|
||||
Our review process supports our [code of conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct)
|
||||
by making our review criteria transparent and applying it to all content contributions.
|
||||
|
||||
Criteria has two tiers: required and supplemental.
|
||||
|
||||
### Required acceptance criteria
|
||||
|
||||
- Technical accuracy: At least one technical WG lead or maintainer reviews and
|
||||
approves the content.
|
||||
- Correct markup: All linting and tests pass.
|
||||
- Language: Content must be clear and understandable. To learn more see the
|
||||
[highlights](https://developers.google.com/style/highlights) and
|
||||
[general principles](https://developers.google.com/style/tone) of the Google developer
|
||||
style guide.
|
||||
- Links and navigation: The content has no broken links and the site builds properly.
|
||||
|
||||
### Supplemental acceptance criteria
|
||||
|
||||
- Content structure: Information structure enhances the readers' experience.
|
||||
- Consistency: Content adheres to all recommendations in the
|
||||
[Istio contribution guides](/about/contribute/)
|
||||
- Style: Content adheres to the [Google developer style guide](https://developers.google.com/style).
|
||||
- Graphic assets: Diagrams follow the Istio [diagram creation guide](/about/contribute/diagrams/).\
|
||||
- Code samples: Content provides relevant, testable, and working code samples.
|
||||
- Content reuse: Any repeatable content follows a reusability strategy using
|
||||
boilerplate text.
|
||||
- Glossary: New terms are added to the glossary with clear definitions.
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 6.8 KiB |
|
|
@ -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: "2 days until Istio 1.5". Stickers have minimal visual impact for
|
||||
readers during the event.
|
||||
|
||||
- **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 KubeCon
|
||||
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>
|
||||
|
|
@ -1,92 +1,28 @@
|
|||
---
|
||||
title: Style Guide
|
||||
description: Explains the dos and donts of writing Istio documentation.
|
||||
weight: 20
|
||||
description: Explains the style conventions used in the Istio documentation.
|
||||
weight: 10
|
||||
aliases:
|
||||
- /docs/welcome/contribute/style-guide.html
|
||||
- /docs/reference/contribute/style-guide.html
|
||||
keywords: [contribute]
|
||||
---
|
||||
|
||||
This page provides the content guidelines for the Istio documentation. These
|
||||
guidelines do not supersede your best judgment and enhancements to this
|
||||
document in a pull request are welcome.
|
||||
All content accepted into the Istio documentation must be **clear** and
|
||||
**understandable**. The standard we use to make that determination is defined by
|
||||
the [highlights](https://developers.google.com/style/highlights) and
|
||||
the [general principles](https://developers.google.com/style/tone) of the Google
|
||||
developer style guide. See our [review page](/about/contribute/review) for details on how your content
|
||||
contributions are reviewed and accepted.
|
||||
|
||||
## Formatting standards
|
||||
Here you can find all the scenarios where the Istio project has decided to
|
||||
follow a different practice and basic style guidance with Istio-specific
|
||||
examples.
|
||||
|
||||
### Use consistent capitalization
|
||||
## Use sentence case for headings
|
||||
|
||||
Don't use capitalization for emphasis.
|
||||
|
||||
Follow the original capitalization employed in the code or configuration files
|
||||
when referencing those values directly. Use back-ticks \`\` around the
|
||||
referenced content 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. Tell the reader what the placeholder
|
||||
represents. For example:
|
||||
|
||||
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.
|
||||
|
||||
### Use **bold** for user interface elements
|
||||
|
||||
|Do | Don't
|
||||
|------------------|------
|
||||
|Click **Fork**. | Click "Fork".
|
||||
|Select **Other**. | Select 'Other'.
|
||||
|
||||
### Use _italics_ to define or introduce 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 `code` style for filenames, 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 `code` style for 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` style for 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.
|
||||
|
||||
### Use title capitalization for `title:` front-matter
|
||||
|
||||
The text for the `title:` front-matter must use title case:
|
||||
Capitalize the first letter of every word except conjunctions and prepositions.
|
||||
This is unlike headings within the document, as described below.
|
||||
|
||||
### Only capitalize the first letter of headings
|
||||
|
||||
For any headings use sentence case: only capitalize the first word of the
|
||||
heading, except for proper nouns or acronyms. Note that the
|
||||
`title:` annotation in markdown uses title case.
|
||||
Use sentence case for the headings in your document. Only capitalize the first
|
||||
word of the heading, except for proper nouns or acronyms.
|
||||
|
||||
|Do | Don't
|
||||
|------------------------|-----
|
||||
|
|
@ -94,50 +30,12 @@ heading, except for proper nouns or acronyms. Note that the
|
|||
|Using Envoy for ingress | Using envoy for ingress
|
||||
|Using HTTPS | Using https
|
||||
|
||||
## Terminology standards
|
||||
## Use title case for the value of the `title:` field of the front-matter
|
||||
|
||||
We want to use the standard terms in this section consistently within the
|
||||
documentation for clarity.
|
||||
The text for the `title:` field of the front-matter must use title case.
|
||||
Capitalize the first letter of every word except conjunctions and prepositions.
|
||||
|
||||
### 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`
|
||||
|
||||
## Best practices
|
||||
|
||||
### Use present tense
|
||||
## Use present tense
|
||||
|
||||
|Do | Don't
|
||||
|-----------------------------|------
|
||||
|
|
@ -146,14 +44,14 @@ Related Terms:
|
|||
Exception: Use future or past tense if it is required to convey the correct
|
||||
meaning. This exception is extremely rare and should be avoided.
|
||||
|
||||
### Use active voice
|
||||
## Use active voice
|
||||
|
||||
|Do | Don't
|
||||
|-------------------------------------------|------
|
||||
|You can explore the API using a browser. | The API can be explored using a browser.
|
||||
|The YAML file specifies the replica count. | The replica count is specified in the YAML file.
|
||||
|
||||
### Use simple and direct language
|
||||
## Use simple and direct language
|
||||
|
||||
Use simple and direct language. Avoid using unnecessary phrases, such as saying
|
||||
"please."
|
||||
|
|
@ -164,14 +62,14 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying
|
|||
|See the configuration file. | Please see the configuration file.
|
||||
|View the Pods. | With this next command, we'll view the Pods.
|
||||
|
||||
### Address the reader as "you"
|
||||
## Address the reader as "you"
|
||||
|
||||
|Do | Don't
|
||||
|---------------------------------------|------
|
||||
|You can create a `Deployment` by ... | We'll create a `Deployment` by ...
|
||||
|In the preceding output, you can see...| In the preceding output, we can see ...
|
||||
|
||||
### Create useful links
|
||||
## Create useful links
|
||||
|
||||
There are good hyperlinks, and bad hyperlinks. The common practice of calling
|
||||
links *here* or *click here* are examples of bad hyperlinks. Check out [this
|
||||
|
|
@ -179,7 +77,7 @@ excellent article](https://medium.com/@heyoka/dont-use-click-here-f32f445d1021)
|
|||
explaining what makes a good hyperlink and try to keep these guidelines in
|
||||
mind when creating or reviewing site content.
|
||||
|
||||
### Avoid using "we"
|
||||
## Avoid using "we"
|
||||
|
||||
Using "we" in a sentence can be confusing, because the reader might not know
|
||||
whether they're part of the "we" you're describing.
|
||||
|
|
@ -190,33 +88,29 @@ whether they're part of the "we" you're describing.
|
|||
|Istio provides a new feature for ... | We provide a new feature ...
|
||||
|This page teaches you how to use pods. | In this page, we are going to learn about pods.
|
||||
|
||||
### Avoid jargon and idioms
|
||||
## Avoid jargon and idioms
|
||||
|
||||
Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier.
|
||||
Some readers speak English as a second language. Avoid jargon and idioms to help
|
||||
make their understanding easier.
|
||||
|
||||
|Do | Don't
|
||||
|----------------------|------
|
||||
|Internally, ... | Under the hood, ...
|
||||
|Create a new cluster. | Turn up a new cluster.
|
||||
|Initially, ... | Out of the box, ...
|
||||
|
||||
### Avoid statements about the future
|
||||
## Avoid statements about the future
|
||||
|
||||
Avoid making promises or giving hints about the future. If you need to talk
|
||||
about an alpha feature, put the text under a heading that identifies it as
|
||||
alpha information.
|
||||
about a feature in development, add a boilerplate under the front matter that
|
||||
identifies the information accordingly.
|
||||
|
||||
### Avoid statements that will soon be out of date
|
||||
|
||||
Avoid words like "currently" and "new". A feature that is new today might not
|
||||
be considered new in a few months.
|
||||
Avoid using wording that becomes outdated quickly like "currently" and
|
||||
"new". A feature that is new today is not new for long.
|
||||
|
||||
|Do | Don't
|
||||
|------------------------------------|------
|
||||
|In version 1.4, ... | In the current version, ...
|
||||
|The Federation feature provides ... | The new Federation feature provides ...
|
||||
|
||||
### Minimize use of callouts
|
||||
|
||||
[Callouts](/about/contribute/creating-and-editing-pages/#callouts) let you highlight some particular content in your pages, but
|
||||
they need to be used sparingly. Callouts are intended for special notes to the user and over-using them
|
||||
throughout the site neutralizes their special attention-grabbing nature.
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
@ -11,12 +11,12 @@ target_release: 1.3
|
|||
Welcome to the Istio blog!
|
||||
|
||||
To make it easier to publish your content on our website, we
|
||||
[updated the content types guide](/about/contribute/creating-and-editing-pages/#choosing-a-page-type).
|
||||
[updated the content types guide](/about/contribute/add-content/#content-types).
|
||||
|
||||
The goal of the updated guide is to make sharing and finding content easier.
|
||||
|
||||
We want to make sharing timely information on Istio easy and the [Istio blog](/blog) is
|
||||
a good place to start.
|
||||
We want to make sharing timely information on Istio easy and the [Istio blog](/blog)
|
||||
is a good place to start.
|
||||
|
||||
We welcome your posts to the blog if you think your content falls in one of the
|
||||
following four categories:
|
||||
|
|
@ -27,7 +27,7 @@ following four categories:
|
|||
- Your post details how to accomplish a task or fulfill a specific use case
|
||||
using Istio.
|
||||
|
||||
Posting your blog is only [one PR away](/about/contribute/github/#how-to-contribute)
|
||||
and, if you wish, you can [request a review](/about/contribute/github/#review).
|
||||
Posting your blog is only [one PR away](/about/contribute/github/)
|
||||
and, if you wish, you can [request a review](/about/contribute/review).
|
||||
|
||||
We look forward to reading about your Istio experience on the blog soon!
|
||||
|
|
|
|||
Loading…
Reference in New Issue