Zach’s ugly mug (his face) Zach Leatherman

The Smorgasbord of Windows Terminal… Windows

June 30, 2024

Over the years the Eleventy project has seen some things. One of the issues we’ve seen crop up a few times now involved the Quick Start guide, which had a few steps that asked folks to create a few new files in a Terminal application.

Notably, not everyone is familiar with Terminal applications so we have some introductory documentation on that too.

It started with this command:

echo '# Heading' > index.md

This worked fine for folks on macOS or Linux but in some cases caused issues for some Windows users.

For folks using the Command Prompt application in Windows (also known as cmd.exe) this new index.md incorrectly included the single quotes in the file’s content: '# Heading'. Command Prompt users need to run the command without the quotes:

echo # Header > index.md

For folks using Windows PowerShell (default in the Windows Terminal application and currently bundled with VS Code on Windows, this is specifically versions of PowerShell v5 and prior), the > redirection operator encodes files using UTF-16 (and not the typical UTF-8 expected by Eleventy) resulting in ��#� �H�e�a�d�i�n�g� output in the browser.

PowerShell users need to use the following command:

echo '# Header' | out-file -encoding utf8 'index.md'

For folks using PowerShell Core (the new cross-platform open source terminal application from Microsoft, specifically versions of PowerShell v6 or newer) or Windows Subsystem for Linux (also known as WSL), the original command works without issue:

echo '# Header' > index.md

This smorgasbord adds some hurdles. Folks on Windows machines need to:

  1. Know how to open a Terminal application
  2. Know what Terminal application they’ve opened
  3. Pick the right command for their specific Terminal application type
Name Availability
Command Prompt Default
Windows PowerShell <=5 Default, (via Terminal and VS Code)
PowerShell Core >=6 Installation required
Windows Subsystem for Linux Installation required

Microsoft seems to be iterating in the right direction with the long-term goal of elevating PowerShell Core as the primary terminal application, but the legacy applications are significantly muddying the waters!

Moving forward

Here’s how we’re trying to help Windows folks navigate this complexity:

  1. We added a tabs interface for the different commands for: macOS, Linux, Windows, and Cross Platform.
  2. The Windows tab shows the PowerShell specific command using out-file. It’s compatible with both Windows PowerShell and PowerShell Core.
  3. If out-file doesn’t work in your Windows terminal application (if you’re using Command Prompt), we recommend using the Cross Platform method.

The Cross Platform command uses a new, tiny 11ty/create package that writes a string argument to a file using utf8 encoding.

npx @11ty/create index.md "# Heading"

The above works in macOS, Linux, or Windows (anywhere npx does, requiring Node v18 or newer). No package.json installation is required and it installs on the fly.

@11ty/create is a little 75 lines-of-code utility written in ESM, using the Node test runner and Node’s built-in util.parseArgs. It only has one dependency for colorized terminal text.

This may make way for more code-generation utilities in 11ty moving forward but only with the right problem-solving/complexity/automation/education trade-offs.

Character Encoding Detection

I did also experiment with some character encoding detection (via node-chardet) to gives folks a better error messaging experience when they attempt to process more exotic file encodings in Eleventy.

This approach had a significant performance cost and while very impressive and well-coded (zero dependencies and 22KB!) it was still guessing (more or less) so the tradeoff didn’t make sense in this case.


< Newer
Improved error messaging for require(ESM) in Node.js
Older >
11ty Goes Fully Independent—JS Party #325

Zach Leatherman IndieWeb Avatar for https://zachleat.com/is a builder for the web at IndieWeb Avatar for https://fontawesome.com/Font Awesome and the creator/maintainer of IndieWeb Avatar for https://www.11ty.devEleventy (11ty), an award-winning open source site generator. At one point he became entirely too fixated on web fonts. He has given 83 talks in nine different countries at events like Beyond Tellerrand, Smashing Conference, Jamstack Conf, CSSConf, and The White House. Formerly part of CloudCannon, Netlify, Filament Group, NEJS CONF, and NebraskaJS. Learn more about Zach »

2 Reposts

Sara Joy :happy_pepper:Bob Monsour

4 Likes

Jacky (is looking for work)Andrei TorresnrkSara Joy :happy_pepper:
2 Comments
  1. Zach Leatherman :11ty:

    @raymondcamden that’s a good distinction, I pushed a few updates—thank you!

  2. Raymond Camden

    @zachleat np :)

Shamelessly plug your related post

These are webmentions via the IndieWeb and webmention.io.

Sharing on social media?

This is what will show up when you share this post on Social Media:

How did you do this? I automated my Open Graph images. (Peer behind the curtain at the test page)