Bring over some 11ty setup cleanup and improvements from Flutter docs…

… site (#6020)
dart-lang · Aug 4, 2024 · 5e29c49 · 5e29c49
1 parent 48880c9
commit 5e29c49
Show file tree

Hide file tree

Showing 34 changed files with 117 additions and 160 deletions.
diff --git a/eleventy.config.js b/eleventy.config.js
@@ -2,15 +2,7 @@
 // It configures the core 11ty behavior and registers
 // plugins and customization that live in `/src/_11ty`.
 
-import {
-  activeNavEntryIndexArray,
-  arrayToSentenceString,
-  breadcrumbsForPage,
-  generateToc,
-  regexReplace,
-  toISOString,
-  underscoreBreaker,
-} from './src/_11ty/filters.js';
+import { registerFilters } from './src/_11ty/filters.js';
 import { markdown } from './src/_11ty/plugins/markdown.js';
 import { configureHighlighting } from './src/_11ty/plugins/highlight.js';
 
@@ -19,6 +11,7 @@ import yaml from 'js-yaml';
 
 import * as path from 'node:path';
 import * as sass from 'sass';
+import {registerShortcodes} from "./src/_11ty/shortcodes.js";
 
 // noinspection JSUnusedGlobalSymbols
 /**
@@ -46,20 +39,10 @@ export default function (eleventyConfig) {
     strictFilters: true,
     lenientIf: true,
   });
+  eleventyConfig.setLiquidParameterParsing('builtin');
 
-  eleventyConfig.addFilter('regex_replace', regexReplace);
-  eleventyConfig.addFilter('toISOString', toISOString);
-  eleventyConfig.addFilter(
-    'active_nav_entry_index_array',
-    activeNavEntryIndexArray,
-  );
-  eleventyConfig.addFilter('array_to_sentence_string', arrayToSentenceString);
-  eleventyConfig.addFilter('underscore_breaker', underscoreBreaker);
-  eleventyConfig.addFilter('throw_error', function (error) {
-    throw new Error(error);
-  });
-  eleventyConfig.addFilter('generate_toc', generateToc);
-  eleventyConfig.addFilter('breadcrumbsForPage', breadcrumbsForPage);
+  registerFilters(eleventyConfig);
+  registerShortcodes(eleventyConfig);
 
   eleventyConfig.addTemplateFormats('scss');
   eleventyConfig.addWatchTarget('src/_sass');

diff --git a/package.json b/package.json
@@ -34,7 +34,6 @@
     "markdown-it-attrs": "^4.1.6",
     "markdown-it-container": "^4.0.0",
     "markdown-it-deflist": "^3.0.0",
-    "markdown-it-table": "^4.1.1",
     "sass": "^1.77.8",
     "shiki": "^1.12.1"
   }

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/_11ty/filters.js b/src/_11ty/filters.js
@@ -4,6 +4,19 @@ import { selectAll } from 'hast-util-select';
 import { toText } from 'hast-util-to-text';
 import { escapeHtml } from 'markdown-it/lib/common/utils.mjs';
 
+export function registerFilters(eleventyConfig) {
+  eleventyConfig.addFilter('regexReplace', regexReplace);
+  eleventyConfig.addFilter('toISOString', toISOString);
+  eleventyConfig.addFilter('activeNavEntryIndexArray', activeNavEntryIndexArray);
+  eleventyConfig.addFilter('arrayToSentenceString', arrayToSentenceString);
+  eleventyConfig.addFilter('underscoreBreaker', underscoreBreaker);
+  eleventyConfig.addFilter('throwError', function (error) {
+    throw new Error(error);
+  });
+  eleventyConfig.addFilter('generateToc', generateToc);
+  eleventyConfig.addFilter('breadcrumbsForPage', breadcrumbsForPage);
+}
+
 /**
  * Replace text in {@link input} that matches the specified {@link regex}
  * with the specified {@link replacement}.
@@ -13,7 +26,7 @@ import { escapeHtml } from 'markdown-it/lib/common/utils.mjs';
  * @param {string} replacement
  * @return {string} The resulting string with the replacement made.
  */
-export function regexReplace(input, regex, replacement = '') {
+function regexReplace(input, regex, replacement = '') {
   return input.toString().replace(new RegExp(regex), replacement);
 }
 
@@ -25,7 +38,7 @@ export function regexReplace(input, regex, replacement = '') {
  * @param {string|Date} input The date to convert
  * @return {string} The ISO string
  */
-export function toISOString(input) {
+function toISOString(input) {
   if (input instanceof Date) {
     return input.toISOString();
   } else {
@@ -34,12 +47,12 @@ export function toISOString(input) {
   }
 }
 
-export function activeNavEntryIndexArray(navEntryTree, pageUrlPath = '') {
+function activeNavEntryIndexArray(navEntryTree, pageUrlPath = '') {
   const activeEntryIndexes = _getActiveNavEntries(navEntryTree, pageUrlPath);
   return activeEntryIndexes.length === 0 ? null : activeEntryIndexes;
 }
 
-export function _getActiveNavEntries(navEntryTree, pageUrlPath = '') {
+function _getActiveNavEntries(navEntryTree, pageUrlPath = '') {
   // TODO(parlough): Simplify once standardizing with the Flutter site.
   for (let i = 0; i < navEntryTree.length; i++) {
     const entry = navEntryTree[i];
@@ -68,7 +81,7 @@ export function _getActiveNavEntries(navEntryTree, pageUrlPath = '') {
   return [];
 }
 
-export function arrayToSentenceString(list, joiner = 'and') {
+function arrayToSentenceString(list, joiner = 'and') {
   if (!list || list.length === 0) {
     return '';
   }
@@ -91,7 +104,7 @@ export function arrayToSentenceString(list, joiner = 'and') {
   return result;
 }
 
-export function underscoreBreaker(stringToBreak, inAnchor = false) {
+function underscoreBreaker(stringToBreak, inAnchor = false) {
   // Only consider text which has underscores in it to keep this simpler.
   if (!stringToBreak.includes('_')) {
     return stringToBreak;
@@ -109,7 +122,7 @@ export function underscoreBreaker(stringToBreak, inAnchor = false) {
   return stringToBreak.replaceAll('_', '_<wbr>');
 }
 
-export function generateToc(contents) {
+function generateToc(contents) {
   // TODO(parlough): Speed this up.
   //   Perhaps do the processing before HTML rendering?
   //   Maybe shouldn't be a filter.
@@ -160,7 +173,7 @@ export function generateToc(contents) {
   };
 }
 
-export function breadcrumbsForPage(page) {
+function breadcrumbsForPage(page) {
   const breadcrumbs = [];
 
   // Retrieve the liquid data for this page.

diff --git a/src/_11ty/plugins/markdown.js b/src/_11ty/plugins/markdown.js
@@ -1,6 +1,5 @@
 import markdownIt from 'markdown-it';
 import markdownItContainer from 'markdown-it-container';
-import { markdownItTable } from 'markdown-it-table';
 import markdownItDefinitionList from 'markdown-it-deflist';
 import markdownItAttrs from 'markdown-it-attrs';
 import markdownItAnchor from 'markdown-it-anchor';
@@ -9,7 +8,6 @@ import { slugify } from '../utils/slugify.js';
 /** @type {import('markdown-it/lib').MarkdownIt} */
 export const markdown = (() => {
   const markdown = markdownIt({ html: true })
-    .use(markdownItTable)
     .use(markdownItDefinitionList)
     .use(markdownItAttrs, {
       leftDelimiter: '{:',
@@ -30,10 +28,28 @@ export const markdown = (() => {
     });
 
   _registerAsides(markdown);
+  _setUpTables(markdown);
 
   return markdown;
 })();
 
+/**
+ * Wrap all tables in a div with `table-wrapper` class.
+ *
+ * @param markdown {import('markdown-it/lib').MarkdownIt} markdown
+ */
+function _setUpTables(markdown) {
+  markdown.renderer.rules = {
+    ...markdown.renderer.rules,
+    table_open: function (tokens, idx, options, env, self) {
+      const token = tokens[idx];
+      // Render added attributes from `{:.table .table-striped}` syntax.
+      return `<div class="table-wrapper">\n<table ${self.renderAttrs(token)}>\n`;
+    },
+    table_close: () => '</table>\n</div>',
+  };
+}
+
 /**
  * Register a custom aside/admonition.
  *

diff --git a/src/_11ty/shortcodes.js b/src/_11ty/shortcodes.js
@@ -0,0 +1,31 @@
+export function registerShortcodes(eleventyConfig) {
+  _setupMedia(eleventyConfig);
+}
+
+function _setupMedia(eleventyConfig) {
+  eleventyConfig.addShortcode('ytEmbed', function (id, title, type = 'video', fullWidth = false) {
+    let embedTypePath = '';
+    if (type === 'playlist') {
+      embedTypePath = 'playlist?list=';
+    } else if (type === 'series') {
+      embedTypePath = 'videoseries?list=';
+    }
+
+    return `<iframe ${fullWidth ? 'class="full-width"' : 'width="560" height="315"'} 
+        src="https://www.youtube.com/embed/${embedTypePath}${id}" title="${title}" frameborder="0" 
+        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
+        allowfullscreen loading="lazy"></iframe><br>
+        <p><a href="https://www.youtube.com/watch/${id}" target="_blank" rel="noopener" title="Open '${title}' video in new tab">${title}</a></p>`;
+  });
+
+  eleventyConfig.addPairedShortcode('videoWrapper', function (content, intro = '') {
+    let wrapperMarkup = '<div class="video-wrapper">';
+    if (intro && intro !== '') {
+      wrapperMarkup += `<span class="video-intro">${intro}</span>`;
+    }
+
+    wrapperMarkup += content;
+    wrapperMarkup += '</div>';
+    return wrapperMarkup;
+  });
+}
diff --git a/src/_data/site.yml b/src/_data/site.yml
@@ -29,6 +29,10 @@ announce: https://groups.google.com/a/dartlang.org/g/announce
 android-dev: https://developer.android.com
 apple-dev: https://developer.apple.com
 
+yt:
+  watch: 'https://www.youtube.com/watch'
+  playlist: 'https://www.youtube.com/playlist?list='
+
 show_banner: false
 
 # Increment this global og:image URL version number (used as a query parameter)

diff --git a/src/_data/yt.yml b/src/_data/yt.yml
diff --git a/src/_includes/breadcrumbs.html b/src/_includes/breadcrumbs.html
@@ -6,7 +6,7 @@
 - https://search.google.com/structured-data/testing-tool
 {% endcomment %}
 
-{% assign url = page.url | regex_replace: '/index$|/index.html$|/$' -%}
+{% assign url = page.url | regexReplace: '/index$|/index.html$|/$' -%}
 
 {% if url.size > 0 -%}
 <nav aria-label="breadcrumb">
@@ -18,7 +18,7 @@
       property="itemListElement" typeof="ListItem"
       {%- if forloop.last %} aria-current="page"{% endif %}>
       {%- comment %}Avoid spaces here, it messes up formatting{% endcomment -%}
-      <a href="{{ crumb.url | regex_replace: '/index$|/index.html$|/$' }}" property="item" typeof="WebPage">
+      <a href="{{ crumb.url | regexReplace: '/index$|/index.html$|/$' }}" property="item" typeof="WebPage">
         {%- comment %}Avoid spaces here, it messes up formatting{% endcomment -%}
         <span property="name">{{crumb.title}}</span>
       </a>

diff --git a/src/_includes/head.html b/src/_includes/head.html
@@ -15,7 +15,7 @@
   {% assign desc = description | default: site.description | strip_html | strip_newlines | truncate: 160 -%}
   {% unless desc and desc != '' -%}
     {% assign error = page.url | append: ' must have a description specified!' -%}
-    {{ error | throw_error }}
+    {{ error | throwError }}
   {% endunless %}
   <meta name="description" content="{{desc}}">
   <title>{% if short-title %}{{short-title}}{% else %}{{title}}{% endif %} | {{site.title}}</title>

diff --git a/src/_includes/navigation-main.html b/src/_includes/navigation-main.html
@@ -1,4 +1,4 @@
-{% assign page_url_path = page.url | regex_replace: '/index$|/index\.html$|\.html$|/$' | prepend: '/*' | append: '/' -%}
+{% assign page_url_path = page.url | regexReplace: '/index$|/index\.html$|\.html$|/$' | prepend: '/*' | append: '/' -%}
 
 <nav id="mainnav" class="site-header">
   <div id="menu-toggle"><i class="material-symbols">menu</i></div>

diff --git a/src/_includes/navigation-toc-side.html b/src/_includes/navigation-toc-side.html
@@ -6,12 +6,12 @@
   <ul class="section-nav">
     {% for topLevel in tocContents.toc %}
     <li class="toc-entry nav-item">
-      <a class="nav-link" href="{{topLevel.id}}">{{topLevel.text | underscore_breaker}}</a>
+      <a class="nav-link" href="{{topLevel.id}}">{{topLevel.text | underscoreBreaker}}</a>
       {% if topLevel.children and topLevel.children.size > 0 %}
       <ul class="nav">
         {% for child in topLevel.children %}
         <li class="toc-entry nav-item">
-          <a class="nav-link" href="{{child.id}}">{{child.text | underscore_breaker}}</a>
+          <a class="nav-link" href="{{child.id}}">{{child.text | underscoreBreaker}}</a>
         </li>
         {% endfor -%}
       </ul>

diff --git a/src/_includes/sidenav-level-1.html b/src/_includes/sidenav-level-1.html
@@ -1,5 +1,5 @@
-{% assign page_url_path = url | regex_replace: '/index$|/index\.html$|\.html$|/$' -%}
-{% assign active_entries = nav | active_nav_entry_index_array: page_url_path -%}
+{% assign page_url_path = url | regexReplace: '/index$|/index\.html$|\.html$|/$' -%}
+{% assign active_entries = nav | activeNavEntryIndexArray: page_url_path -%}
 
 <ul class="nav flex-column">
   {%- for entry in nav -%}

diff --git a/src/_layouts/default.html b/src/_layouts/default.html
@@ -2,7 +2,7 @@
 <html lang="en">
   {% include 'head.html' %}
   {% if toc != false -%}
-    {% assign tocContents = content | generate_toc %}
+    {% assign tocContents = content | generateToc %}
     {% if tocContents == null or tocContents == '' -%}
       {% assign toc = false %}
     {% endif -%}
@@ -23,7 +23,7 @@
           <div id="site-content-title">
             {% include 'page-github-links.html' -%}
             {% if underscore_breaker_titles -%}
-            <h1>{{title | underscore_breaker}}</h1>
+            <h1>{{title | underscoreBreaker}}</h1>
             {% else %}
             <h1>{{title }}</h1>
             {% endif -%}

diff --git a/src/_sass/_site.scss b/src/_sass/_site.scss
@@ -487,7 +487,7 @@ li.card {
 }
 
 // If table head has empty children, just hide it
-// since markdown-it-table doesn't support headless tables.
+// since markdown-it's tables don't support headless tables.
 thead:has(th:empty) {
   display: none;
 }

diff --git a/src/content/get-dart/index.md b/src/content/get-dart/index.md
@@ -91,16 +91,22 @@ run the same command to install the Dart SDK from your package manager.
   <li class="tab-link" data-tab="tab-sdk-install-linux">Linux</li>
   <li class="tab-link" data-tab="tab-sdk-install-mac">macOS</li>
 </ul>
-<div id="tab-sdk-install-windows" class="tabs__content current" markdown="1">
+<div id="tab-sdk-install-windows" class="tabs__content current">
+
 {% include 'install/windows.md' %}
+
 </div>
 
-<div id="tab-sdk-install-linux" class="tabs__content" markdown="1">
+<div id="tab-sdk-install-linux" class="tabs__content">
+
 {% include 'install/linux.md' %}
+
 </div>
 
-<div id="tab-sdk-install-mac" class="tabs__content" markdown="1">
+<div id="tab-sdk-install-mac" class="tabs__content">
+
 {% include 'install/macos.md' %}
+
 </div>
 
 ## Release channel reference {:#release-channels}

diff --git a/src/content/guides/whats-new.md b/src/content/guides/whats-new.md
@@ -366,10 +366,10 @@ During Google I/O 2023, we released the following videos:
 * [Rethinking Dart interoperability with Android][]
 * [How to build a package in Dart][]
 
-[What's new in Dart and Flutter]: {{yt.watch}}?v=yRlwOdCK7Ho
-[American Sign Language version]: {{yt.watch}}?v=QbMgjVB0XMI
-[Rethinking Dart interoperability with Android]: {{yt.watch}}?v=ZWp2FJ2TuJs
-[How to build a package in Dart]: {{yt.watch}}?v=8V_TLiWszK0
+[What's new in Dart and Flutter]: {{site.yt.watch}}?v=yRlwOdCK7Ho
+[American Sign Language version]: {{site.yt.watch}}?v=QbMgjVB0XMI
+[Rethinking Dart interoperability with Android]: {{site.yt.watch}}?v=ZWp2FJ2TuJs
+[How to build a package in Dart]: {{site.yt.watch}}?v=8V_TLiWszK0
 
 ## January 25, 2023: 2.19 + 3.0 alpha releases