Add cross-platform commands for quick start and getting started guides. Fixes #2082

Author: zachleat

src/_includes/components/lists.css

@@ -26,20 +26,13 @@
 	margin: 4px 4px 4px 0;
 	transition: 0.15s linear outline;
 }
-/* .inlinelist .inlinelist-item:has(> a) {
-	padding: 0;
-}
-.inlinelist .inlinelist-item:has(> a) > a {
-	padding: .2em .5em;
-} */
 
-.inlinelist .inlinelist-item.active {
+.inlinelist .inlinelist-item:is(:has([aria-selected="true"]), .active) {
 	background-color: #222;
 	color: #fff;
 	font-weight: inherit;
 }
-.inlinelist .inlinelist-item.active :link,
-.inlinelist .inlinelist-item.active :visited {
+.inlinelist .inlinelist-item:is(:has([aria-selected="true"]), .active) :is(:link, :visited) {
 	color: #fff;
 }
 .inlinelist .inlinelist-item code {

src/_includes/components/quick-start.webc

@@ -1,24 +1,47 @@
-<h2 class="mt-0">Quick Start in 2 Steps</h2>
-
-<p>Create a Markdown file.</p>
-
-<syntax-highlight language="bash">
-echo '# Page header' > index.md
-</syntax-highlight>
-
-<details class="details-expand-bg details-rounded">
-	<summary>Eleventy requires Node.js <node-minimum></node-minimum> <em>(expand to learn more)</em></summary>
-	<p>You can check whether or not you have Node installed by running `node --version` in a terminal window. (<a href="/docs/terminal-window/"><em>Well, wait—what is a Terminal window?</em></a>)</p>
-	<p>If the command is not found or it reports a number lower than <node-minimum></node-minimum>, you will need to <a href="https://nodejs.org/en/download/">download and install Node.js</a> before moving on to the next step.</p>
-</details>
+<h2 class="mt-0">Quick Start</h2>
+
+<p><strong>Eleventy requires Node.js <node-minimum></node-minimum>.</strong> You can check whether or not you have Node installed by running <code>node --version</code> in a Terminal. (<a href="/docs/terminal-window/"><em>Well, wait—what is a Terminal?</em></a>) If <code>node</code> is not found or it reports a version number below <node-minimum></node-minimum>, you will need to <a href="https://nodejs.org/en/download/">install Node.js</a> before moving on.</p>
+
+<p>Now we’ll create an <code>index.md</code> <a href="https://commonmark.org/help/">Markdown</a> file. You can do this in the text editor of your choice or by running one of these commands in your terminal:</p>
+
+<script type="module" src="/js/seven-minute-tabs.js" webc:keep></script>
+<seven-minute-tabs class="tabs-left tabs-full" persist sync>
+	<div role="tablist" aria-label="Choose your Operating System">
+		<a href="#quickstart-os-nix" role="tab" data-tabs-persist="os:posix">macOS or Linux</a>
+		<a href="#quickstart-os-win" role="tab" data-tabs-persist="os:win">Windows</a>
+		<a href="#quickstart-os-oldwin" role="tab" data-tabs-persist="os:winold">Windows (Older)</a>
+		<a href="#quickstart-os-all" role="tab" data-tabs-persist="os:all">Cross Platform</a>
+	</div>
+	<div id="quickstart-os-nix" role="tabpanel">
+		<syntax-highlight language="bash">
+echo '# Heading' > index.md
+		</syntax-highlight>
+	</div>
+	<div id="quickstart-os-win" role="tabpanel">
+		<syntax-highlight language="bash">
+echo '# Heading' | out-file -encoding utf8 'index.md'
+		</syntax-highlight>
+	</div>
+	<div id="quickstart-os-oldwin" role="tabpanel">
+		<syntax-highlight language="bash">
+echo # Heading > index.md
+		</syntax-highlight>
+	</div>
+	<div id="quickstart-os-all" role="tabpanel">
+		<syntax-highlight language="bash">
+npx @11ty/create index.md "# Heading"
+		</syntax-highlight>
+		<p>Learn more about <a href="https://github.com/11ty/create"><code>@11ty/create</code></a> <em>(requires Node.js 18 or newer)</em>.</p>
+	</div>
+</seven-minute-tabs>
 
 <p>Run Eleventy.</p>
 
 <syntax-highlight language="bash">
 npx @11ty/eleventy
 </syntax-highlight>
 
-<p>Eleventy compiles any files in the current directory matching valid <a href="/docs/languages/">file extensions</a> (<code>.md</code> is one of many) to the output folder (<code>_site</code> by default). It might look like this:</p>
+<p>Eleventy compiles any files in the current directory matching valid <a href="/docs/languages/">file extensions</a> (<code>md</code> is one of many) to the <code>_site</code> output folder. It might look like this:</p>
 
 <cli-eleventy-output @show-version>
 Writing _site/index.html from ./index.md (liquid)

src/_includes/components/seven-minute-tabs.css

@@ -17,6 +17,12 @@ seven-minute-tabs [role="tablist"] {
 	line-height: 1.8;
 	text-align: right;
 }
+seven-minute-tabs.tabs-full [role="tablist"] {
+	font-size: 0.9375em; /* 15px /16 */
+}
+seven-minute-tabs.tabs-left [role="tablist"] {
+	text-align: left;
+}
 seven-minute-tabs [role="tablist"]:first-child {
 	margin-bottom: 0.5rem;
 }

src/_includes/layouts/base.njk

@@ -73,12 +73,12 @@ let eleventyComputed = {
 {% include 'components/newsletter-signup.css' %}
 {# TODO convert to WebC #}
 {% include 'components/grid-layout.css' %}
+{% include 'components/seven-minute-tabs.css' %}
 
 {% if not skipLegacyBundle %}
 	{# these components are not yet used on WebC pages #}
 	{% include 'components/direct-links.css' %}
 	{% include 'components/breadcrumb.css' %}
-	{% include 'components/seven-minute-tabs.css' %}
 
 	{# these components have been converted to WebC #}
 	{% include 'components/prism-theme.css' %}

src/docs/config.md

@@ -271,7 +271,7 @@ module.exports = function (eleventyConfig) {
 npx @11ty/eleventy --formats=html,liquid,njk
 ```
 
-{% callout "info" %}{% addedin "0.9.0" %} <strong>Case sensitivity</strong>: File extensions should be considered case insensitive, cross-platform. While Mac OS, by default, already behaves this way, other operating systems require additional Eleventy code to enable this behavior.{% endcallout %}
+{% callout "info" %}{% addedin "0.9.0" %} <strong>Case sensitivity</strong>: File extensions should be considered case insensitive, cross-platform. While macOS, by default, already behaves this way, other operating systems require additional Eleventy code to enable this behavior.{% endcallout %}
 
 ### Enable Quiet Mode to Reduce Console Noise
 

src/docs/debug-performance.md

@@ -1,6 +1,6 @@
 ---
 eleventyNavigation:
-  key: Performance
+  key: Debug Performance
   parent: Debug Mode
   excerpt: How to analyze your Eleventy build to find bottlenecks.
   order: 1
@@ -24,7 +24,9 @@ This list is not considered to be exhaustive. It’s just what has been implemen
 
 {% addedin "0.11.0" %} You can use the following `debug` command to show performance measurements for all of these entries (not just those that take longer than 8%).
 
-#### Mac OS (or Linux, etc)
+Learn more about [environment variables for debug output](/docs/debugging/#commands).
+
+#### macOS or Linux (et al)
 
 ```bash
 DEBUG=Eleventy:Benchmark* npx @11ty/eleventy

src/docs/debugging.md

@@ -19,7 +19,7 @@ You can enable this feature by using the `DEBUG` [environment variable](/docs/en
 
 _The commands below assume that Eleventy is installed locally (recommended) but you can learn more about the difference between Local and [Global installation](/docs/global-installation/)._
 
-### Mac OS (or Linux, etc)
+### macOS or Linux (et al)
 
 ```sh
 DEBUG=Eleventy* npx @11ty/eleventy
@@ -35,12 +35,30 @@ Read more about [Windows environment variables](https://www.npmjs.com/package/de
 set DEBUG=Eleventy* & npx @11ty/eleventy
 ```
 
-#### Powershell (VS Code default)
+#### Powershell (default in VS Code)
 
 ```sh
 $env:DEBUG="Eleventy*"; npx @11ty/eleventy
 ```
 
+### Cross Platform
+
+Use the [`cross-env` package](https://github.com/kentcdodds/cross-env) to compatibly set your environment variables cross-platform.
+
+```sh
+npm install cross-env
+```
+
+Now add an npm script in your `package.json`, unlocking `npm run debug`:
+
+```json
+{
+	"scripts": {
+		"debug": "cross-env DEBUG=Eleventy* npx @11ty/eleventy"
+	}
+}
+```
+
 ## Learn More
 
 Read more at the [`debug` package documentation](https://www.npmjs.com/package/debug).

src/docs/environment-vars.md

@@ -27,7 +27,7 @@ For private keys and other sensitive information, you’ll want to create a `.en
 
 ### Via the command line
 
-#### Mac OS (or Linux, etc)
+#### macOS or Linux (et al)
 
 ```bash
 MY_ENVIRONMENT=production npx @11ty/eleventy
@@ -39,22 +39,27 @@ MY_ENVIRONMENT=production npx @11ty/eleventy
 set MY_ENVIRONMENT=production & npx @11ty/eleventy
 ```
 
-#### Windows Powershell (VS Code default)
+#### Windows Powershell (default in VS Code)
 
 ```bash
 $env:MY_ENVIRONMENT="production"; npx @11ty/eleventy
 ```
 
-### Via an npm script
+#### Cross Platform npm scripts
+
+Use the [`cross-env` package](https://github.com/kentcdodds/cross-env) to compatibly set your environment variables cross-platform.
+
+```sh
+npm install cross-env
+```
 
-You can also use the above commands in an npm script in your project’s `package.json` file.
 
 {% codetitle "package.json" %}
 
 ```js
 {
   "scripts": {
-    "build:prod": "MY_ENVIRONMENT=production npx @11ty/eleventy"
+    "build:prod": "cross-env MY_ENVIRONMENT=production npx @11ty/eleventy"
   }
 }
 ```

src/docs/index.webc

@@ -16,7 +16,7 @@ overrideCommunityLinks: true
 
 <p>Eleventy <eleventy-version></eleventy-version> requires <strong><a href="https://nodejs.org/">Node.js</a> version <node-minimum></node-minimum></strong> or higher.</p>
 
-<p>You can check whether or not you have Node installed by running <code>node --version</code> in a terminal window. (<a href="/docs/terminal-window/"><em>Well, wait—what is a Terminal window?</em></a>) If the command is not found or it reports a number lower than <node-minimum></node-minimum>, you will need to <a href="https://nodejs.org/en/download/">download and install Node.js</a> before moving on to the next step.</p>
+<p>You can check whether or not you have Node installed by running <code>node --version</code> in a terminal application. (<a href="/docs/terminal-window/"><em>Well, wait—what is a Terminal?</em></a>) If the command is not found or it reports a number lower than <node-minimum></node-minimum>, you will need to <a href="https://nodejs.org/en/download/">download and install Node.js</a> before moving on to the next step.</p>
 
 <p>Prefer to watch videos instead? Check out <a href="https://www.youtube.com/watch?v=kzf9A9tkkl4"><strong>6 minutes to Build a Blog from Scratch</strong></a>.</p>
 
@@ -85,15 +85,44 @@ If you see `({% latestVersion versions, config %})` in your output you know you
 A <dfn>template</dfn> is a content file written in a [format such as Markdown, HTML, Liquid, Nunjucks, and more](/docs/languages/), which Eleventy transforms into a page (or pages) when building our site.
 
 Let’s run two commands to create two new template files.
+</template>
 
-```bash
+<script type="module" src="/js/seven-minute-tabs.js" webc:keep></script>
+<seven-minute-tabs class="tabs-full tabs-left" persist sync>
+	<div role="tablist" aria-label="Choose your Operating System">
+		<a href="#quickstart-os-nix" role="tab" data-tabs-persist="os:posix">macOS or Linux</a>
+		<a href="#quickstart-os-win" role="tab" data-tabs-persist="os:win">Windows</a>
+		<a href="#quickstart-os-all" role="tab" data-tabs-persist="os:all">Cross Platform</a>
+	</div>
+	<div id="quickstart-os-nix" role="tabpanel">
+<syntax-highlight language="bash">
 echo '<!doctype html><title>Page title</title><p>Hi</p>' > index.html
-```
-
-```bash
-echo '# Page header' > README.md
-```
+</syntax-highlight>
+<syntax-highlight language="bash">
+echo '# Heading' > README.md
+</syntax-highlight>
+	</div>
+	<div id="quickstart-os-win" role="tabpanel">
+<syntax-highlight language="bash">
+echo '<!doctype html><title>Page title</title><p>Hi</p>' | out-file -encoding utf8 'index.html'
+</syntax-highlight>
+<syntax-highlight language="bash">
+echo '# Heading' | out-file -encoding utf8 'README.md'
+</syntax-highlight>
+		<p>If the <code>out-file</code> command is not available in your Windows Terminal window, switch to use the Cross Platform method!</p>
+	</div>
+	<div id="quickstart-os-all" role="tabpanel">
+<syntax-highlight language="bash">
+npx @11ty/create index.html "<!doctype html><title>Page title</title><p>Hi</p>"
+</syntax-highlight>
+<syntax-highlight language="bash">
+npx @11ty/create README.md "# Heading"
+</syntax-highlight>
+		<p>Learn more about <a href="https://github.com/11ty/create"><code>@11ty/create</code></a> <em>(requires Node.js 18 or newer)</em>.</p>
+	</div>
+</seven-minute-tabs>
 
+<template webc:type="11ty" 11ty:type="njk,md" webc:raw webc:nokeep>
 Alternatively, you can create these using any text editor—just make sure you save them into your project folder and they have the correct file extensions.
 
 After you’ve created an HTML template and a Markdown template, let’s run Eleventy again with the following command:

src/docs/terminal-window.md

@@ -6,31 +6,41 @@ eleventyNavigation:
 excludeFromSidebar: true
 ---
 
-# Opening a Terminal Window
+# Opening a Terminal
 
 {% tableofcontents %}
 
-Eleventy runs in a [Terminal window](https://en.wikipedia.org/wiki/Terminal_emulator). If you’re not familiar with Terminal windows, they’re used to run typed commands (and programs) on your computer. A Terminal window is mostly synonymous with terms like Command Line Interface (CLI) or shell prompt.
+Eleventy runs in a [Terminal application](https://en.wikipedia.org/wiki/Terminal_emulator). If you’re not familiar with Terminal applications, they’re used to run typed commands (and programs) on your computer. A Terminal application is mostly synonymous with terms like Command Line Interface (CLI) or shell prompt.
 
-Here’s how to open a Terminal window in various operating systems:
+Here’s how to open a Terminal in various operating systems:
 
-## Mac OS
+## macOS
 
-Mac OS includes an Application called `Terminal.app` which can be used to run Eleventy. Depending on your version of Mac OS, it may be in `/Applications/Utilities/Terminal.app`.
+macOS includes an application called `Terminal` which can be used to run Eleventy. Depending on your version of macOS, it likely lives in `/Applications/Utilities/Terminal`. It may also be called `Terminal.app` if your operating system is configured to show file extensions.
 
 - [Open or quit Terminal on Mac on the _Apple Terminal User Guide_](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac)
 
 ## Windows
 
-Depending on your version of Windows, it may include the `Terminal` App (aka Windows PowerShell), the `Command Prompt` (also known as `cmd.exe`), or both.
+Depending on your version of Windows, it may include the `Terminal` application (aka Windows PowerShell, preferred), or the `Command Prompt` (also known as `cmd.exe`, not preferred), or both.
 
-## Popular Alternatives
+For the best terminal experience, we recommend installing [PowerShell Core](https://github.com/PowerShell/PowerShell) on your Windows machine, a newer and more future-compatible terminal application (also newly cross-platform!).
 
-- [iTerm2](https://iterm2.com/) (Mac OS)
+## Linux
 
-### Editors bundled with Terminals
+Depending on your flavor of Linux, it may be called `Terminal`, `Shell`, `Gnome Terminal`, `Konsole`, or `XTerm`.
 
-- [Nova](https://nova.app/) (Mac OS)
-- [Visual Studio Code](https://code.visualstudio.com/) (Mac OS, Windows, Linux)
+## Editors
+
+Some code editors bundle a terminal for you!
+
+- [Nova](https://nova.app/) (macOS)
+- [Visual Studio Code](https://code.visualstudio.com/) (macOS, Windows, Linux)
   - On Windows, Visual Studio Code is bundled with Windows Powershell.
-- [WebStorm](https://www.jetbrains.com/webstorm/) (Mac OS, Windows, Linux)
+- [WebStorm](https://www.jetbrains.com/webstorm/) (macOS, Windows, Linux)
+
+## More resources
+
+- [DigitalOcean: An introduction to the Linux Terminal](https://www.digitalocean.com/community/tutorials/an-introduction-to-the-linux-terminal#terminal-emulator)
+- [Ubuntu guide: The Linux command line for beginners](https://ubuntu.com/tutorials/command-line-for-beginners#3-opening-a-terminal)
+- [OpenSource.com: A guide to the Linux terminal for beginners](https://opensource.com/article/21/8/linux-terminal)