For the novice and intermediate users of terminals on Linux, macOS, and other operating systems, finding, understanding, learning, remembering common commands is an essential skill. There are a variety of one-off websites, GitHub gists, marketing pages, etc. that have these commands, but few provide the type of user-centered design that makes learning even easier.
Terminal Cheat Sheet aims to balance approachability through straightforward content, reduced friction by localizing, accessibility through best practices like WCAG, and performance through the use of static content. It's also meant to complement, not replace, options like man pages or detailed user guides.
- Jekyll - static site builder that works with GitHub pages
- AMP - used to enforce speed, simplicity, and SEO
Libraries
- PureCSS - used for basic components and grid
- Workbox - used for offline support/PWA functionality
- Termynal - modified a bit to work with
<amp-script>
Infra
- GitHub for source and deployment
- GitHub Pages for hosting the content
- Cloudflare for CDN
You'll need to set up Jekyll for local development. Visit https://jekyllrb.com/docs/installation/ for instructions.
Checkout the code from GitHub and then run jekyll serve in the repo directory.
Since this is AMP code, make sure you validate locally before merging.
Contributions welcomed! See CONTRIBUTING.md if you would like to contribute!
The website is internationalized to support localization through translations, asset variations, and more. This is done without the use of additional Jekyll plugins. There are many parts of the site that use this work, but the main parts for new pages are in the following structure:
├── _data
│ ├── translations.yml
│ └── commands
│ ├── basic.yml
│ ├── files.yml
│ └── <newcommands.yml>
│
├── _includes
│ └── i18n
│ ├── index.html
│ └── <newpage.html>
│
├── assets
│ └── pagetype
│ ├── randomasset-en.png
│ ├── randomasset-es.png
│ ├── randomasset-<newlang>.png
│ ├── <newasset>-en.mp4
│ ├── <newasset>-es.mp4
│ └── <newasset>-<newlang>.mp4
│
├── i18n
│ ├── es
│ │ ├── index.html
│ │ ├── otherpage.md
│ │ └── <newpage.html>
│ │
│ ├── fr
│ │ ├── index.html
│ │ ├── otherpage.md
│ │ └── <newpage.html>
│ │
│ └── <newlang>
│ ├── index.html
│ ├── otherpage.md
│ └── <newpage.html>
│
├── index.html
├── otherpage.md
├── <newpage.html>
...
_includes/i18n/* contains the actual content of each page. This content is localized by combining translations from _data/translations.yml and _data/commands/*.yml with the page.lang variable.
i18n/* contains the pages for each language. These only contain some front matter and the include for the actual content from _includes/i18n/*. Most importantly, the page.lang variable is set at the top. If the language uses a RTL script, make sure you set page.direction to rtl as well to automatically reflow the correct parts of the site.
The default language of the site is English, so the files outside of the i18n directory have the language set to English in page.lang. They also include the actual content from _includes/i18n/*.
i18n/* contains the pages for each language. These contain some front matter and the fully translated page written in markdown. The page.lang variable is set at the top. If the language uses a RTL script, make sure you set page.direction to rtl as well to automatically reflow the correct parts of the site.
The default language of the site is English, so the files outside of the i18n directory have the language set to English in page.lang and the content written in markdown as English.
You should not add new content without appropriate translations!
In the structure above, you'll need to add:
- Any translations you need to the data files
- An English page in the top directory
- A page for each language in the appropriate folder within
i18n - The actual content page under
_includes/i18n - Front matter set correctly in each page
- Localized assets in the
assetsdirectory
In the structure above, you'll need to add:
- An English markdown page in the top directory
- A markdown page for each language in the appropriate folder within
i18n - Front matter set correctly in each page
- Localized assets in the
assetsdirectory. For screenshots/GIFs of terminal interaction, it may be OK to use the English locale for most cases
Make sure you:
- Add the guide to the
_data/guides/guide-index.ymlfile so that the navbar auto-generates correctly. - Try to be consistent with other guides by adding sections like "Introduction", "Prerequisites", and a table of contents
Using Docker, we can keep the demo environment consistent across collaborators. Note: all of these commands are from within the demo_env folder.
To create a new image:
docker build -t testimage:v1 --no-cache .
To run and attach to the container:
docker run -it -p 8000:8000 testimage:v1 bash
Keeping the dates consistent on files and folders helps to create consistency across the guides. To do this, you can update the modified date to 2020-01-01:
touch -mt 202001010000 *
A few tips to keep the screenshots and GIFs consistent:
- Use a tool like BetterTouchTool to create a reuseable window size snapping area. A lot of the assets are 665x387 right now, so this helps to be consistent with that
- When taking screenshots with the built-in macOS tool, use
CMD + Shift + 4, then pressSpaceto make it a window screenshot, and then holdAltwhen clicking to avoid capturing the window shadow effect
- The 404 page defaults to English no matter what context you came from
- It's sometimes hard to highlight LTR code mixed with RTL prose
- The use of i18n versus l10n needs some cleanup
SPDX-License-Identifier: Apache-2.0
Visit LICENSE for full text.