From 2da7078eff28b329987fa1a9ae2d37ed38a46e04 Mon Sep 17 00:00:00 2001
From: "V. Tinev" <54780475+vtinev@users.noreply.github.com>
Date: Fri, 6 Aug 2021 23:46:09 +0300
Subject: [PATCH] [Docs] Added an "Aliases" page under Guides. [En] (#1042)

* Styled the dark version for the search bar. Changed some stlyes for both themes.

* [Docs] Added an "Aliases" page under Guides. [EN]

* [Docs] Added "Aliases" page under Guides. Removed styles from another PR.

* Revert theme.css.

* Revert Search.css.

* Edited the text.

Co-authored-by: Peter Singh <drgaud@hotmail.com>

* Text edits after review.

* Apply suggestions from documentation review.

Co-authored-by: Fred K. Schott <fkschott@gmail.com>

Co-authored-by: V. Tinev <vtinev@2create.studio>
Co-authored-by: Peter Singh <drgaud@hotmail.com>
Co-authored-by: Fred K. Schott <fkschott@gmail.com>
---
 docs/src/config.ts               |  1 +
 docs/src/pages/guides/aliases.md | 61 ++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 docs/src/pages/guides/aliases.md

diff --git a/docs/src/config.ts b/docs/src/config.ts
index 6fafece89b..3dea10f6c7 100644
--- a/docs/src/config.ts
+++ b/docs/src/config.ts
@@ -20,6 +20,7 @@ export const SIDEBAR = {
     { text: 'Data Fetching', link: 'guides/data-fetching' },
     { text: 'Markdown', link: 'guides/markdown-content' },
     { text: 'Supported Imports', link: 'guides/imports' },
+    { text: 'Aliases', link: 'guides/aliases' },
     { text: 'Deploy a Website', link: 'guides/deploy' },
     { text: 'Publish a Component', link: 'guides/publish-to-npm' },
 
diff --git a/docs/src/pages/guides/aliases.md b/docs/src/pages/guides/aliases.md
new file mode 100644
index 0000000000..818578e2cd
--- /dev/null
+++ b/docs/src/pages/guides/aliases.md
@@ -0,0 +1,61 @@
+---
+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. 
+
+With aliases, 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. 
+
+> **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.
+
+```ts
+// snowpack.config.mjs
+
+export default {
+  alias: {
+    components: './src/components',
+    '~': './src',
+  },
+  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:
+
+```js
+import '@public/assets/logo.svg';
+import MyComponent from 'components/MyComponent/MyComponent.tsx'
+```