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.
This commit is contained in:
Martin Taillefer 2018-01-29 06:44:07 -08:00 committed by GitHub
parent 9a4fcf4cde
commit 23b47d9983
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 281 additions and 502 deletions

View File

@ -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

View File

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

View File

@ -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>

View File

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

View File

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

View File

@ -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 {
border: 1px solid lighten($textColor, 20%);
padding: .3em;
table, th, td, tr {
padding: .5em;
}
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 {
max-height: 30em;
margin: .6em 2em;
tr.oneof>td {
border-bottom: 1px dashed $dividerBarColor;
border-top: 1px dashed $dividerBarColor;
}
@media (min-width: $bp-md) {
margin: 1.5em 0;
table {
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 {
top: -2px;
}
>.toolbar a {
a.copy-button {
font-size: .8em;
padding: .2em .5em;
border-radius: .3em;
background-color: $secondBrandColor;
cursor: pointer;
color: $white;
margin-right: 1px;
}
>.toolbar a:hover {
background-color: $mainBrandColor;
color: $white;
div.hide {
float: right;
z-index: 2;
transition: opacity .4s ease-in-out;
opacity: 0;
}
>.toolbar a:active {
background-color: $popBrandColor;
color: $white;
}
>code {
border-left-color: $secondBrandColor;
border-left-width: 4px;
div.show {
float: right;
z-index: 2;
transition: opacity 1.2s ease-in-out;
opacity: 1;
}
}
@ -207,4 +292,8 @@ blockquote {
@media (min-width: $bp-md) {
height: 1rem;
}
}
}
.deprecated {
background: silver;
}

View File

@ -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 */

View File

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

View File

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

View File

@ -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 .prisms 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;
}

View File

@ -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);
});
})();

24
js/prism.min.js vendored

File diff suppressed because one or more lines are too long

50
scripts/grab_reference_docs.sh Executable file
View File

@ -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