From 73020fab0cb9c5a5a848fc91cdbce1d13570a4fe Mon Sep 17 00:00:00 2001
From: "Fred K. Schott" <fkschott@gmail.com>
Date: Fri, 6 Aug 2021 15:22:35 -0700
Subject: [PATCH] another pass on alias docs

---
 docs/src/pages/guides/aliases.md | 59 +++++++++++++-------------------
 1 file changed, 23 insertions(+), 36 deletions(-)

diff --git a/docs/src/pages/guides/aliases.md b/docs/src/pages/guides/aliases.md
index b8e6b75d7..28d6dd1c5 100644
--- a/docs/src/pages/guides/aliases.md
+++ b/docs/src/pages/guides/aliases.md
@@ -3,56 +3,43 @@ layout: ~/layouts/MainLayout.astro
 title: Aliases
 ---
 
-An **alias** is a handy shortcut for your JavaScript import paths. This can be a great option if you dislike long relative import paths with many repeating `../` segments. Define an **alias** in your project to import directly from some directory no matter how deeply nested a file is located.
+An **alias** is a handy shortcut for your JavaScript imports. This can be a great option if you dislike long relative import paths with many repeating `../` segments. Define an alias to import things directly from some top-level project directory, no matter how deeply nested a file is located.
 
-With aliases, you can import from `"components/SomeComponent.astro"` instead of `"../../../../../components/SomeComponent.astro"`.
+With an alias, you can import from `"$components/SomeComponent.astro"` instead of `"../../../../../components/SomeComponent.astro"`.
 
 ## Adding a custom alias
 
-To add custom aliases to your project, located in the root of your project is the `snowpack.config.mjs` file. This configuration file contains the instructions for Astro's build tool [Snowpack](https://www.snowpack.dev/reference/configuration), on how to build out your Astro project.
+To add a custom alias to your project, locate your project `snowpack.config.mjs` file. This configuration file contains the instructions and configuration for Astro's internal build tool [Snowpack](https://www.snowpack.dev/reference/configuration). If you don't see a `snowpack.config.mjs` file at the top-level of your project (inside the same folder as your `package.json`), you can create a blank file now.
 
-> **Note:** some projects don't come with this file out of the box, feel free to create it yourself. [More on snowpack.config.mjs.](https://www.snowpack.dev/reference/configuration)
-
-Inside the file you will notice that there are already some predefined aliases.
+To add a new import alias, define a new `alias` entry:
 
 ```ts
 // snowpack.config.mjs
-
 export default {
   alias: {
-    components: './src/components',
-    '~': './src',
+    // Map "$components/*" imports to "src/components/*"
+    $components: './src/components',
+    // Map "$/*" imports to "src/*"
+    '$': './src',
+    // Define your own!
+    '$my-special-alias': './src/some/special/folder'
   },
-  plugins: ['@snowpack/plugin-dotenv'],
-  workspaceRoot: '../',
+  // ...
 };
 ```
 
-To **add your own** alias just define it on a new line, like so:
-
-```ts
-// snowpack.config.mjs
-
-export default {
-  alias: {
-    components: './src/components',
-    '~': './src',
-    '@public': './public', // This can be virtually anything
-  },
-  plugins: ['@snowpack/plugin-dotenv'],
-  workspaceRoot: '../',
-};
-```
-
-| Key                         | Value                              |
-| --------------------------- | ---------------------------------- |
-| The keyword you'll be using | The path it will get replaced with |
-
-## Usage
-
-Now just use the **defined** aliases in a file of your choice:
+Once you have defined your alias(es) and restarted Astro (if needed) you can start importing from the alias anywhere in your project:
 
 ```js
-import '@public/assets/logo.svg';
-import MyComponent from 'components/MyComponent/MyComponent.tsx';
+import MyComponent from '$components/MyComponent.astro';
+import mySvgUrl from '$/logo.svg';
 ```
+
+You can read more about the `alias` configuration in [the Snowpack documentation.](https://www.snowpack.dev/reference/configuration#alias)
+
+## Tips & Tricks
+
+- We recommend starting all aliases with the special `$` character. This is not required.
+- It is common to define a top-level `$` alias for your `src` directory. This is not required.
+- To add VSCode support for you aliases, you will also need to define your aliases in a `tsconfig.json` or `jsconfig.json` file via the `"paths"` config value. This will enable Intellisense in VSCode and most other text editors.
+- You don't need to use an alias with Astro! Some people prefer less magic in their code, and don't want to bother with extra steps for text editor support.