This content originally appeared on Zach Leatherman and was authored by Zach Leatherman
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.mdThis 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 developers need to run the command without the quotes:
echo # Header > index.mdFor folks using the Terminal application in Windows (also known as Windows PowerShell—versions of PowerShell v5 and prior; the one that is bundled by default with VS Code), 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.
Terminal/PowerShell developers 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) or Windows Subsystem for Linux (also known as WSL), the original command works without issue:
echo '# Header' > index.mdThis smorgasbord adds some hurdles. Folks on Windows machines need to:
- Know how to open a Terminal application
- Know what Terminal application they’ve opened
- Pick the right command for their specific Terminal application type
| Name | Availability |
|---|---|
| Command Prompt | Default |
Terminal, Windows PowerShell <=5 |
Default, VS Code Default |
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:
- We added a tabs interface for the different commands for: macOS, Linux, Windows, and Cross Platform.
- The Windows tab shows the PowerShell specific command using
out-file. It’s compatible with both Windows PowerShell and PowerShell Core. - If
out-filedoesn’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.
This content originally appeared on Zach Leatherman and was authored by Zach Leatherman
Zach Leatherman | Sciencx (2024-06-30T00:00:00+00:00) The Smorgasbord of Windows Terminal… Windows. Retrieved from https://www.scien.cx/2024/06/30/the-smorgasbord-of-windows-terminal-windows/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.