Prepare for new generated reference content. (#889)

- Stop using the prism functionality for syntax highlighting since
it doesn't handle embedded links in <pre> blocks, which prevents
cross-linking to type names properly. We now roll our own PRE block
handling.

- Stop drawing a box around inline code elements which substantially improves
the visuals, especially in tables.

- Improve appearance of tables to be a bit cleaner.

_about/contribute/writing-a-new-topic.md

@@ -233,70 +233,6 @@ func HelloWorld() {
 You can use `markdown`, `yaml`, `json`, `java`, `javascript`, `c`, `cpp`, `csharp`, `go`, `html`, `protobuf`, 
 `perl`, `docker`, and `bash`.
 
-### Displaying file content
-
-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:
-
-```
-{% raw %}<pre data-src="https://raw.githubusercontent.com/istio/istio/master/BUILD"></pre>{% endraw %}
-```
-
-which produces the following result:
-
-<pre data-src="https://raw.githubusercontent.com/istio/istio/master/BUILD"></pre>
-
-The `data-src` attribute specifies the path to the file to display. [PrismJS](http://prismjs.com/) 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 (`raw.githubusercontent.com`) is CORS enabled so it may be used here.
-
-### Highlighting lines
-
-You can highlight specific lines in a preformatted block using the `data-line` attribute:
-
-```
-<pre data-line="3"><code>This is a test
-This is a test
-This is a test
-This is a test
-</code></pre>
-```
-
-which produces the following result:
-
-<pre data-line="3"><code>This is a test
-This is a test
-This is a test
-This is a test
-</code></pre>
-
-See [here](http://prismjs.com/plugins/line-highlight/) for information on how to highlight multiple
-lines and ranges.
-
-### Displaying line numbers
-
-You can display line numbers for all lines in a preformatted block using the `line-numbers` class:
-
-```
-<pre class="line-numbers"><code>This is a test
-This is a test
-This is a test
-This is a test
-</code></pre>
-```
-
-which produces the following result:
-
-<pre class="line-numbers"><code>This is a test
-This is a test
-This is a test
-This is a test
-</code></pre>
-
-See [here](http://prismjs.com/plugins/line-numbers/) for information on how to control some line numbering
-options.
-
 ## Adding redirects
 
 If you move pages around and would like to ensure existing links continue to work, you can add

_config.yml

@@ -5,8 +5,6 @@ kramdown:
   auto_ids: true
   input: GFM
   hard_wrap: false
-  syntax_highlighter_opts:
-    disable : true
 
 baseurl:
 

_layouts/base.html

@@ -61,7 +61,6 @@ layout: compress
         <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/4.0.0/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">
         <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
-        <link rel="stylesheet" href="{{home}}/css/prism.css">
         <link rel="stylesheet" href="{{home}}/css/all.css">
     </head>
 
@@ -77,6 +76,5 @@ layout: compress
 
         <!-- our own scripts -->
         <script src="{{home}}/js/misc.js"></script>
-        <script src="{{home}}/js/prism.min.js"></script>
     </body>
 </html>

_layouts/docs.html

@@ -20,7 +20,7 @@ layout: default
 
             <main role="main">
                 <h1>{{page.title}}</h1>
-                {{ content}}
+                {{content}}
             </main>
         </div>
 

_layouts/protoc-gen-docs.html

@@ -0,0 +1,4 @@
+---
+layout: docs
+---
+{{content}}

_sass/base/_common.scss

@@ -1,11 +1,20 @@
+// This is a hack such that when we link to a fragment on a page, the page
+// scrolls correctly in relation to the fixed header. Without this hack, the
+// page scrolls with the fragment at the top of the page, below the header!
 *[id]:before {
       display: block;
-      content: " ";
+      content: ' ';
       margin-top: -3.0em;
       height: 3.0em;
       visibility: hidden;
 }
 
+// This is here to undo the effect of the above for table rows. Otherwise,
+// table rows with ids don't render properly
+tr[id]:before {
+    content: normal;
+}
+
 html {
     overflow-y: scroll;
     position: relative;
@@ -45,13 +54,21 @@ a.disabled {
     font-weight: 500;
 }
 
-table, th, td {
+table, th, td, tr {
-    border: 1px solid lighten($textColor, 20%);
+    padding: .5em;
-    padding: .3em;
 }
 
 table {
-    border-collapse: collapse;
+    margin-left: 1em;
+    margin-right: 1em;
+}
+
+table p:first-of-type {
+    margin-top: 0
+}
+
+table p:last-of-type {
+    margin-bottom: 0
 }
 
 th {
@@ -60,36 +77,104 @@ th {
     font-weight: normal;
 }
 
-pre.code-toolbar {
+tr.oneof>td {
-    max-height: 30em;
+    border-bottom: 1px dashed $dividerBarColor;
-    margin: .6em 2em;
+    border-top: 1px dashed $dividerBarColor;
+}
 
-    @media (min-width: $bp-md) {
+table {
-        margin: 1.5em 0;
+    border-collapse: separate;
+    border-spacing: 0;
+}
+
+th, td {
+    border-left: 1px solid $secondBrandColor;
+    border-top: 1px solid $secondBrandColor;
+}
+
+tr:first-child th:first-child {
+    border-radius: 4px 0 0 0;
+}
+
+tr:first-child td:first-child {
+    border-radius: 4px 0 0 0;
+}
+
+tr:first-child th:last-child {
+    border-radius: 0 4px 0 0;
+}
+
+tr:first-child td:last-child {
+    border-radius: 0 4px 0 0;
+}
+
+tr:last-child td {
+    border-bottom: 1px solid $secondBrandColor;
+}
+
+tr:last-child td:first-child {
+    border-radius: 0 0 0 4px;
+}
+
+tr:last-child td:last-child {
+    border-radius: 0 0 4px 0;
+}
+
+tr th:last-child {
+    border-right: 1px solid $secondBrandColor;
+}
+
+tr td:last-child {
+    border-right: 1px solid $secondBrandColor;
+}
+
+thead+tbody tr:first-child td:first-child {
+    border-radius: 0;
+}
+
+thead+tbody tr:first-child td:last-child {
+    border-radius: 0;
+}
+
+pre {
+    margin: 1em;
+    max-height: 31em;
+    border: 1px solid $secondBrandColor;
+    border-left: 7px solid $secondBrandColor;
+    border-radius: 4px;
+    background-image: linear-gradient(transparent 50%, rgba(69,142,209,0.04) 50%);
+    background-size: 3em 3em;
+    background-origin: content-box;
+    background-attachment: local;
+    box-shadow: 3px 3px 8px #a7a7a7;
+
+    code {
+        display: block;
+        padding-left: 1em;
     }
 
-    >.toolbar {
+    a.copy-button {
-        top: -2px;
+        font-size: .8em;
-    }
+        padding: .2em .5em;
-
+        border-radius: .3em;
-    >.toolbar a {
         background-color: $secondBrandColor;
+        cursor: pointer;
         color: $white;
+        margin-right: 1px;
     }
 
-    >.toolbar a:hover {
+    div.hide {
-        background-color: $mainBrandColor;
+        float: right;
-        color: $white;
+        z-index: 2;
+        transition: opacity .4s ease-in-out;
+        opacity: 0;
     }
 
-    >.toolbar a:active {
+    div.show {
-        background-color: $popBrandColor;
+        float: right;
-        color: $white;
+        z-index: 2;
-    }
+        transition: opacity 1.2s ease-in-out;
-
+        opacity: 1;
-    >code {
-        border-left-color: $secondBrandColor;
-        border-left-width: 4px;
     }
 }
 
@@ -207,4 +292,8 @@ blockquote {
     @media (min-width: $bp-md) {
         height: 1rem;
     }
-}
+}
+
+.deprecated {
+    background: silver;
+}

_sass/base/_syntax-coloring.scss

@@ -0,0 +1,60 @@
+.highlight  { background: #ffffff; }
+.highlight .c { color: #999988; font-style: italic } /* Comment */
+.highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
+.highlight .k { font-weight: bold } /* Keyword */
+.highlight .o { font-weight: bold } /* Operator */
+.highlight .cm { color: #999988; font-style: italic } /* Comment.Multiline */
+.highlight .cp { color: #999999; font-weight: bold } /* Comment.Preproc */
+.highlight .c1 { color: #999988; font-style: italic } /* Comment.Single */
+.highlight .cs { color: #999999; font-weight: bold; font-style: italic } /* Comment.Special */
+.highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
+.highlight .gd .x { color: #000000; background-color: #ffaaaa } /* Generic.Deleted.Specific */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #aa0000 } /* Generic.Error */
+.highlight .gh { color: #999999 } /* Generic.Heading */
+.highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
+.highlight .gi .x { color: #000000; background-color: #aaffaa } /* Generic.Inserted.Specific */
+.highlight .go { color: #888888 } /* Generic.Output */
+.highlight .gp { color: #555555 } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #aaaaaa } /* Generic.Subheading */
+.highlight .gt { color: #aa0000 } /* Generic.Traceback */
+.highlight .kc { font-weight: bold } /* Keyword.Constant */
+.highlight .kd { font-weight: bold } /* Keyword.Declaration */
+.highlight .kp { font-weight: bold } /* Keyword.Pseudo */
+.highlight .kr { font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #445588; font-weight: bold } /* Keyword.Type */
+.highlight .m { color: #009999 } /* Literal.Number */
+.highlight .s { color: #d14 } /* Literal.String */
+.highlight .na { color: #008080 } /* Name.Attribute */
+.highlight .nb { color: #0086B3 } /* Name.Builtin */
+.highlight .nc { color: #445588; font-weight: bold } /* Name.Class */
+.highlight .no { color: #008080 } /* Name.Constant */
+.highlight .ni { color: #800080 } /* Name.Entity */
+.highlight .ne { color: #990000; font-weight: bold } /* Name.Exception */
+.highlight .nf { color: #990000; font-weight: bold } /* Name.Function */
+.highlight .nn { color: #555555 } /* Name.Namespace */
+.highlight .nt { color: #000080 } /* Name.Tag */
+.highlight .nv { color: #008080 } /* Name.Variable */
+.highlight .ow { font-weight: bold } /* Operator.Word */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .mf { color: #009999 } /* Literal.Number.Float */
+.highlight .mh { color: #009999 } /* Literal.Number.Hex */
+.highlight .mi { color: #009999 } /* Literal.Number.Integer */
+.highlight .mo { color: #009999 } /* Literal.Number.Oct */
+.highlight .sb { color: #d14 } /* Literal.String.Backtick */
+.highlight .sc { color: #d14 } /* Literal.String.Char */
+.highlight .sd { color: #d14 } /* Literal.String.Doc */
+.highlight .s2 { color: #d14 } /* Literal.String.Double */
+.highlight .se { color: #d14 } /* Literal.String.Escape */
+.highlight .sh { color: #d14 } /* Literal.String.Heredoc */
+.highlight .si { color: #d14 } /* Literal.String.Interpol */
+.highlight .sx { color: #d14 } /* Literal.String.Other */
+.highlight .sr { color: #009926 } /* Literal.String.Regex */
+.highlight .s1 { color: #d14 } /* Literal.String.Single */
+.highlight .ss { color: #990073 } /* Literal.String.Symbol */
+.highlight .bp { color: #999999 } /* Name.Builtin.Pseudo */
+.highlight .vc { color: #008080 } /* Name.Variable.Class */
+.highlight .vg { color: #008080 } /* Name.Variable.Global */
+.highlight .vi { color: #008080 } /* Name.Variable.Instance */
+.highlight .il { color: #009999 } /* Literal.Number.Integer.Long */

_sass/modules/_figure.scss

@@ -1,8 +1,6 @@
 .figure {
     margin: 1.5rem auto;
     display: block;
-    border: 1px solid $dividerBarColor;
-    border-radius: 4px;
     padding: .5rem .5rem 0 .5rem;
 
     p {

css/all.scss

@@ -3,6 +3,7 @@
 
 @import "base/constants";
 @import "base/common";
+@import "base/syntax-coloring";
 
 @import "modules/header";
 @import "modules/footer";

css/prism.scss

@@ -1,380 +0,0 @@
----
----
-
-/* PrismJS 1.9.0
-http://prismjs.com/download.html?themes=prism-coy&languages=markup+css+clike+javascript+c+bash+cpp+csharp+docker+go+java+json+markdown+perl+protobuf+yaml&plugins=line-highlight+line-numbers+file-highlight+toolbar+copy-to-clipboard */
-/**
- * prism.js Coy theme for JavaScript, CoffeeScript, CSS and HTML
- * Based on https://github.com/tshedor/workshop-wp-theme (Example: http://workshop.kansan.com/category/sessions/basics or http://workshop.timshedor.com/category/sessions/basics);
- * @author Tim  Shedor
- */
-
-code[class*="language-"],
-pre[class*="language-"] {
-	color: black;
-	background: none;
-	font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace;
-	text-align: left;
-	white-space: pre;
-	word-spacing: normal;
-	word-break: normal;
-	word-wrap: normal;
-	line-height: 1.5;
-
-	-moz-tab-size: 4;
-	-o-tab-size: 4;
-	tab-size: 4;
-
-	-webkit-hyphens: none;
-	-moz-hyphens: none;
-	-ms-hyphens: none;
-	hyphens: none;
-}
-
-/* Code blocks */
-pre[class*="language-"] {
-	position: relative;
-	margin: .5em 0;
-	overflow: visible;
-	padding: 0;
-}
-pre[class*="language-"]>code {
-	position: relative;
-	border-left: 10px solid #358ccb;
-	box-shadow: -1px 0px 0px 0px #358ccb, 0px 0px 0px 1px #dfdfdf;
-	background-color: #fdfdfd;
-	background-image: linear-gradient(transparent 50%, rgba(69, 142, 209, 0.04) 50%);
-	background-size: 3em 3em;
-	background-origin: content-box;
-	background-attachment: local;
-}
-
-code[class*="language"] {
-	max-height: inherit;
-	padding: 0 1em;
-	display: block;
-	overflow: auto;
-}
-
-/* Margin bottom to accomodate shadow */
-:not(pre) > code[class*="language-"],
-pre[class*="language-"] {
-	background-color: #fdfdfd;
-	-webkit-box-sizing: border-box;
-	-moz-box-sizing: border-box;
-	box-sizing: border-box;
-	margin-bottom: 1em;
-}
-
-/* Inline code */
-:not(pre) > code[class*="language-"] {
-	position: relative;
-	padding: .2em;
-	border-radius: 0.3em;
-	color: #c92c2c;
-	border: 1px solid rgba(0, 0, 0, 0.1);
-	display: inline;
-	white-space: normal;
-}
-
-pre[class*="language-"]:before,
-pre[class*="language-"]:after {
-	content: '';
-	z-index: -2;
-	display: block;
-	position: absolute;
-	bottom: 0.75em;
-	left: 0.18em;
-	width: 40%;
-	height: 20%;
-	max-height: 13em;
-	box-shadow: 0px 13px 8px #979797;
-	-webkit-transform: rotate(-2deg);
-	-moz-transform: rotate(-2deg);
-	-ms-transform: rotate(-2deg);
-	-o-transform: rotate(-2deg);
-	transform: rotate(-2deg);
-}
-
-:not(pre) > code[class*="language-"]:after,
-pre[class*="language-"]:after {
-	right: 0.75em;
-	left: auto;
-	-webkit-transform: rotate(2deg);
-	-moz-transform: rotate(2deg);
-	-ms-transform: rotate(2deg);
-	-o-transform: rotate(2deg);
-	transform: rotate(2deg);
-}
-
-.token.comment,
-.token.block-comment,
-.token.prolog,
-.token.doctype,
-.token.cdata {
-	color: #7D8B99;
-}
-
-.token.punctuation {
-	color: #5F6364;
-}
-
-.token.property,
-.token.tag,
-.token.boolean,
-.token.number,
-.token.function-name,
-.token.constant,
-.token.symbol,
-.token.deleted {
-	color: #c92c2c;
-}
-
-.token.selector,
-.token.attr-name,
-.token.string,
-.token.char,
-.token.function,
-.token.builtin,
-.token.inserted {
-	color: #2f9c0a;
-}
-
-.token.operator,
-.token.entity,
-.token.url,
-.token.variable {
-	color: #a67f59;
-	background: rgba(255, 255, 255, 0.5);
-}
-
-.token.atrule,
-.token.attr-value,
-.token.keyword,
-.token.class-name {
-	color: #1990b8;
-}
-
-.token.regex,
-.token.important {
-	color: #e90;
-}
-
-.language-css .token.string,
-.style .token.string {
-	color: #a67f59;
-	background: rgba(255, 255, 255, 0.5);
-}
-
-.token.important {
-	font-weight: normal;
-}
-
-.token.bold {
-	font-weight: bold;
-}
-.token.italic {
-	font-style: italic;
-}
-
-.token.entity {
-	cursor: help;
-}
-
-.namespace {
-	opacity: .7;
-}
-
-@media screen and (max-width: 767px) {
-	pre[class*="language-"]:before,
-	pre[class*="language-"]:after {
-		bottom: 14px;
-		box-shadow: none;
-	}
-
-}
-
-/* Plugin styles */
-.token.tab:not(:empty):before,
-.token.cr:before,
-.token.lf:before {
-	color: #e0d7d1;
-}
-
-/* Plugin styles: Line Numbers */
-pre[class*="language-"].line-numbers {
-	padding-left: 0;
-}
-
-pre[class*="language-"].line-numbers code {
-	padding-left: 3.8em;
-}
-
-pre[class*="language-"].line-numbers .line-numbers-rows {
-	left: 0;
-}
-
-/* Plugin styles: Line Highlight */
-pre[class*="language-"][data-line] {
-	padding-top: 0;
-	padding-bottom: 0;
-	padding-left: 0;
-}
-pre[data-line] code {
-	position: relative;
-	padding-left: 4em;
-}
-pre .line-highlight {
-	margin-top: 0;
-}
-
-pre[data-line] {
-	position: relative;
-	padding: 1em 0 1em 3em;
-}
-
-.line-highlight {
-	position: absolute;
-	left: 0;
-	right: 0;
-	padding: inherit 0;
-	margin-top: 1em; /* Same as .prism’s padding-top */
-
-	background: hsla(24, 20%, 50%,.08);
-	background: linear-gradient(to right, hsla(24, 20%, 50%,.1) 70%, hsla(24, 20%, 50%,0));
-
-	pointer-events: none;
-
-	line-height: inherit;
-	white-space: pre;
-}
-
-	.line-highlight:before,
-	.line-highlight[data-end]:after {
-		content: attr(data-start);
-		position: absolute;
-		top: .4em;
-		left: .6em;
-		min-width: 1em;
-		padding: 0 .5em;
-		background-color: hsla(24, 20%, 50%,.4);
-		color: hsl(24, 20%, 95%);
-		font: bold 65%/1.5 sans-serif;
-		text-align: center;
-		vertical-align: .3em;
-		border-radius: 999px;
-		text-shadow: none;
-		box-shadow: 0 1px white;
-	}
-
-	.line-highlight[data-end]:after {
-		content: attr(data-end);
-		top: auto;
-		bottom: .4em;
-	}
-
-.line-numbers .line-highlight:before,
-.line-numbers .line-highlight:after {
-	content: none;
-}
-
-pre.line-numbers {
-	position: relative;
-	padding-left: 3.8em;
-	counter-reset: linenumber;
-}
-
-pre.line-numbers > code {
-	position: relative;
-    white-space: inherit;
-}
-
-.line-numbers .line-numbers-rows {
-	position: absolute;
-	pointer-events: none;
-	top: 0;
-	font-size: 100%;
-	left: -3.8em;
-	width: 3em; /* works for line-numbers below 1000 lines */
-	letter-spacing: -1px;
-	border-right: 1px solid #999;
-
-	-webkit-user-select: none;
-	-moz-user-select: none;
-	-ms-user-select: none;
-	user-select: none;
-
-}
-
-	.line-numbers-rows > span {
-		pointer-events: none;
-		display: block;
-		counter-increment: linenumber;
-	}
-
-		.line-numbers-rows > span:before {
-			content: counter(linenumber);
-			color: #999;
-			display: block;
-			padding-right: 0.8em;
-			text-align: right;
-		}
-pre.code-toolbar {
-	position: relative;
-}
-
-pre.code-toolbar > .toolbar {
-	position: absolute;
-	top: .3em;
-	right: .2em;
-	transition: opacity 0.3s ease-in-out;
-	opacity: 0;
-}
-
-pre.code-toolbar:hover > .toolbar {
-	opacity: 1;
-}
-
-pre.code-toolbar > .toolbar .toolbar-item {
-	display: inline-block;
-}
-
-pre.code-toolbar > .toolbar a {
-	cursor: pointer;
-}
-
-pre.code-toolbar > .toolbar button {
-	background: none;
-	border: 0;
-	color: inherit;
-	font: inherit;
-	line-height: normal;
-	overflow: visible;
-	padding: 0;
-	-webkit-user-select: none; /* for button */
-	-moz-user-select: none;
-	-ms-user-select: none;
-}
-
-pre.code-toolbar > .toolbar a,
-pre.code-toolbar > .toolbar button,
-pre.code-toolbar > .toolbar span {
-	color: #bbb;
-	font-size: .8em;
-	padding: 0 .5em;
-	background: #f5f2f0;
-	background: rgba(224, 224, 224, 0.2);
-	box-shadow: 0 2px 0 0 rgba(0,0,0,0.2);
-	border-radius: .5em;
-}
-
-pre.code-toolbar > .toolbar a:hover,
-pre.code-toolbar > .toolbar a:focus,
-pre.code-toolbar > .toolbar button:hover,
-pre.code-toolbar > .toolbar button:focus,
-pre.code-toolbar > .toolbar span:hover,
-pre.code-toolbar > .toolbar span:focus {
-	color: inherit;
-	text-decoration: none;
-}
-

js/misc.js

@@ -29,5 +29,54 @@ $(function ($) {
             $(this).children('i.fa').toggleClass('fa-caret-down');
             $(this).parent().children('ul.tree').toggle(200);
         });
+
+        // toggle copy button
+        $(document).on('mouseenter', 'pre', function () {
+            $(this).children("div.copy").toggleClass("show", true)
+            $(this).children("div.copy").toggleClass("hide", false)
+        });
+
+        // toggle copy button
+        $(document).on('mouseleave', 'pre', function () {
+            $(this).children("div.copy").toggleClass("show", false)
+            $(this).children("div.copy").toggleClass("hide", true)
+        });
     });
 }(jQuery));
+
+(function(){
+    var div = "<div class='copy hide'><a style='color: white' class='copy-button'>Copy</a></div>";
+    var pre = document.getElementsByTagName('PRE');
+    for (var i = 0; i < pre.length; i++) {
+        pre[i].insertAdjacentHTML('afterbegin', div);
+    };
+
+    var copyCode = new Clipboard('.copy-button', {
+        target: function(trigger) {
+            return trigger.parentElement.nextElementSibling;
+        }
+    });
+
+    // On success:
+    // - Change the "Copy" text to "Done".
+    // - Swap it to "Copy" in 2s.
+
+    copyCode.on('success', function(event) {
+        event.clearSelection();
+        event.trigger.textContent = 'Done';
+        window.setTimeout(function() {
+            event.trigger.textContent = 'Copy';
+        }, 2000);
+    });
+
+    // On error (Safari):
+    // - Change to "Not supported"
+    // - Swap it to "Copy" in 2s.
+
+    copyCode.on('error', function(event) {
+        event.trigger.textContent = 'Not supported';
+        window.setTimeout(function() {
+            event.trigger.textContent = 'Copy';
+        }, 5000);
+    });
+})();

scripts/grab_reference_docs.sh

@@ -0,0 +1,50 @@
+#! /bin/bash
+
+# This script copies generated .pb.html files, which contain reference docs for protos, and installs
+# them in their targeted location within the _docs/reference tree of this repo.
+#
+# Each .pb.html file contains a line indicate the target directory location. The line is of the form:
+#
+#  location: https://istio.io/docs/reference/...
+#
+
+WORKDIR=work
+
+if [ -d $WORKDIR ]; then
+  cd $WORKDIR/api
+  git fetch
+  cd ../istio
+  git fetch
+  cd ../..
+else
+  mkdir $WORKDIR
+  cd $WORKDIR
+  git clone https://github.com/istio/api.git
+  git clone https://github.com/istio/istio.git
+  cd ..
+fi
+
+locate_file() {
+    FILENAME=$1
+    LOCATION=$(grep '^location: https://istio.io/docs' $FILENAME)
+    LEN=${#LOCATION}
+    if [ $LEN -eq 0 ]
+    then
+        echo "No 'location:' tag in $FILENAME, skipping"
+        return
+    fi
+    FNP=${LOCATION:31}
+    FN=$(echo $FNP | rev | cut -d'/' -f1 | rev)
+    PP=$(echo $FNP | rev | cut -d'/' -f2- | rev)
+    cp ${FILENAME} _docs/${PP}/${FN}
+}
+
+find $WORKDIR/api -type f -name '*.pb.html' | while read line; do
+    locate_file $line
+done
+
+find $WORKDIR/istio -type f -name '*.pb.html' | while read line; do
+    locate_file $line
+done
+
+rm -fr work