istio.io/archive/v1.9/about/contribute/build/index.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="Build and serve the website locally"><meta name=description content="Explains how to locally build, test, serve, and preview the website."><meta name=keywords content="microservices,services,mesh,contribute,serve,Docker,Hugo,build"><meta property="og:title" content="Build and serve the website locally"><meta property="og:type" content="website"><meta property="og:description" content="Explains how to locally build, test, serve, and preview the website."><meta property="og:url" content="/v1.9/about/contribute/build/"><meta property="og:image" content="/v1.9/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.9 / Build and serve the website locally</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.9/blog/feed.xml><link rel=alternate type=application/rss+xml title="Istio News" href=/v1.9/news/feed.xml><link rel=alternate type=application/rss+xml title="Istio Blog and News" href=/v1.9/feed.xml><link rel="shortcut icon" href=/v1.9/favicons/favicon.ico><link rel=apple-touch-icon href=/v1.9/favicons/apple-touch-icon-180x180.png sizes=180x180><link rel=icon type=image/png href=/v1.9/favicons/favicon-16x16.png sizes=16x16><link rel=icon type=image/png href=/v1.9/favicons/favicon-32x32.png sizes=32x32><link rel=icon type=image/png href=/v1.9/favicons/android-36x36.png sizes=36x36><link rel=icon type=image/png href=/v1.9/favicons/android-48x48.png sizes=48x48><link rel=icon type=image/png href=/v1.9/favicons/android-72x72.png sizes=72x72><link rel=icon type=image/png href=/v1.9/favicons/android-96x96.png sizes=96xW96><link rel=icon type=image/png href=/v1.9/favicons/android-144x144.png sizes=144x144><link rel=icon type=image/png href=/v1.9/favicons/android-192x192.png sizes=192x192><link rel=manifest href=/v1.9/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.9/css/all.css><script src=/v1.9/js/themes_init.min.js></script></head><body class="language-unknown archive-site"><script>const branchName="release-1.9";const docTitle="Build and serve the website locally";const iconFile="\/v1.9/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.9/js/all.min.js data-manual defer></script><header><nav><a id=brand href=/v1.9/><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.9</span></a><div id=hamburger><svg class="icon hamburger"><use xlink:href="/v1.9/img/icons.svg#hamburger"/></svg></div><div id=header-links><a title="Learn how to deploy, use, and operate Istio." href=/v1.9/docs/>Docs</a>
<a title="Posts about using Istio." href=/v1.9/blog/2021/>Blog<i class=dot data-prefix=/blog></i></a>
<a title="Timely news about the Istio project." href=/v1.9/news/>News<i class=dot data-prefix=/news></i></a>
<a title="Frequently Asked Questions about Istio." href=/v1.9/faq/>FAQ</a>
<a class=current title="Get a bit more in-depth info about the Istio project." href=/v1.9/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 gear"><use xlink:href="/v1.9/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\/build\/');return false;">Current Release</a>
<a tabindex=-1 role=menuitem onclick="navigateToUrlOrRoot('https://preliminary.istio.io/about\/contribute\/build\/');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 magnifier"><use xlink:href="/v1.9/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.9/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 cancel-x"><use xlink:href="/v1.9/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 about"><use xlink:href="/v1.9/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="Our Community"><button aria-hidden=true></button><a title="Learn about our community, our customers, and our partners." href=/v1.9/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.9/about/community/join/>Getting Involved</a></li><li role=none><a role=treeitem title="Who's building stuff around Istio." href=/v1.9/about/community/partners/>Partners</a></li><li role=none><a role=treeitem title="Some of the companies that have adopted Istio." href=/v1.9/about/community/customers/>Who's using Istio</a></li></ul></li><li role=none><a role=treeitem title="List of features and their release stages." href=/v1.9/about/feature-stages/>Feature Status</a></li><li role=none><a role=treeitem title="What to do if you find a bug." href=/v1.9/about/bugs/>Reporting Bugs</a></li><li role=none><a role=treeitem title="How we handle security vulnerabilities." href=/v1.9/about/security-vulnerabilities/>Security Vulnerabilities</a></li><li role=none><a role=treeitem title="The currently supported Istio releases." href=/v1.9/about/supported-releases/>Supported Releases</a></li><li role=none><a role=treeitem title="Official Istio resources for digital and printed materials." href=/v1.9/about/media-resources/>Media Resources</a></li><li role=treeitem aria-label="Contribute Documentation"><button class=show aria-hidden=true></button><a title="Details how to create and maintain Istio documentation pages." href=/v1.9/about/contribute/>Contribute Documentation</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.9/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.9/about/contribute/add-content/>Add New Documentation</a></li><li role=none><a role=treeitem title="Details how to contribute retired documentation to Istio." href=/v1.9/about/contribute/remove-content/>Remove Retired Documentation</a></li><li role=none><span role=treeitem class=current title="Explains how to locally build, test, serve, and preview the website.">Build and serve the website locally</span></li><li role=none><a role=treeitem title="Explains the front matter used in our documentation and the fields available." href=/v1.9/about/contribute/front-matter/>Front matter</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.9/about/contribute/review/>Documentation Review Process</a></li><li role=none><a role=treeitem title="Explains how to include code in your documentation." href=/v1.9/about/contribute/code-blocks/>Add Code Blocks</a></li><li role=none><a role=treeitem title="Explains the shortcodes available and how to use them." href=/v1.9/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.9/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.9/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.9/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.9/about/contribute/diagrams/>Diagram Creation Guidelines</a></li></ul></li><li role=none><a role=treeitem title="List of recent changes to this website." href=/v1.9/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 pull"><use xlink:href="/v1.9/img/icons.svg#pull"/></svg></button><nav aria-label=Breadcrumb><ol><li><a href=/v1.9/ title="Connect, secure, control, and observe services.">Istio</a></li><li><a href=/v1.9/about/ title="Get a bit more in-depth info about the Istio project.">About</a></li><li><a href=/v1.9/about/contribute/ title="Details how to create and maintain Istio documentation pages.">Contribute Documentation</a></li><li>Build and serve the website locally</li></ol></nav><article aria-labelledby=title><div class=title-area><div style=width:100%><h1 id=title>Build and serve the website locally</h1><p class=byline><span title="489 words"><svg class="icon clock"><use xlink:href="/v1.9/img/icons.svg#clock"/></svg><span>&nbsp;</span>3 minute read</span>
<span>&nbsp;</span>
<span></span></p></div></div><nav class=toc-inlined aria-label="Table of Contents"><div><hr><ol><li role=none aria-label="Before you begin"><a href=#before-you-begin>Before you begin</a><li role=none aria-label="Preview your changes"><a href=#preview-your-changes>Preview your changes</a><ol><li role=none aria-label="Test your changes"><a href=#test-your-changes>Test your changes</a></ol></li><li role=none aria-label="See also"><a href=#see-also>See also</a></li></ol><hr></div></nav><p>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.</p><h2 id=before-you-begin>Before you begin</h2><p>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: <a href=https://gohugo.io/>Hugo</a>.</p><p>To build, test, and preview the site locally, you need to install
<a href=https://www.docker.com/get-started>Docker</a> on your system.</p><h2 id=preview-your-changes>Preview your changes</h2><p>To preview your changes to the site, go to the root of your fork of
<code>istio/istio.io</code> and run the following command:</p><pre><code class=language-bash data-expandlinks=true data-repo=istio>$ make serve
</code></pre><p>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
<code>http://localhost:1313</code> on your web browser.</p><p>If you need to make and serve the site from a remote server, you can use
<code>ISTIO_SERVE_DOMAIN</code> to provide the IP address or DNS Domain of the server, for
example:</p><pre><code class=language-bash data-expandlinks=true data-repo=istio>$ make ISTIO_SERVE_DOMAIN=192.168.7.105 serve
</code></pre><p>The example builds the site and starts a web server, which hosts the site on the
remote server at the <code>192.168.7.105</code> IP address. Like before, you can then
connect to the web server at <code>http://192.168.7.105:1313</code>.</p><h3 id=test-your-changes>Test your changes</h3><p>We use linters and tests to ensure a quality baseline for the site&rsquo;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:</p><ul><li><p>HTML proofing: ensures all links are valid along with other checks.</p></li><li><p>Spell check: ensures content is spelled correctly.</p></li><li><p>Markdown Style check: ensures the markup used complies with our Markdown style
rules.</p></li></ul><p>To run these checks locally, use the following command:</p><pre><code class=language-bash data-expandlinks=true data-repo=istio>$ make lint
</code></pre><p>If the spell checker reports errors, the following are the most likely causes:</p><ul><li><p>A real typo: Fix the typo on your Markdown files.</p></li><li><p>The error is reported for a command, field, or symbol name: Place
`back-ticks` around the content with the error.</p></li><li><p>The error is reported for a correct word or proper name not present in the
tool&rsquo;s dictionary: Add the word to the <code>.spelling</code> file at the root of the
<code>istio/istio.io</code> repository.</p></li></ul><p>Due to poor Internet connectivity, you could have trouble with the link checker.
If you can&rsquo;t get good connectivity, you can set the checker to prevent it from
checking external links. Set the <code>INTERNAL_ONLY</code> environment variable to <code>True</code>
when running the linter, for example:</p><pre><code class=language-bash data-expandlinks=true data-repo=istio>$ make INTERNAL_ONLY=True lint
</code></pre><p>When your content passes all the checks, submit it to the repository through a
PR. Visit <a href=/v1.9/about/contribute/github>Working with GitHub</a> for more
information.</p><nav id=see-also><h2>See also</h2><div class=see-also><div class=entry><p class=link><a data-skipendnotes=true href=/v1.9/about/contribute/code-blocks/>Add Code Blocks</a></p><p class=desc>Explains how to include code in your documentation.</p></div><div class=entry><p class=link><a data-skipendnotes=true href=/v1.9/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.9/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.9/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.9/about/contribute/formatting/>Follow Formatting Standards</a></p><p class=desc>Explains the standard markup used to format Istio documentation.</p></div><div class=entry><p class=link><a data-skipendnotes=true href=/v1.9/about/contribute/remove-content/>Remove Retired Documentation</a></p><p class=desc>Details how to contribute retired documentation to Istio.</p></div></div></nav></article><nav class=pagenav><div class=left><a title="Details how to contribute retired documentation to Istio." href=/v1.9/about/contribute/remove-content/><svg class="icon left-arrow"><use xlink:href="/v1.9/img/icons.svg#left-arrow"/></svg>Remove Retired Documentation</a></div><div class=right><a title="Explains the front matter used in our documentation and the fields available." href=/v1.9/about/contribute/front-matter/>Front matter<svg class="icon right-arrow"><use xlink:href="/v1.9/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="Before you begin"><a href=#before-you-begin>Before you begin</a><li role=none aria-label="Preview your changes"><a href=#preview-your-changes>Preview your changes</a><ol><li role=none aria-label="Test your changes"><a href=#test-your-changes>Test your changes</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.9.5 now" href=/v1.9/docs/setup/getting-started/#download aria-label="Download Istio"><span>download</span><svg class="icon download"><use xlink:href="/v1.9/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 discourse"><use xlink:href="/v1.9/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 stackoverflow"><use xlink:href="/v1.9/img/icons.svg#stackoverflow"/></svg></a>
<a class=channel title="Interactively discuss issues with the Istio community on Slack" href=https://slack.istio.io aria-label=slack><span>slack</span><svg class="icon slack"><use xlink:href="/v1.9/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 twitter"><use xlink:href="/v1.9/img/icons.svg#twitter"/></svg></a><div class=tag>for everyone</div></div><div class=info><p class=copyright>Istio Archive
1.9.5<br>&copy; 2020 Istio Authors, <a href=https://policies.google.com/privacy>Privacy Policy</a><br>Archived on May 18, 2021</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 github"><use xlink:href="/v1.9/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 drive"><use xlink:href="/v1.9/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 working-groups"><use xlink:href="/v1.9/img/icons.svg#working-groups"/></svg></a><div class=tag>for developers</div></div></footer><div id=scroll-to-top-container aria-hidden=true><button id=scroll-to-top title="Back to top"><svg class="icon top"><use xlink:href="/v1.9/img/icons.svg#top"/></svg></button></div></body></html>