Initial Home page

Where-did-my-colored-output-go?.md

@@ -0,0 +1,34 @@
+> If you've wound up here, you're probably wondering why your application with Chalk output is missing color or other formatting. If you've been linked here, please understand that we get this question _a lot_ - there is no bug, nor is there anything we can do, and explaining this time and time again takes a lot of our time.
+
+Chalk uses what are called ["escape sequences" or "escape codes"](https://en.wikipedia.org/wiki/ANSI_escape_code) to tell supporting terminals how to style/format program output. Generally speaking, any program can output a stream of text to be shown, but with escape codes this text can be displayed in a variety of colors, formatting styles (bold, italic, underline, etc.), and even at different positions on the screen.
+
+**Chalk uses "standard" escape sequences and API calls to do what it does. There is nothing magical or unique about how Chalk outputs color. In _MOST_ cases, "bugs" reported to us are cases of user-error.**
+
+Not all terminals support these codes, and - perhaps worse - many [terminal emulators](https://en.wikipedia.org/wiki/Terminal_emulator) that _do_ support them often omit certain codes or have them behave much differently than other terminal emulators might.
+
+Further, these escape sequences are not magic. They are interleaved with normal program output (intended to be read by a human) and are simply characters that hold special meaning, just like any other text. This causes problems when programs are [piped](https://en.wikipedia.org/wiki/Pipeline_%28Unix%29) together, since those escape sequences are otherwise considered as input and can cause a variety of problems - the _best_ case being the program refusing the input altogether.
+
+Thus, most programs (in most languages, on most platforms, using most terminal frameworks, in most cases - **not** just Chalk) tend to check whether or not the target of the colorful output is a [TTY](https://en.wikipedia.org/wiki/Tty_(unix)) - in which case, it is a safe assumption that a user is interactively running the program.
+
+If it is _not_ a TTY, then we choose _not_ to output escape sequences, since it is a pretty safe assumption that the output of the program is being piped into another program as input.
+
+Some cases where your program's output _might_ be piped to another program:
+
+- It's running in a [Docker](https://www.docker.com/) container (including those created by Kubernetes)
+- It's running in [PM2](https://pm2.keymetrics.io/)
+- It's running within a [systemd](https://systemd.io/) unit (e.g. a service or timer)
+- It's being monitored by some logging/error detection system
+- It's running within [GNU Screen](https://en.wikipedia.org/wiki/GNU_Screen) (though this is unlikely as Screen tends to emulate a TTY)
+- It's running within a [CI](https://en.wikipedia.org/wiki/Continuous_integration) system (though [we support](https://github.com/chalk/supports-color/issues?q=CI) many CI services)
+- It's running inside of a [shell script](https://en.wikipedia.org/wiki/Shell_script)
+- It's running on an old version of Windows
+- Your terminal emulator doesn't support color codes
+- About 1000 other potential causes.
+
+Chalk uses a library (called `supports-color`) to perform this check, which when most of the edge-case checks have been boiled away, uses Node's built-in [`isatty()`](https://nodejs.org/api/tty.html#tty_writestream_istty) to determine if the output of either [stdout or stderr](https://en.wikipedia.org/wiki/Standard_streams) are TTYs, depending on [which stream you're using Chalk with](https://github.com/chalk/chalk#chalkstderr-and-supportscolorstderr).
+
+---
+
+So, where did your colors go? They probably aren't being displayed to begin with!
+
+If you're in a situation where you _know_ colors can be safely displayed, we provide a [variety](https://github.com/chalk/chalk#supportscolor) of [ways](https://github.com/chalk/chalk#chalklevel) to override `supports-color`'s result. All of this information, and more, is available in the [Chalk README](https://github.com/chalk/chalk#readme) :)