mirror of https://github.com/istio/istio.io.git
61 lines
21 KiB
HTML
61 lines
21 KiB
HTML
<!DOCTYPE html><html lang="en" itemscope itemtype="https://schema.org/WebPage" style="overflow-y: scroll;"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="title" content="Writing a New Topic"><meta name="og:title" content="Writing a New Topic"><meta name="og:image" content="/v0.3/img/logo.png"/><meta name="theme-color" content="#466BB0"/><meta name="description" content="Explains the mechanics of creating new documentation pages."><meta name="og:description" content="Explains the mechanics of creating new documentation pages."><title>Istioldie 0.3 / Writing a New Topic</title><script> window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date; ga('create', 'UA-98480406-2', 'auto'); ga('send', 'pageview'); </script> <script async src='https://www.google-analytics.com/analytics.js'></script><link rel="alternate" type="application/rss+xml" title="Istio Blog RSS" href="/v0.3/feed.xml"><link rel="shortcut icon" href="/v0.3/favicons/favicon.ico" ><link rel="apple-touch-icon" href="/v0.3/favicons/apple-touch-icon-180x180.png" sizes="180x180"><link rel="icon" type="image/png" href="/v0.3/favicons/favicon-16x16.png" sizes="16x16"><link rel="icon" type="image/png" href="/v0.3/favicons/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="/v0.3/favicons/android-36x36.png" sizes="36x36"><link rel="icon" type="image/png" href="/v0.3/favicons/android-48x48.png" sizes="48x48"><link rel="icon" type="image/png" href="/v0.3/favicons/android-72x72.png" sizes="72x72"><link rel="icon" type="image/png" href="/v0.3/favicons/android-96x196.png" sizes="96x196"><link rel="icon" type="image/png" href="/v0.3/favicons/android-144x144.png" sizes="144x144"><link rel="icon" type="image/png" href="/v0.3/favicons/android-192x192.png" sizes="192x192"><link rel="manifest" href="/v0.3/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=Roboto:400,100,100italic,300,300italic,400italic,500,500italic,700,700italic,900,900italic"><link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"><link rel="stylesheet" href="/v0.3/css/all.css"><link rel="stylesheet" href="/v0.3/css/prism.css"></head><body class="language-unknown"> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script><div class="nav-hero-container" style="z-index: 200000;"><nav id="header-nav" class="navbar navbar-inverse" role="navigation" style="z-index: 200000;"><div class="container"><div class="row"><div class="col-md-11 nofloat center-block "><div class="navbar-header"> <button type="button" class="hamburger navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-collapse-1" aria-expanded="false"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="/v0.3/"><div> <img src="/v0.3/img/istio-logo.svg" alt="Istio Logo" height="54px"/> <span class="brand-name">Istioldie 0.3</span></div></a></div><div class="collapse navbar-collapse" id="navbar-collapse-1"><ul class="nav navbar-nav navbar-right"><li><a href="/v0.3/about" >About</a></li><li><a href="/v0.3/blog" >Blog</a></li><li><a href="/v0.3/docs/welcome" class='current'>Docs</a></li><li><a href="/v0.3/help" >Help</a></li><li><a href="/v0.3/community" >Community</a></li><li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown" href=""> <i class='fa fa-lg fa-cog'></i> <span class="caret"></span> </a><ul class="dropdown-menu"><h6 class="dropdown-header">Other versions of this site</h6><li> <a href="https://istio.io">Current Release</a></li><li> <a href="https://preliminary.istio.io">Next Release</a></li><li> <a href="https://archive.istio.io">Older Releases</a></li></ul></li><li><form name="cse" id="searchbox_demo" class="navbar-form navbar-right" role="search"> <input type="hidden" name="cx" value="013699703217164175118:iwwf17ikgf4" /> <input type="hidden" name="ie" value="utf-8" /> <input type="hidden" name="hl" value="en" /><div class="form-group"><div class="input-group"> <input name="q" class="form-control search-box" type="text" size="30" /><div class="input-group-addon"> <span class="btn-search glyphicon glyphicon-search"></span></div></div></div></form> <script type="text/javascript" src="https://www.google.com/cse/brand?form=searchbox_demo"></script></li></ul></div></div></div></div></nav></div><div class="container"><div class="row"><div class="col-md-11 nofloat center-block" style="margin-top: 3px;"><ul class="col-sm-10 nav nav-tabs"><li role="presentation" class='active'><a href="/v0.3/docs/welcome/">Welcome</a></li><li role="presentation" ><a href="/v0.3/docs/concepts/">Concepts</a></li><li role="presentation" ><a href="/v0.3/docs/setup/">Setup</a></li><li role="presentation" ><a href="/v0.3/docs/tasks/">Tasks</a></li><li role="presentation" ><a href="/v0.3/docs/guides/">Guides</a></li><li role="presentation" ><a href="/v0.3/docs/reference/">Reference</a></li></ul></div></div></div><script src="/v0.3/js/navtree.min.js"></script><div class="container docs"><div class="row"><div class="col-md-11 nofloat center-block"><div class="row"><div id="sidebar-container" class="col-sm-3"><ul class="doc-side-nav"><li><h5 class='doc-side-nav-title'>Welcome</h5></li><script type="text/javascript"> var docs = []; docs.push({path: [ "contribute", "creating-a-pull-request.md", ], url: "/docs/welcome/contribute/creating-a-pull-request.html", title: "Creating a Pull Request", order: 20, overview: "Shows you how to create a GitHub pull request in order to submit your docs for approval."}); docs.push({path: [ "contribute", "editing.md", ], url: "/docs/welcome/contribute/editing.html", title: "Editing Docs", order: 10, overview: "Lets you start editing this site's documentation."}); docs.push({path: [ "contribute", "index.md", ], url: "/docs/welcome/contribute/", title: "Contributing to the Docs", order: 100, overview: "Learn how to contribute to improve and expand the Istio documentation."}); docs.push({path: [ "contribute", "reviewing-doc-issues.md", ], url: "/docs/welcome/contribute/reviewing-doc-issues.html", title: "Doc Issues", order: 60, overview: "Explains the process involved in accepting documentation updates."}); docs.push({path: [ "contribute", "staging-your-changes.md", ], url: "/docs/welcome/contribute/staging-your-changes.html", title: "Staging Your Changes", order: 40, overview: "Explains how to test your changes locally before submitting them."}); docs.push({path: [ "contribute", "style-guide.md", ], url: "/docs/welcome/contribute/style-guide.html", title: "Style Guide", order: 70, overview: "Explains the dos and donts of writing Istio docs."}); docs.push({path: [ "contribute", "writing-a-new-topic.md", ], url: "/docs/welcome/contribute/writing-a-new-topic.html", title: "Writing a New Topic", order: 30, overview: "Explains the mechanics of creating new documentation pages."}); docs.push({path: [ "faq.md", ], url: "/docs/welcome/faq.html", title: "Frequently Asked Questions", order: 20, overview: "Frequently Asked Questions about Istio."}); docs.push({path: [ "feature-stages.md", ], url: "/docs/welcome/feature-stages.html", title: "Feature Status", order: 10, overview: "List of features and their release stages."}); docs.push({path: [ "glossary.md", ], url: "/docs/welcome/glossary.html", title: "Glossary", order: 30, overview: "A glossary of common Istio terms."}); docs.push({path: [ "index.md", ], url: "/docs/welcome/", title: "Welcome", order: 0, overview: "Istio documentation home page."}); docs.push({path: [ "notes", "0.1.md", ], url: "/docs/welcome/notes/0.1.html", title: "Istio 0.1", order: 100, overview: ""}); docs.push({path: [ "notes", "0.2.md", ], url: "/docs/welcome/notes/0.2.html", title: "Istio 0.2", order: 99, overview: ""}); docs.push({path: [ "notes", "0.3.md", ], url: "/docs/welcome/notes/0.3.html", title: "Istio 0.3", order: 98, overview: ""}); docs.push({path: [ "notes", "index.md", ], url: "/docs/welcome/notes/", title: "Release Notes", order: 5, overview: "What's been happening with Istio."}); genNavBarTree(docs) </script></ul></div><div id="tab-container" class="col-xs-1 tab-neg-margin pull-left"> <a id="sidebar-tab" class="glyphicon glyphicon-chevron-left" href="javascript:void 0;"> </a></div><div id="content-container" class="thin-left-border col-sm-9 markdown"><div id="toc" class="toc"></div><div id="doc-content"><h1>Writing a New Topic</h1><p>This page shows how to create a new Istio documentation topic.</p><h2 id="before-you-begin">Before you begin</h2><p>You first need to create a fork of the Istio documentation repository as described in <a href="./creating-a-pull-request.html">Creating a Doc Pull Request</a>.</p><h2 id="choosing-a-page-type">Choosing a page type</h2><p>As you prepare to write a new topic, think about which of these page types is the best fit for your content:</p><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 or tutorials 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>Guides</td><td>A guide page describes a fully working stand-alone example highlighting a particular set of features. Guides must have easy to follow setup and usage instructions so users can quickly run the sample themselves and experiment with changing the sample to explore the system.</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.</td></tr></table><p>Each page type has a template file located in the corresponding directory which shows you the basic structure expected for topics of that type. Please start new documents by copying the template.</p><h2 id="naming-a-topic">Naming a topic</h2><p>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.</p><p>For example, the topic with title TBD (<code>[TBD](/docs/tasks/tbd.html)</code>) has filename <code>tbd.md</code>. You don’t need to put “Istio” in the filename, because “Istio” is already in the URL for the topic, for example:</p><pre><code>/v0.3/docs/tasks/tbd.html
|
||
</code></pre><h2 id="updating-the-front-matter">Updating the front matter</h2><p>Every documentation file needs to start with Jekyll <a href="https://jekyllrb.com/docs/frontmatter/">front matter</a>. The front matter is a block of YAML that is between the triple-dashed lines at the top of each file. Here’s the chunk of front matter you should start with:</p><pre><code>---
|
||
title: <title>
|
||
overview: <overview>
|
||
|
||
order: <order>
|
||
|
||
layout: docs
|
||
type: markdown
|
||
---
|
||
</code></pre><p>Copy the above at the start of your new markdown file and update the <code><title></code>, <code><overview></code> and <code><order></code> fields for your particular file. The available front matter fields are:</p><table><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><code>title</code></td><td>The short title of the page</td></tr><tr><td><code>overview</code></td><td>a one-line description of what the topic is about</td></tr><tr><td><code>order</code></td><td>integer used for sort order</td></tr><tr><td><code>layout</code></td><td>indicates which of the Jekyll layouts this page uses</td></tr><tr><td><code>index</code></td><td>indicates whether the page should appear in the doc’s top nav tabs</td></tr></tbody></table><h2 id="choosing-a-directory">Choosing a directory</h2><p>Depending on your page type, put your new file in a subdirectory of one of these:</p><ul><li>_docs/concepts/</li><li>_docs/reference/</li><li>_docs/guides/</li><li>_docs/tasks/</li></ul><p>You can put your file in an existing subdirectory, or you can create a new subdirectory.</p><h2 id="adding-images-to-a-topic">Adding images to a topic</h2><p>Put image files in an <code>img</code> subdirectory of where you put your markdown file. The preferred image format is SVG.</p><p>If you must use a PNG or JPEG file instead, and the file was generated from an original SVG file, please include the SVG file in the repository even if it isn’t used in the web site itself. This is so we can update the imagery over time if needed.</p><p>Within markdown, use the <code>figure</code> element to add the image:</p><pre><code class="language-html"><figure>
|
||
<img src="./img/myfile.svg" alt="Some description for accessibility" titla="A title displayed as a tooltip"/>
|
||
<figcaption>A caption displayed under the image</figcaption>
|
||
</figure>
|
||
</code></pre><p>This will insert the image centered with a width of 75% and the given caption under it. You can adjust the width using a style element such as:</p><pre><code class="language-html"><figure>
|
||
<img style="max-width: 32%;" src="./img/myfile.svg" alt="Some description for accessibility" titla="A title displayed as a tooltip"/>
|
||
<figcaption>A caption displayed under the image</figcaption>
|
||
</figure>
|
||
</code></pre><h2 id="linking-to-other-pages">Linking to other pages</h2><p>There are three types of links that can be included in documentation. Each uses a different way to indicate the link target:</p><ul><li><p><strong>Internet Link</strong>. You use classic URL syntax, preferably with the HTTPS protocol, to reference files on the Internet:</p><pre><code class="language-markdown">[see here](https://mysite/myfile.html)
|
||
</code></pre></li><li><p><strong>Relative Link</strong>. 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:</p><pre><code class="language-markdown">[see here](./adir/anotherfile.html)
|
||
</code></pre></li><li><p><strong>Absolute Link</strong>. You use absolute links with the special {{home}} notation to reference content outside of the current hierarchy:</p><pre><code class="language-markdown">[see here]({{home}}/docs/adir/afile.html)
|
||
</code></pre><p>In order to use {{home}} in a file, you need to make sure that the file contains the following line of boilerplate right after the block of front matter:</p><pre><code class="language-markdown">...
|
||
---
|
||
{% include home.html %}
|
||
</code></pre><p>Adding this include statement is what defines the <code>home</code> variable that is used in the link target.</p></li></ul><h2 id="embedding-preformatted-blocks">Embedding preformatted blocks</h2><p>You can embed blocks of preformatted content using the normal markdown technique:</p><pre class="language-markdown"><code>```
|
||
func HelloWorld() {
|
||
fmt.Println("Hello World")
|
||
}
|
||
```
|
||
</code></pre><p>The above produces this kind of output:</p><pre><code>func HelloWorld() {
|
||
fmt.Println("Hello World")
|
||
}
|
||
</code></pre><p>In general, you should indicate the nature of the content in the preformatted block. You do this by appending a name after the initial set of tick marks</p><pre class="language-markdown"><code>```go
|
||
func HelloWorld() {
|
||
fmt.Println("Hello World")
|
||
}
|
||
```
|
||
</code></pre><p>The above indicates the content is Go source code, which will lead to appropriate syntax coloring as shown here:</p><pre><code class="language-go">func HelloWorld() {
|
||
fmt.Println("Hello World")
|
||
}
|
||
</code></pre><p>You can use <code>markdown</code>, <code>yaml</code>, <code>json</code>, <code>java</code>, <code>javascript</code>, <code>c</code>, <code>cpp</code>, <code>csharp</code>, <code>go</code>, <code>html</code>, <code>protobuf</code>, and <code>bash</code>.</p><h3 id="displaying-file-content">Displaying file content</h3><p>You can pull in an external file and display its content as a preformatted block. This is handy to display a config file or a test file. To do so, you can’t use normal markup and instead you need to use direct HTML. For example:</p><pre><code><pre data-src="https://raw.githubusercontent.com/istio/istio/master/BUILD"></pre>
|
||
</code></pre><p>which produces the following result:</p><pre data-src="https://raw.githubusercontent.com/istio/istio/master/BUILD"></pre><p>The <code>data-src</code> attribute specifies the path to the file to display. <a href="http://prismjs.com/">PrismJS</a> fetches the file using XMLHttpRequest. If the file is from a different origin site, CORS should be enabled on that site. Note that the github raw content site (<code>raw.githubusercontent.com</code>) is CORS enabled so it may be used here.</p><h3 id="highlighting-lines">Highlighting lines</h3><p>You can highlight specific lines in a preformatted block using the <code>data-line</code> attribute:</p><pre><code><pre data-line="3"><code>This is a test
|
||
This is a test
|
||
This is a test
|
||
This is a test
|
||
</code></pre>
|
||
</code></pre><p>which produces the following result:</p><pre data-line="3"><code>This is a test
|
||
This is a test
|
||
This is a test
|
||
This is a test
|
||
</code></pre><p>See <a href="http://prismjs.com/plugins/line-highlight/">here</a> for information on how to highlight multiple lines and ranges.</p><h3 id="displaying-line-numbers">Displaying line numbers</h3><p>You can display line numbers for all lines in a preformatted block using the <code>line-numbers</code> class:</p><pre><code><pre class="line-numbers"><code>This is a test
|
||
This is a test
|
||
This is a test
|
||
This is a test
|
||
</code></pre>
|
||
</code></pre><p>which produces the following result:</p><pre class="line-numbers"><code>This is a test
|
||
This is a test
|
||
This is a test
|
||
This is a test
|
||
</code></pre><p>See <a href="http://prismjs.com/plugins/line-numbers/">here</a> for information on how to control some line numbering options.</p></div></div></div></div></div></div><script src="/v0.3/js/sidemenu.min.js"></script><footer><div class="container"><div class="row"><div class="col-lg-2 col-md-2 col-sm-2"></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li><a class="header" href="/v0.3/docs/welcome">Docs</a></li><li><a href="/v0.3/docs/concepts">Concepts</a></li><li><a href="/v0.3/docs/setup">Setup</a></li><li><a href="/v0.3/docs/tasks">Tasks</a></li><li><a href="/v0.3/docs/guides">Guides</a></li><li><a href="/v0.3/docs/reference">Reference</a></li></ul></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li><a class="header" href="/v0.3/help">Help</a></li><li><a href="/v0.3/faq">FAQ</a></li><li><a href="/v0.3/glossary">Glossary</a></li><li><a href="/v0.3/troubleshooting">Troubleshooting</a></li><li><a href="/v0.3/bugs">Report Bugs</a></li><li><a href="https://github.com/istio/istio.github.io/issues/new?title=Issue with _docs/welcome/contribute/writing-a-new-topic.md">Doc Bugs & Gaps</a></li><li><a href="https://github.com/istio/istio.github.io/edit/master/_docs/welcome/contribute/writing-a-new-topic.md">Edit This Page</a></li></ul></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li> <a class="header" href="/v0.3/community">Community</a></li><li> <a href="https://groups.google.com/forum/#!forum/istio-users" target="_blank" rel="noopener">User</a> | <a href="https://groups.google.com/forum/#!forum/istio-dev" target="_blank" rel="noopener">Dev Mailing Lists</a></li><li><a href="https://twitter.com/IstioMesh" target="_blank" rel="noopener">Twitter</a></li><li><a href="https://stackoverflow.com/questions/tagged/istio" target="_blank" rel="noopener">Stack Overflow</a></li><li><a href="https://github.com/istio/community" target="_blank" rel="noopener">GitHub</a></li><li><a href="https://github.com/istio/community/blob/master/WORKING-GROUPS.md" target="_blank" rel="noopener">Working Groups</a></li></ul></div><div class="col-lg-1 col-md-1 col-sm-1"></div></div><div class="row"><p class="description small text-center"> Istio 0.3, Copyright © 2017 Istio Authors<br> Archived on 08-Dec-2017</p></div></div></footer><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-validate/1.15.0/jquery.validate.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.form/4.2.1/jquery.form.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-visible/1.2.0/jquery.visible.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/slick-carousel/1.6.0/slick.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script> <script src="/v0.3/js/common.min.js"></script> <script src="/v0.3/js/search.js"></script> <script src="/v0.3/js/prism.min.js"></script></body></html>
|