mirror of https://github.com/istio/istio.io.git
200 lines
39 KiB
HTML
200 lines
39 KiB
HTML
<!doctype html><html lang=en itemscope itemtype=https://schema.org/WebPage><head><meta charset=utf-8><meta http-equiv=x-ua-compatible content="IE=edge"><meta name=viewport content="width=device-width,initial-scale=1,shrink-to-fit=no"><meta name=theme-color content="#466BB0"><meta name=title content="Add Code Blocks"><meta name=description content="Explains how to include code in your documentation."><meta name=keywords content="microservices,services,mesh,contribute,documentation,guide,code-block"><meta property="og:title" content="Add Code Blocks"><meta property="og:type" content="website"><meta property="og:description" content="Explains how to include code in your documentation."><meta property="og:url" content="/v1.5/about/contribute/code-blocks/"><meta property="og:image" content="/v1.5/img/istio-whitelogo-bluebackground-framed.svg"><meta property="og:image:alt" content="Istio Logo"><meta property="og:image:width" content="112"><meta property="og:image:height" content="150"><meta property="og:site_name" content="Istio"><meta name=twitter:card content="summary"><meta name=twitter:site content="@IstioMesh"><title>Istioldie 1.5 / Add Code Blocks</title><script async src="https://www.googletagmanager.com/gtag/js?id=UA-98480406-2"></script><script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}
|
|
gtag('js',new Date());gtag('config','UA-98480406-2');</script><link rel=alternate type=application/rss+xml title="Istio Blog" href=/v1.5/blog/feed.xml><link rel=alternate type=application/rss+xml title="Istio News" href=/v1.5/news/feed.xml><link rel=alternate type=application/rss+xml title="Istio Blog and News" href=/v1.5/feed.xml><link rel="shortcut icon" href=/v1.5/favicons/favicon.ico><link rel=apple-touch-icon href=/v1.5/favicons/apple-touch-icon-180x180.png sizes=180x180><link rel=icon type=image/png href=/v1.5/favicons/favicon-16x16.png sizes=16x16><link rel=icon type=image/png href=/v1.5/favicons/favicon-32x32.png sizes=32x32><link rel=icon type=image/png href=/v1.5/favicons/android-36x36.png sizes=36x36><link rel=icon type=image/png href=/v1.5/favicons/android-48x48.png sizes=48x48><link rel=icon type=image/png href=/v1.5/favicons/android-72x72.png sizes=72x72><link rel=icon type=image/png href=/v1.5/favicons/android-96x96.png sizes=96xW96><link rel=icon type=image/png href=/v1.5/favicons/android-144x144.png sizes=144x144><link rel=icon type=image/png href=/v1.5/favicons/android-192x192.png sizes=192x192><link rel=manifest href=/v1.5/manifest.json><meta name=apple-mobile-web-app-title content="Istio"><meta name=application-name content="Istio"><link rel=stylesheet href="https://fonts.googleapis.com/css?family=Work+Sans:400|Chivo:400|Work+Sans:500,300,600,300italic,400italic,500italic,600italic|Chivo:500,300,600,300italic,400italic,500italic,600italic"><link rel=stylesheet href=/v1.5/css/all.css><script src=/v1.5/js/themes_init.min.js></script></head><body class="language-unknown archive-site"><script>const branchName="release-1.5";const docTitle="Add Code Blocks";const iconFile="\/v1.5/img/icons.svg";const buttonCopy='Copy to clipboard';const buttonPrint='Print';const buttonDownload='Download';</script><script src="https://www.google.com/cse/brand?form=search-form" defer></script><script src=/v1.5/js/all.min.js data-manual defer></script><header><nav><a id=brand href=/v1.5/><span class=logo><svg viewBox="0 0 300 300"><circle cx="150" cy="150" r="146" stroke-width="2"/><polygon points="65 240 225 240 125 270"/><polygon points="65 230 125 220 125 110"/><polygon points="135 220 225 230 135 30"/></svg></span><span class=name>Istioldie 1.5</span></a><div id=hamburger><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#hamburger"/></svg></div><div id=header-links><a title="Learn how to deploy, use, and operate Istio." href=/v1.5/docs/>Docs</a>
|
|
<a title="Posts about using Istio." href=/v1.5/blog/2020/>Blog<i class=dot data-prefix=/blog></i></a>
|
|
<a title="Timely news about the Istio project." href=/v1.5/news/>News<i class=dot data-prefix=/news></i></a>
|
|
<a title="Frequently Asked Questions about Istio." href=/v1.5/faq/>FAQ</a>
|
|
<a class=current title="Get a bit more in-depth info about the Istio project." href=/v1.5/about/>About</a><div class=menu><button id=gearDropdownButton class=menu-trigger title="Options and settings" aria-label="Options and Settings" aria-controls=gearDropdownContent><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#gear"/></svg></button><div id=gearDropdownContent class=menu-content aria-labelledby=gearDropdownButton role=menu><a tabindex=-1 role=menuitem lang=en id=switch-lang-en class=active>English</a>
|
|
<a tabindex=-1 role=menuitem lang=zh id=switch-lang-zh>中文</a><div role=separator></div><a tabindex=-1 role=menuitem class=active id=light-theme-item>Light Theme</a>
|
|
<a tabindex=-1 role=menuitem id=dark-theme-item>Dark Theme</a><div role=separator></div><a tabindex=-1 role=menuitem id=syntax-coloring-item>Color Examples</a><div role=separator></div><h6>Other versions of this site</h6><a tabindex=-1 role=menuitem onclick="navigateToUrlOrRoot('https://istio.io/about\/contribute\/code-blocks\/');return false;">Current Release</a>
|
|
<a tabindex=-1 role=menuitem onclick="navigateToUrlOrRoot('https://preliminary.istio.io/about\/contribute\/code-blocks\/');return false;">Next Release</a>
|
|
<a tabindex=-1 role=menuitem href=https://istio.io/archive>Older Releases</a></div></div><button id=search-show title="Search this site" aria-label=Search><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#magnifier"/></svg></button></div><form id=search-form name=cse role=search><input type=hidden name=cx value=002184991200833970123:iwwf17ikgf4>
|
|
<input type=hidden name=ie value=utf-8>
|
|
<input type=hidden name=hl value=en>
|
|
<input type=hidden id=search-page-url value=/v1.5/search>
|
|
<input id=search-textbox class=form-control name=q type=search aria-label="Search this site">
|
|
<button id=search-close title="Cancel search" type=reset aria-label="Cancel search"><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#cancel-x"/></svg></button></form></nav></header><div class=banner-container></div><main class=primary><div id=sidebar-container class="sidebar-container sidebar-offcanvas"><nav id=sidebar aria-label="Section Navigation"><div class=directory><div class=card><div id=header0 class=header title="Get a bit more in-depth info about the Istio project."><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#about"/></svg>About Istio</div><div class="body default" aria-labelledby=header0><ul role=tree aria-expanded=true aria-labelledby=header0><li role=treeitem aria-label="Contribute Documentation to Istio"><button class=show aria-hidden=true></button><a title="Details how to create and maintain documentation pages." href=/v1.5/about/contribute/>Contribute Documentation to Istio</a><ul role=group aria-expanded=true class=leaf-section><li role=none><a role=treeitem title="Shows you how to use GitHub to contribute to the Istio documentation." href=/v1.5/about/contribute/github/>Work with GitHub</a></li><li role=none><a role=treeitem title="Details how to contribute new documentation to Istio." href=/v1.5/about/contribute/add-content/>Add New Documentation</a></li><li role=none><a role=treeitem title="Explains the front matter used in our documentation and the fields available." href=/v1.5/about/contribute/front-matter/>Front matter</a></li><li role=none><a role=treeitem title="Explains how to locally build, test, serve, and preview the website." href=/v1.5/about/contribute/build/>Build and serve the website locally</a></li><li role=none><a role=treeitem title="Shows you how changes to the Istio documentation and website are reviewed and approved." href=/v1.5/about/contribute/review/>Documentation Review Process</a></li><li role=none><span role=treeitem class=current title="Explains how to include code in your documentation.">Add Code Blocks</span></li><li role=none><a role=treeitem title="Explains the shortcodes available and how to use them." href=/v1.5/about/contribute/shortcodes/>Use Shortcodes</a></li><li role=none><a role=treeitem title="Explains the standard markup used to format Istio documentation." href=/v1.5/about/contribute/formatting/>Follow Formatting Standards</a></li><li role=none><a role=treeitem title="Explains the style conventions used in the Istio documentation." href=/v1.5/about/contribute/style-guide/>Style Guide</a></li><li role=none><a role=treeitem title="Explains the terminology standards used in the Istio documentation." href=/v1.5/about/contribute/terminology/>Terminology Standards</a></li><li role=none><a role=treeitem title="Provides assets and instructions to create diagrams for the Istio documentation." href=/v1.5/about/contribute/diagrams/>Diagram Creation Guidelines</a></li></ul></li><li role=treeitem aria-label="Our Community"><button aria-hidden=true></button><a title="Learn about our community, our customers, and our partners." href=/v1.5/about/community/>Our Community</a><ul role=group aria-expanded=false class=leaf-section><li role=none><a role=treeitem title="Information on the various ways to participate and interact with the Istio community." href=/v1.5/about/community/join/>Getting Involved</a></li><li role=none><a role=treeitem title="Who's building stuff around Istio." href=/v1.5/about/community/partners/>Partners</a></li><li role=none><a role=treeitem title="Who's using Istio out there." href=/v1.5/about/community/customers/>Istio in Action</a></li></ul></li><li role=none><a role=treeitem title="List of features and their release stages." href=/v1.5/about/feature-stages/>Feature Status</a></li><li role=none><a role=treeitem title="How we manage, number, and support Istio releases." href=/v1.5/about/release-cadence/>Build & Release Cadence</a></li><li role=none><a role=treeitem title="What to do if you find a bug." href=/v1.5/about/bugs/>Reporting Bugs</a></li><li role=none><a role=treeitem title="How we handle security vulnerabilities." href=/v1.5/about/security-vulnerabilities/>Security Vulnerabilities</a></li><li role=none><a role=treeitem title="Official Istio resources for digital and printed materials." href=/v1.5/about/media-resources/>Media Resources</a></li><li role=none><a role=treeitem title="List of recent changes to this website." href=/v1.5/about/log/>Website Content Changes</a></li></ul></div></div></div></nav></div><div class=article-container><button tabindex=-1 id=sidebar-toggler title="Toggle the navigation bar"><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#pull"/></svg></button><nav aria-label=Breadcrumb><ol><li><a href=/v1.5/ title="Connect, secure, control, and observe services.">Istio</a></li><li><a href=/v1.5/about/ title="Get a bit more in-depth info about the Istio project.">About</a></li><li><a href=/v1.5/about/contribute/ title="Details how to create and maintain documentation pages.">Contribute Documentation to Istio</a></li><li>Add Code Blocks</li></ol></nav><article aria-labelledby=title><div class=title-area><div style=width:100%><h1 id=title>Add Code Blocks</h1><p class=byline><span title="1423 words"><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#clock"/></svg><span> </span>7 minute read</span></p></div></div><nav class=toc-inlined aria-label="Table of Contents"><div><hr><ol><li role=none aria-label="Add syntax highlighting"><a href=#add-syntax-highlighting>Add syntax highlighting</a><ol><li role=none aria-label="Supported syntax"><a href=#supported-syntax>Supported syntax</a></ol></li><li role=none aria-label="Dynamically import code into your document"><a href=#dynamically-import-code-into-your-document>Dynamically import code into your document</a><ol><li role=none aria-label="Import code from a file in the istio.io repository"><a href=#import-code-from-a-file-in-the-istio-io-repository>Import code from a file in the <code>istio.io</code> repository</a><li role=none aria-label="Import code from an external source through a URL"><a href=#import-code-from-an-external-source-through-a-url>Import code from an external source through a URL</a><li role=none aria-label="Import a code snippet from a larger file"><a href=#snippets>Import a code snippet from a larger file</a></ol></li><li role=none aria-label="Link to files in GitHub"><a href=#link-2-files>Link to files in GitHub</a><li role=none aria-label="Advanced features"><a href=#advanced-features>Advanced features</a><ol><li role=none aria-label="Download name"><a href=#download-name>Download name</a></ol></li><li role=none aria-label="See also"><a href=#see-also>See also</a></li></ol><hr></div></nav><p>Code blocks in the Istio documentation are embedded preformatted block of
|
|
content. We use Hugo to build our website, and it uses the <code>text</code> and
|
|
<code>text_import</code> shortcodes to add code to a page.</p><p>Using this markup allows us to provide our readers with a better experience.
|
|
The rendered code blocks can be easily copied, printed, or downloaded.</p><p>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.</p><p>The most common example of code blocks are Command Line Interface (CLI)
|
|
commands, for example:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text bash >}}
|
|
$ echo "Hello"
|
|
{{< /text >}}
|
|
</code></pre><p>The shortcode requires you to start each CLI command with a <code>$</code> and it renders the
|
|
content as follows:</p><pre><code class=language-bash data-expandlinks=true data-repo=istio>$ echo "Hello"
|
|
</code></pre><p>You can have multiple commands in a code block, but the shortcode only
|
|
recognizes a single output, for example:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text bash >}}
|
|
$ echo "Hello" >file.txt
|
|
$ cat file.txt
|
|
Hello
|
|
{{< /text >}}
|
|
</code></pre><p>By default and given the set <code>bash</code> attribute, the commands render using bash
|
|
syntax highlighting and the output renders as plain text, for example:</p><pre><code class=language-bash data-expandlinks=true data-repo=istio>$ echo "Hello" >file.txt
|
|
$ cat file.txt
|
|
Hello
|
|
</code></pre><p>For readability, you can use <code>\</code> to continue long commands on new lines, for example:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text bash >}}
|
|
$ echo "Hello" \
|
|
>file.txt
|
|
$ echo "There" >>file.txt
|
|
$ cat file.txt
|
|
Hello
|
|
There
|
|
{{< /text >}}
|
|
</code></pre><p>Hugo renders the multi-line command without issue:</p><pre><code class=language-bash data-expandlinks=true data-repo=istio>$ echo "Hello" \
|
|
>file.txt
|
|
$ echo "There" >>file.txt
|
|
$ cat file.txt
|
|
Hello
|
|
There
|
|
</code></pre><p>Your <span class=term data-title=Workload data-body='<p>A binary deployed by <a href="/docs/reference/glossary/#operator">operators</a> to deliver some function of a service mesh application.
|
|
Workloads have names, namespaces, and unique ids. These properties are available in policy and telemetry configuration
|
|
using the following <a href="/docs/reference/glossary/#attribute">attributes</a>:</p>
|
|
|
|
<ul>
|
|
<li><code>source.workload.name</code>, <code>source.workload.namespace</code>, <code>source.workload.uid</code></li>
|
|
<li><code>destination.workload.name</code>, <code>destination.workload.namespace</code>, <code>destination.workload.uid</code></li>
|
|
</ul>
|
|
|
|
<p>In Kubernetes, a workload typically corresponds to a Kubernetes deployment,
|
|
while a <a href="/docs/reference/glossary/#workload-instance">workload instance</a> corresponds to an individual <a href="/docs/reference/glossary/#pod">pod</a> managed
|
|
by the deployment.</p>'>workloads</span> can be coded in various
|
|
programming languages. Therefore, we have implemented support for multiple
|
|
combinations of syntax highlighting in code blocks.</p><h2 id=add-syntax-highlighting>Add syntax highlighting</h2><p>Let’s start with the following “Hello World” example:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text plain >}}
|
|
func HelloWorld() {
|
|
fmt.Println("Hello World")
|
|
}
|
|
{{< /text >}}
|
|
</code></pre><p>The <code>plain</code> attribute renders the code without syntax highlighting:</p><pre><code class=language-plain data-expandlinks=true data-repo=istio>func HelloWorld() {
|
|
fmt.Println("Hello World")
|
|
}
|
|
</code></pre><p>You can set the language of the code in the block to highlight its syntax. The
|
|
previous example set the syntax to <code>plain</code>, and the rendered code block doesn’t
|
|
have any syntax highlighting. However, you can set the syntax to GoLang, for
|
|
example:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text go >}}
|
|
func HelloWorld() {
|
|
fmt.Println("Hello World")
|
|
}
|
|
{{< /text >}}
|
|
</code></pre><p>Then, Hugo adds the appropriate highlighting:</p><pre><code class=language-go data-expandlinks=true data-repo=istio>func HelloWorld() {
|
|
fmt.Println("Hello World")
|
|
}
|
|
</code></pre><h3 id=supported-syntax>Supported syntax</h3><p>Code blocks in Istio support the following languages with syntax highlighting:</p><ul><li><code>plain</code></li><li><code>markdown</code></li><li><code>yaml</code></li><li><code>json</code></li><li><code>java</code></li><li><code>javascript</code></li><li><code>c</code></li><li><code>cpp</code></li><li><code>csharp</code></li><li><code>go</code></li><li><code>html</code></li><li><code>protobuf</code></li><li><code>perl</code></li><li><code>docker</code></li><li><code>bash</code></li></ul><p>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:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< 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 >}}
|
|
</code></pre><p>Renders the commands with bash syntax highlighting and the output with the
|
|
appropriate JASON syntax highlighting.</p><pre><code class=language-bash data-expandlinks=true data-outputis=json data-repo=istio>$ 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"}
|
|
</code></pre><h2 id=dynamically-import-code-into-your-document>Dynamically import code into your document</h2><p>The previous examples show how to format the code in your document.
|
|
However, you can use the <code>text_import</code> 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.</p><h3 id=import-code-from-a-file-in-the-istio-io-repository>Import code from a file in the <code>istio.io</code> repository</h3><p>Use the <code>file</code> attribute to import content from a file in the Istio
|
|
documentation repository, for example:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text_import file="test/snippet_example.txt" syntax="plain" >}}
|
|
</code></pre><p>The example above renders the content in the file as plain text:</p><pre><code class=language-plain data-expandlinks=true data-downloadas=snippet_example.txt data-repo=istio>BEFORE
|
|
|
|
# $snippet SNIP1
|
|
This is chunk 1
|
|
on two lines
|
|
# $endsnippet
|
|
|
|
# $snippet SNIP2
|
|
This is chunk 2
|
|
# $endsnippet
|
|
|
|
# $snippet SNIP1
|
|
This is chunk 3
|
|
# $endsnippet
|
|
|
|
AFTER
|
|
</code></pre><p>Set the language of the content through the <code>syntax=</code> field to get the
|
|
appropriate syntax highlighting.</p><h3 id=import-code-from-an-external-source-through-a-url>Import code from an external source through a URL</h3><p>Similarly, you can dynamically import content from the Internet. Use the <code>url</code>
|
|
attribute to specify the source. The following example imports the same file, but
|
|
from a URL:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text_import url="https://raw.githubusercontent.com/istio/istio.io/master/test/snippet_example.txt" syntax="plain" >}}
|
|
</code></pre><p>As you can see, the content is rendered in the same way as before:</p><div><a data-skipendnotes=true style=display:none href=https://raw.githubusercontent.com/istio/istio.io/master/test/snippet_example.txt>Zip</a><pre><code class=language-plain data-expandlinks=true data-downloadas=snippet_example.txt data-src=https://raw.githubusercontent.com/istio/istio.io/master/test/snippet_example.txt data-repo=istio></code></pre></div><p>If the file is from a different origin site, CORS should be enabled on that
|
|
site. Note the GitHub raw content site (<code>raw.githubusercontent.com</code>) may be used
|
|
here.</p><h3 id=snippets>Import a code snippet from a larger file</h3><p>Sometimes, you don’t need the contents of the entire file. You can control which
|
|
parts of the content to render using <em>named snippets</em>. Tag the code you want
|
|
in the snippet with comments containing the <code>$snippet SNIPPET_NAME</code> and
|
|
<code>$endsnippet</code> tags. The content between the two tags represents the snippet. For
|
|
example, take the following file:</p><pre><code class=language-plain data-expandlinks=true data-downloadas=snippet_example.txt data-repo=istio>BEFORE
|
|
|
|
# $snippet SNIP1
|
|
This is chunk 1
|
|
on two lines
|
|
# $endsnippet
|
|
|
|
# $snippet SNIP2
|
|
This is chunk 2
|
|
# $endsnippet
|
|
|
|
# $snippet SNIP1
|
|
This is chunk 3
|
|
# $endsnippet
|
|
|
|
AFTER
|
|
</code></pre><p>The file has three separate snippets: <code>SNIP1</code>, <code>SNIP2</code>, and <code>SNIP3</code>. The
|
|
convention is name snippets using all caps. To reference a specific snippet in
|
|
your document, set the value of the <code>snippet</code> attribute in the shortcode to the
|
|
name of the snippet, for example:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text_import file="test/snippet_example.txt" syntax="plain" snippet="SNIP1" >}}
|
|
</code></pre><p>The resulting code block only includes the code of the <code>SNIP1</code> snippet:</p><pre><code class=language-plain data-expandlinks=true data-downloadas=SNIP1 data-repo=istio>This is chunk 1
|
|
on two lines</code></pre><p>You can use the <code>syntax</code> attribute of the <code>text_import</code> shortcode to
|
|
specify the syntax of the snippet. For snippets containing CLI commands, you can
|
|
use the <code>outputis</code> attribute to specify the output’s syntax.</p><h2 id=link-2-files>Link to files in GitHub</h2><p>Some code blocks need to reference files from <a href=https://github.com/istio/istio>Istio’s GitHub repository</a>.
|
|
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 <code>@</code> symbols. This markup
|
|
renders the path should as a link to the file from the current release branch in
|
|
GitHub, for example:</p><div><a data-skipendnotes=true style=display:none href=https://raw.githubusercontent.com/istio/istio/release-1.5/samples/bookinfo/networking/virtual-service-reviews-v3.yaml>Zip</a><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text bash >}}
|
|
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
|
|
{{< /text >}}
|
|
</code></pre></div><p>The path renders as a link that takes you to the corresponding file:</p><div><a data-skipendnotes=true style=display:none href=https://raw.githubusercontent.com/istio/istio/release-1.5/samples/bookinfo/networking/virtual-service-reviews-v3.yaml>Zip</a><pre><code class=language-bash data-expandlinks=true data-repo=istio>$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
|
|
</code></pre></div><p>By default, these links point to the current release branch of the <code>istio/istio</code>
|
|
repository. For the link to point to a different Istio repository
|
|
instead, you can use the <code>repo</code> attribute, for example:</p><div><a data-skipendnotes=true style=display:none href=https://raw.githubusercontent.com/istio/istio/release-1.5/README.md>Zip</a><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text syntax="bash" repo="api" >}}
|
|
$ cat @README.md@
|
|
{{< /text >}}
|
|
</code></pre></div><p>The path renders as a link to the <code>README.md</code> file of the <code>istio/api</code> repository:</p><div><a data-skipendnotes=true style=display:none href=https://raw.githubusercontent.com/istio/api/release-1.5/README.md>Zip</a><pre><code class=language-bash data-expandlinks=true data-repo=api>$ cat @README.md@
|
|
</code></pre></div><p>Sometimes, your code block uses <code>@</code> for something else. You can turn the link
|
|
expansion on and off with the <code>expandlinks</code> attribute, for example:</p><div><a data-skipendnotes=true style=display:none href=https://raw.githubusercontent.com/istio/istio/release-1.5/samples/bookinfo/networking/virtual-service-reviews-v3.yaml>Zip</a><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text syntax="bash" expandlinks="false" >}}
|
|
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
|
|
{{< /text >}}
|
|
</code></pre></div><h2 id=advanced-features>Advanced features</h2><p>To use the more advanced features for preformatted content which are described
|
|
in the following sections, use the extended form of the <code>text</code> sequence
|
|
rather than the simplified form shown so far. The expanded form uses normal HTML
|
|
attributes:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< 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 >}}
|
|
</code></pre><p>The available attributes are:</p><table><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><code>file</code></td><td>The path of a file to show in the preformatted block.</td></tr><tr><td><code>url</code></td><td>The URL of a document to show in the preformatted block.</td></tr><tr><td><code>syntax</code></td><td>The syntax of the preformatted block.</td></tr><tr><td><code>outputis</code></td><td>When the syntax is <code>bash</code>, this specifies the command output’s syntax.</td></tr><tr><td><code>downloadas</code></td><td>The default file name used when the user <a href=#download-name>downloads the preformatted block</a>.</td></tr><tr><td><code>expandlinks</code></td><td>Whether or not to expand <a href=#link-2-files>GitHub file references</a> in the preformatted block.</td></tr><tr><td><code>snippet</code></td><td>The name of the <a href=#snippets>snippet</a> of content to extract from the preformatted block.</td></tr><tr><td><code>repo</code></td><td>The repository to use for <a href=#link-2-files>GitHub links</a> embedded in preformatted blocks.</td></tr></tbody></table><h3 id=download-name>Download name</h3><p>You can define the name used when someone chooses to download the code block
|
|
with the <code>downloadas</code> attribute, for example:</p><pre><code class=language-markdown data-expandlinks=true data-repo=istio>{{< text syntax="go" downloadas="hello.go" >}}
|
|
func HelloWorld() {
|
|
fmt.Println("Hello World")
|
|
}
|
|
{{< /text >}}
|
|
</code></pre><p>If you don’t specify a download name, Hugo derives one automatically based on
|
|
one of the following available possible names:</p><ul><li>The title of the current page for inline content</li><li>The name of the file containing the imported code</li><li>The URL of the source of the imported code</li></ul><nav id=see-also><h2>See also</h2><div class=see-also><div class=entry><p class=link><a data-skipendnotes=true href=/v1.5/about/contribute/terminology/>Terminology Standards</a></p><p class=desc>Explains the terminology standards used in the Istio documentation.</p></div><div class=entry><p class=link><a data-skipendnotes=true href=/v1.5/about/contribute/diagrams/>Diagram Creation Guidelines</a></p><p class=desc>Provides assets and instructions to create diagrams for the Istio documentation.</p></div><div class=entry><p class=link><a data-skipendnotes=true href=/v1.5/about/contribute/review/>Documentation Review Process</a></p><p class=desc>Shows you how changes to the Istio documentation and website are reviewed and approved.</p></div><div class=entry><p class=link><a data-skipendnotes=true href=/v1.5/blog/2019/sail-the-blog/>Sail the Blog!</a></p><p class=desc>Announces the new Istio blog policy.</p></div><div class=entry><p class=link><a data-skipendnotes=true href=/v1.5/about/contribute/add-content/>Add New Documentation</a></p><p class=desc>Details how to contribute new documentation to Istio.</p></div><div class=entry><p class=link><a data-skipendnotes=true href=/v1.5/about/contribute/build/>Build and serve the website locally</a></p><p class=desc>Explains how to locally build, test, serve, and preview the website.</p></div></div></nav></article><nav class=pagenav><div class=left><a title="Shows you how changes to the Istio documentation and website are reviewed and approved." href=/v1.5/about/contribute/review/><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#left-arrow"/></svg>Documentation Review Process</a></div><div class=right><a title="Explains the shortcodes available and how to use them." href=/v1.5/about/contribute/shortcodes/>Use Shortcodes<svg class="icon"><use xlink:href="/v1.5/img/icons.svg#right-arrow"/></svg></a></div></nav><div id=feedback><div id=feedback-initial>Was this information useful?<br><button class="btn feedback" onclick="sendFeedback('en',1)">Yes</button>
|
|
<button class="btn feedback" onclick="sendFeedback('en',0)">No</button></div><div id=feedback-comment>Do you have any suggestions for improvement?<br><br><input id=feedback-textbox type=text placeholder="Help us improve..." data-lang=en></div><div id=feedback-thankyou>Thanks for your feedback!</div></div><div id=endnotes-container aria-hidden=true><h2>Links</h2><ol id=endnotes></ol></div></div><div class=toc-container><nav class=toc aria-label="Table of Contents"><div id=toc><ol><li role=none aria-label="Add syntax highlighting"><a href=#add-syntax-highlighting>Add syntax highlighting</a><ol><li role=none aria-label="Supported syntax"><a href=#supported-syntax>Supported syntax</a></ol></li><li role=none aria-label="Dynamically import code into your document"><a href=#dynamically-import-code-into-your-document>Dynamically import code into your document</a><ol><li role=none aria-label="Import code from a file in the istio.io repository"><a href=#import-code-from-a-file-in-the-istio-io-repository>Import code from a file in the <code>istio.io</code> repository</a><li role=none aria-label="Import code from an external source through a URL"><a href=#import-code-from-an-external-source-through-a-url>Import code from an external source through a URL</a><li role=none aria-label="Import a code snippet from a larger file"><a href=#snippets>Import a code snippet from a larger file</a></ol></li><li role=none aria-label="Link to files in GitHub"><a href=#link-2-files>Link to files in GitHub</a><li role=none aria-label="Advanced features"><a href=#advanced-features>Advanced features</a><ol><li role=none aria-label="Download name"><a href=#download-name>Download name</a></ol></li><li role=none aria-label="See also"><a href=#see-also>See also</a></li></ol></div></nav></div></main><footer><div class=user-links><a class=channel title="Go download Istio 1.5.4 now" href=/v1.5/docs/setup/getting-started/#download aria-label="Download Istio"><span>download</span><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#download"/></svg>
|
|
</a><a class=channel title="Join the Istio discussion board to participate in discussions and get help troubleshooting problems" href=https://discuss.istio.io aria-label="Istio discussion board"><span>discuss</span><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#discourse"/></svg></a>
|
|
<a class=channel title="Stack Overflow is where you can ask questions and find curated answers on deploying, configuring, and using Istio" href=https://stackoverflow.com/questions/tagged/istio aria-label="Stack Overflow"><span>stack overflow</span><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#stackoverflow"/></svg></a>
|
|
<a class=channel title="Interactively discuss issues with the Istio community on Slack" href=https://istio.slack.com aria-label=slack><span>slack</span><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#slack"/></svg></a>
|
|
<a class=channel title="Follow us on Twitter to get the latest news" href=https://twitter.com/IstioMesh aria-label=Twitter><span>twitter</span><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#twitter"/></svg></a><div class=tag>for everyone</div></div><div class=info><p class=copyright>Istio Archive
|
|
1.5.4<br>© 2020 Istio Authors, <a href=https://policies.google.com/privacy>Privacy Policy</a><br>Archived on May 21, 2020</p></div><div class=dev-links><a class=channel title="GitHub is where development takes place on Istio code" href=https://github.com/istio/community aria-label=GitHub><span>github</span><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#github"/></svg></a>
|
|
<a class=channel title="Access our team drive if you'd like to take a look at the Istio technical design documents" href=https://groups.google.com/forum/#!forum/istio-team-drive-access aria-label="team drive"><span>drive</span><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#drive"/></svg></a>
|
|
<a class=channel title="If you'd like to contribute to the Istio project, consider participating in our working groups" href=https://github.com/istio/community/blob/master/WORKING-GROUPS.md aria-label="working groups"><span>working groups</span><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#working-groups"/></svg></a><div class=tag>for developers</div></div></footer><script src=https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js defer></script><div id=scroll-to-top-container aria-hidden=true><button id=scroll-to-top title="Back to top"><svg class="icon"><use xlink:href="/v1.5/img/icons.svg#top"/></svg></button></div></body></html> |