more shortcodes and layout cleanup

assets/styles/common/base.scss

@@ -1,7 +1,9 @@
-$site-max-width: 100rem;
+$site-max-width: 120rem;
+$sidebar-width: 20rem;
 
 :root {
 	--site-max-width: #{$site-max-width};
+	--sidebar-width: #{$sidebar-width};
 
 	--color-crossfade-duration: 0.25s;
 	--color-crossfade-ease: ease;
@@ -10,6 +12,7 @@ $site-max-width: 100rem;
 html {
 	font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
 	scroll-behavior: smooth;
+	text-rendering: optimizeLegibility;
 }
 
 body {

assets/styles/common/colors.scss

@@ -13,6 +13,10 @@
 
 	--ui-overlay: #ddd;
 	--ui-overlay-text: var(--ui-text);
+
+	--ui-border: #ddd;
+
+	--ui-error: hsl(0, 80%, 50%);
 }
 
 @mixin dark {
@@ -30,6 +34,10 @@
 
 	--ui-overlay: #333;
 	--ui-overlay-text: var(--ui-text);
+
+	--ui-border: #ddd;
+
+	--ui-error: hsl(0, 80%, 50%);
 }
 
 :root {

assets/styles/common/content.scss

@@ -86,7 +86,7 @@
 	ol {list-style: decimal; margin: 1em 0;}
 	dl {margin: 1em 0; line-height: 1.4;}
 	dt {font-weight: 700;}
-	dd {margin-left: 1em;}
+	dd {margin-left: 1em; margin-bottom: 1em;}
 	/* block elements */
 	img {
 		width: 100%;
@@ -132,7 +132,6 @@
 		padding: 1em;
 	}
 	pre code {
-		background: inherit;
 		padding: 0;
 	}
 	pre code > span {

assets/styles/components/breadcrumbs.scss

@@ -4,20 +4,12 @@
 	li {
 		margin-bottom: 1rem;
 		margin-right: 0.5rem;
-	}
-	li:not(:first-child) {
 		margin-left: 1rem;
 		a {
 			margin-left: 0.5rem;
 		}
-	}
+		&::marker {
-	li::marker {
+			content: "» ";
-		content: "> ";
+		}
-	}
-	li:first-child::marker {
-		content: "";
-	}
-	li:first-child {
-		margin-left: 0;
 	}
 }

assets/styles/components/nav-section.scss

@@ -1,7 +1,7 @@
 @import "common/mixins.scss";
 
 .section-nav {
-	.container {
+	.buttons {
 		display: grid;
 		grid-gap: 1em;
 	}
@@ -38,11 +38,12 @@
 		font-size: 2em;
 	}
 	@media (min-width: 30rem) {
-		.container {
+		.buttons {
 			grid-template-columns: 1fr 1fr;
 		}
 		.next {
 			grid-column: 2;
 		}
 	}
+	margin-bottom: 2em;
 }

assets/styles/layouts/responsive.scss

@@ -1,3 +1,16 @@
+.page > * > .container
+{
+	display: grid;
+	grid-template-columns: minmax(0, 1fr) minmax(0, 80ch) minmax(0, 1fr);
+	> * {
+		grid-column: 2;
+	}
+	> img, figure
+	{
+		grid-column: 1 / span 3;
+	}
+}
+
 /* [responsive] more room to breathe above mobile sizes */
 
 @media (min-width: 30rem) {
@@ -63,7 +76,7 @@
 
 /* [responsive] move the toc to its own column */
 
-@media (min-width: 75rem) {
+@media (min-width: 90rem) {
 	body {
 		grid-template-columns: auto 1fr;
 	}
@@ -128,20 +141,13 @@
 
 }
 
-@media (min-width: 80rem) {
-	.page {
-		display: grid;
-		grid-template-columns: 1fr 20rem;
-	}
-}
-
 
 /* [responsive] fixed layout after reaching maxwidth */
 
 @media (min-width: $site-max-width) {
 
 	body {
-		grid-template-columns: 1fr 20rem calc(var(--site-max-width) - 20rem) 1fr
+		grid-template-columns: 1fr var(--sidebar-width) calc(var(--site-max-width) - var(--sidebar-width)) 1fr
 	}
 
 	.docs-nav {grid-column: 2;}
@@ -156,7 +162,7 @@
 	/* except now the page is fixed to maxwidth and the toc can "grow" */
 
 	.page {
-		grid-template-columns: calc(var(--site-max-width) - 40rem) 1fr;
+		grid-template-columns: 1fr var(--sidebar-width);
 	}
 
 	/* we don't actually want it to grow, though! just stick to the side */

assets/styles/print.scss

@@ -1,13 +1,17 @@
 @import "common/reset";
-@import "common/colors";
+//@import "common/colors";
 @import "common/base";
 @import "common/content";
 
 @import "components/site-header";
 @import "components/breadcrumbs";
 @import "components/table-of-contents";
+
 @import "features/headings";
+
 @import "shortcodes/hint";
+@import "shortcodes/ref";
+@import "shortcodes/required-optional-nullable";
 
 @import "layouts/list";
 @import "layouts/single";
@@ -19,9 +23,10 @@
 .edit-link,
 .footnote-backref,
 .heading__anchor-link,
-.section-nav
+.section-nav,
+.color-switcher
 {
-	display: none;
+	display: none !important;
 }
 .page-header {padding: 0;}
 
@@ -32,3 +37,25 @@
 a[href^="http"]:after {
 	content: " (" attr(href) ") ";
 }
+
+a.page-ref[href^="http"]:after {
+	content: "";
+}
+
+a.source-ref[href^="http"]:after {
+	content: "";
+}
+
+.source-ref, .page-ref {
+	padding: 0;
+}
+
+.content pre {
+	overflow: unset;
+	white-space: pre-wrap;
+}
+
+.content pre code {
+	width: 100%;
+}
+

assets/styles/screen.scss

@@ -17,6 +17,8 @@
 @import "features/links";
 
 @import "shortcodes/hint";
+@import "shortcodes/ref";
+@import "shortcodes/required-optional-nullable";
 
 @import "layouts/list";
 @import "layouts/single";

assets/styles/shortcodes/ref.scss

@@ -0,0 +1,69 @@
+.ref-link {
+	background: var(--ui-overlay);
+	color: var(--ui-overlay-text);
+	&:link, &:visited {
+		color: var(--ui-overlay-text);
+	}
+	&:hover {
+		background: var(--primary-accent);
+		color: var(--primary-accent-text);
+	}
+	transition:
+		background var(--color-crossfade-duration) var(--color-crossfade-ease),
+		color var(--color-crossfade-duration) var(--color-crossfade-ease);
+	display: grid;
+	align-items: center;
+	gap: 1em;
+	@media (min-width: 20rem) {
+		grid-template-columns: 3em 1fr;
+	}
+	margin: 1em 0;
+	padding: 1em;
+	border-radius: 6px;
+	text-decoration: none;
+	&__icon {
+		height: 3em;
+		width: 3em;
+		grid-column: 1;
+		background: var(--primary-accent);
+		color: var(--primary-accent-text);
+		display: grid;
+		place-items: center;
+		border-radius: 8px;
+	}
+	&__text {
+		grid-column: 2 / -1;
+	}
+	svg {
+		height: 1.5em;
+		width: 1.5em;
+	}
+}
+
+.page-ref {
+	font-weight: 700;
+	&__title {
+
+	}
+	&__section {
+
+	}
+}
+
+.source-ref {
+	word-break: break-all;
+	&__name {
+		font-weight: 700;
+	}
+	&__path {
+		margin-top: 8px;
+		display: block;
+		font-family: monospace;
+	}
+}
+
+.section-ref {
+	&__title {
+		font-weight: 700;
+	}
+}

assets/styles/shortcodes/required-optional-nullable.scss

@@ -0,0 +1,22 @@
+.api-method-parameter {
+	&-required {
+		text-transform: uppercase;
+		font-size: 0.75em;
+		font-weight: 500;
+		color: var(--ui-error, red);
+	}
+
+	&-optional {
+		text-transform: uppercase;
+		font-size: 0.75em;
+		font-weight: 500;
+		color: var(--ui-text-muted);
+	}
+
+	&-nullable {
+		text-transform: uppercase;
+		font-size: 0.75em;
+		font-weight: 500;
+		color: var(--ui-error, red);
+	}
+}

i18n/en.toml

@@ -0,0 +1,8 @@
+[required]
+other = "required"
+
+[optional]
+other = "optional"
+
+[nullable]
+other = "nullable"

layouts/_default/baseof.html

@@ -17,7 +17,7 @@
 {{- $theme := resources.Get "styles/screen.scss" | toCSS }}
 {{- with resources.Get "styles/custom.scss" }}
 {{- $custom := . | toCSS }}
-{{- $screen := slice $theme $custom | resources.Concat "styles/screen.css" | minify | fingerprint }}
+{{- $screen := slice $theme $custom | resources.Concat "assets/screen.css" | minify | fingerprint }}
 <link rel="stylesheet"
 	href="{{ $screen.Permalink }}"
 	integrity="{{ $screen.Data.Integrity }}"
@@ -34,7 +34,7 @@
 {{- $theme := resources.Get "scripts/main.js" | js.Build "script.js" | minify | fingerprint }}
 {{ with resources.Get "scripts/custom.js" }}
 {{ $custom := . }}
-{{ $script := slice $theme $custom | resources.Concat "scripts/main.js" | js.Build "script.js" | minify | fingerprint}}
+{{ $script := slice $theme $custom | resources.Concat "assets/main.js" | js.Build "script.js" | minify | fingerprint}}
 <script type="text/javascript"
 	src="{{ $script.Permalink }}"
 	integrity="{{ $script.Data.Integrity }}">

layouts/_default/single.html

@@ -3,7 +3,6 @@
 	<article class="page" {{- if .Param "autonumbering" }} autonumbering {{- end }}>
 		<header class="section page-header">
 			<div class="container">
-				{{ partial "breadcrumbs.html" . }}
 				<h1 class="page-title">{{ .Title }}</h1>
 				<p class="page-summary">{{.Page.Summary | plainify}}</p>
 				
@@ -16,8 +15,11 @@
 		</header>
 		<aside class="toc section">
 			<div class="container">
-				<p class="toc-title">Page outline</p>
+				{{ partial "breadcrumbs.html" . }}
+				<details open>
+					<summary class="toc-title">Page outline</summary>
 					{{ .TableOfContents }}
+				</details>
 			</div>
 		</aside>
 		<section class="content section">

layouts/partials/breadcrumbs.html

@@ -8,7 +8,9 @@
 	{{ else if not .p1.IsHome }}
 	  {{ template "breadcrumb" (dict "p1" .p1.Site.Home "p2" .p2 )  }}
 	{{ end }}
+	{{ if not .p1.IsHome }}
 	<li{{ if eq .p1 .p2 }} class="active"{{ end }}>
 	  <a href="{{ .p1.RelPermalink }}">{{ .p1.Title }}</a>
 	</li>
 	{{ end }}
+ {{ end }}

layouts/partials/nav-section.html

@@ -1,5 +1,6 @@
 <nav class="section-nav">
 	<div class="container">
+		<div class="buttons">
 			{{ $page := .Page }}
 			{{ with .Next }}
 			{{ if eq .FirstSection $page.FirstSection }}
@@ -10,6 +11,6 @@
 			{{ if eq .FirstSection $page.FirstSection }}
 			<a class="next" href="{{.Permalink}}"><span class="text">Next page:<br/>{{.Title}}</span><span class="arrow">→</span></a>
 			{{ end }}
-	{{ end }}
+			{{ end }}</div>
 	</div>
 </nav>

layouts/shortcodes/nullable.html

@@ -0,0 +1 @@
+<span class="api-method-parameter-nullable">{{ i18n "nullable" }}</span>

layouts/shortcodes/optional.html

@@ -0,0 +1 @@
+<span class="api-method-parameter-optional">{{ i18n "optional" }}</span>

layouts/shortcodes/page-ref.html

@@ -1 +1,27 @@
-<a href='{{.Get "page"}}'></a>
+{{- $ref := relref . (.Get "ref") }}
+{{- $path := (index (split (.Get "ref") "#") 0) }}
+{{- $anchor := (index (split (.Get "ref") "#") 1)}}
+{{- $page := .Site.GetPage $path -}}
+{{- $pattern := printf `.*?\n#{2,6} (.+) \{#%s\}.*?` $anchor }}
+{{- $title := $page.RawContent}}
+{{- $heading := index (findRE $pattern $title 1) 0 }}
+{{- $heading = replaceRE $pattern "$1" $heading }}
+{{- with $page -}}
+<a href="{{ $ref }}" class="ref-link page-ref">
+<div class="ref-link__icon">
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" height="24" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+<path stroke-linecap="round" stroke-linejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z" />
+</svg>
+</div>
+<div class="ref-link__text">
+<span class="page-ref__title">
+{{- .Title }}
+</span>
+{{- with $heading -}}
+<span class="page-ref__section">
+<br>§ {{$heading -}}
+</span>
+{{ end -}}
+</div>
+</a>
+{{- end -}}

layouts/shortcodes/required.html

@@ -0,0 +1 @@
+<span class="api-method-parameter-required">{{ i18n "required" }}</span>

layouts/shortcodes/section-ref.html

@@ -0,0 +1,22 @@
+{{- $ref := relref . (.Get "ref") }}
+{{- $path := (index (split (.Get "ref") "#") 0) }}
+{{- $anchor := (index (split (.Get "ref") "#") 1)}}
+{{- $page := .Site.GetPage $path -}}
+{{- with $page -}}
+<a href="{{ $ref }}" class="ref-link section-ref">
+<div class="ref-link__icon">
+{{ if $.Get "icon" }}
+{{ $.Get "icon" | safeHTML }}
+{{ else }}
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" height="24" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+<path stroke-linecap="round" stroke-linejoin="round" d="M13.5 4.5L21 12m0 0l-7.5 7.5M21 12H3" />
+</svg> 
+{{ end }}
+</div>
+<div class="ref-link__text">
+<span class="section-ref__title">
+{{- or ($.Get "title") .Title }}
+</span>
+</div>
+</a>
+{{- end -}}

layouts/shortcodes/source-ref.html

@@ -0,0 +1,16 @@
+{{- with .Get "url" -}}
+{{ $filename := replaceRE `.*/blob/.+/(.*)` "$1" . }}
+{{ $path := replaceRE `.*/blob/.*?/(.*)` "$1" . }}
+<a href="{{ . }}" class="ref-link source-ref">
+<div class="ref-link__icon">
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" height="24" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+<path stroke-linecap="round" stroke-linejoin="round" d="M17.25 6.75L22.5 12l-5.25 5.25m-10.5 0L1.5 12l5.25-5.25m7.5-3l-4.5 16.5" />
+</svg>
+</div>
+<div class="ref-link__text">
+<span class="source-ref__name">{{- or ($.Get "name") $filename }}</span>
+<br>
+<span class="source-ref__path">{{ $path }}</span>
+</div>
+</a>
+{{- end -}}