[Docs] Added an "Aliases" page under Guides. [En] by vtinev · Pull Request #1042 · withastro/astro

vtinev · 2021-08-06T10:47:50Z

Addressed issue #893.

Changes

Added a page that explains what aliases are, how to define them and how to use them in a project.

Testing

yarn start

Docs

…oth themes.

vercel · 2021-08-06T10:47:54Z

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployments, click below or on the icon next to each commit.

astro-docs – ./docs

🔍 Inspect: https://vercel.com/pikapkg/astro-docs/CfiHdaSPqPidKXHBNC9RGiKvmVjj
✅ Preview: https://astro-docs-git-fork-vtinev-docs-additionsaliases-pikapkg.vercel.app

astro-www – ./www

🔍 Inspect: https://vercel.com/pikapkg/astro-www/EUjC2gyeePmYP5sUWkxdUkE92Foc
✅ Preview: https://astro-www-git-fork-vtinev-docs-additionsaliases-pikapkg.vercel.app

changeset-bot · 2021-08-06T10:47:55Z

⚠️ No Changeset found

Latest commit: 3288e89

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

… PR.

… docs/additions/aliases

Co-authored-by: Peter Singh <[email protected]>

aFuzzyBear

Hey man, good stuff, I do think that this information is warranted and valuable for those wanting to apply it in astro. I dont however feel that it merits itself as a guide, where as the information presented can help augment the config api page. I feel it would be better placed alongside that body of content.

aFuzzyBear · 2021-08-06T17:31:42Z

+
+## Adding a custom alias
+
+If you navigate to the root directory of your project and open the `snowpack.config.mjs` file you will notice that there are some pre-defined aliases already.


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, on how to build out your Astro project. Inside the file you will notice that there are already some predefined aliases.

note that some projects don't have this file! mention to create one if you don't have it yet.

aFuzzyBear · 2021-08-06T17:33:40Z

+title: Aliases
+---
+
+Aliasing is an integral part when it comes to clean and readable code, that's why Astro comes with support for custom aliases out of the box.


Suggested change

Aliasing is an integral part when it comes to clean and readable code, that's why Astro comes with support for custom aliases out of the box.

Aliasing is an integral part when it comes to clean and readable code. Astro comes with support for custom aliases out of the box. Allowing you to maintain a clean and organised project.

Actually, I'd remove the first line entirely as too opinionated :) Some people think that aliases are Bad™️, and our project doesn't really take a stance one way or the other.

Instead, maybe use the first sentence to explain what an alias is and why you might want to use it.

Love that you make the point early that Astro supports aliases "out of the box".

aFuzzyBear · 2021-08-06T17:47:42Z

    { text: 'Data Fetching', link: 'guides/data-fetching' },
    { text: 'Markdown', link: 'guides/markdown-content' },
    { text: 'Supported Imports', link: 'guides/imports' },
+    { text: 'Aliases', link: 'guides/aliases' },


I dont think this should be its own page, having reviewed it I believe this is a better fit to help as an appendix to the references/configuration-reference file, places under the content that is already there.

We'd pretty much be copy/pasting it from the Snowpack documentation and there's already a link for the whole thing there. If we add this we might as well add everything regarding snowpack.config, that wouldn't be very nice because in my opinion Astro and Snowpack are advertised as two separate things.

Given how common this question is I kind of like it as a top-level page, at least for now. +1 for keeping as-is for now (top-level page), and we can do a big docs review before a v1 release and move around if needed then.

FredKSchott

Looking good! Adding some comments but overall +1 on getting this merged. Thanks for tackling!

FredKSchott · 2021-08-06T18:15:27Z

    { text: 'Data Fetching', link: 'guides/data-fetching' },
    { text: 'Markdown', link: 'guides/markdown-content' },
    { text: 'Supported Imports', link: 'guides/imports' },
+    { text: 'Aliases', link: 'guides/aliases' },


Given how common this question is I kind of like it as a top-level page, at least for now. +1 for keeping as-is for now (top-level page), and we can do a big docs review before a v1 release and move around if needed then.

FredKSchott · 2021-08-06T18:17:02Z

+title: Aliases
+---
+
+Aliasing is an integral part when it comes to clean and readable code, that's why Astro comes with support for custom aliases out of the box.


Actually, I'd remove the first line entirely as too opinionated :) Some people think that aliases are Bad™️, and our project doesn't really take a stance one way or the other.

Instead, maybe use the first sentence to explain what an alias is and why you might want to use it.

Love that you make the point early that Astro supports aliases "out of the box".

FredKSchott · 2021-08-06T18:17:51Z

+
+## What are aliases?
+
+Aliases are _keywords_ you can use instead of paths. 


consider removing this header, since the start of every page gets an automatic "Overview" header which these two lines feel like they could fall under.

FredKSchott · 2021-08-06T18:18:15Z

+
+## Adding a custom alias
+
+If you navigate to the root directory of your project and open the `snowpack.config.mjs` file you will notice that there are some pre-defined aliases already.


note that some projects don't have this file! mention to create one if you don't have it yet.

FredKSchott · 2021-08-06T18:18:57Z

+```ts
+// snowpack.config.mjs
+
+alias: {


since some people copy-paste these directly, I'd use the full file format (at least for the first example):

// snowpack.config.mjs export default {

…iases

… docs/additions/aliases

FredKSchott

LGTM with two comments! If you're okay to accept those, then I think this is ready to merge

Co-authored-by: Fred K. Schott <[email protected]>

FredKSchott · 2021-08-06T20:46:06Z

LGTM!

FredKSchott · 2021-08-06T22:23:28Z

fyi I took another pass on the docs and made some additional edits: 73020fa

vtinev2c and others added 2 commits August 6, 2021 10:27

Styled the dark version for the search bar. Changed some stlyes for b…

3733643

…oth themes.

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

526d03c

vercel Bot deployed to Preview – astro-docs August 6, 2021 10:47

View deployment

vercel Bot deployed to Preview – astro-www August 6, 2021 10:47

View deployment

vtinev and others added 3 commits August 6, 2021 13:57

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

0bdc5f1

… PR.

Merge branch 'docs/additions/aliases' of github.com:vtinev/astro into…

4df424f

… docs/additions/aliases

Revert theme.css.

2453ded

vercel Bot deployed to Preview – astro-docs August 6, 2021 11:01

View deployment

vercel Bot deployed to Preview – astro-www August 6, 2021 11:01

View deployment

Revert Search.css.

1baf23a

vercel Bot deployed to Preview – astro-docs August 6, 2021 11:02

View deployment

vercel Bot deployed to Preview – astro-www August 6, 2021 11:03

View deployment

aFuzzyBear reviewed Aug 6, 2021

View reviewed changes

Comment thread docs/src/pages/guides/aliases.md Resolved

Edited the text.

8fb5b14

Co-authored-by: Peter Singh <[email protected]>

vercel Bot deployed to Preview – astro-docs August 6, 2021 17:43

View deployment

vercel Bot deployed to Preview – astro-www August 6, 2021 17:43

View deployment

aFuzzyBear suggested changes Aug 6, 2021

View reviewed changes

FredKSchott mentioned this pull request Aug 6, 2021

Do not comment on some PRs, based on private packages or changed path? changesets/bot#39

Open

FredKSchott reviewed Aug 6, 2021

View reviewed changes

vtinev added 3 commits August 6, 2021 21:25

Merge branch 'main' of github.com:vtinev/astro into docs/additions/al…

55d24b8

…iases

Merge branch 'docs/additions/aliases' of github.com:vtinev/astro into…

caa8ae6

… docs/additions/aliases

Text edits after review.

21a5fe6

vercel Bot deployed to Preview – astro-docs August 6, 2021 18:49

View deployment

vercel Bot deployed to Preview – astro-www August 6, 2021 18:49

View deployment

FredKSchott reviewed Aug 6, 2021

View reviewed changes

Comment thread docs/src/pages/guides/aliases.md Resolved

Comment thread docs/src/pages/guides/aliases.md Resolved

Apply suggestions from documentation review.

3288e89

Co-authored-by: Fred K. Schott <[email protected]>

vercel Bot deployed to Preview – astro-www August 6, 2021 19:34

View deployment

vercel Bot deployed to Preview – astro-docs August 6, 2021 19:34

View deployment

FredKSchott merged commit 2da7078 into withastro:main Aug 6, 2021


		## Adding a custom alias

		If you navigate to the root directory of your project and open the `snowpack.config.mjs` file you will notice that there are some pre-defined aliases already.

	Aliasing is an integral part when it comes to clean and readable code, that's why Astro comes with support for custom aliases out of the box.
	Aliasing is an integral part when it comes to clean and readable code. Astro comes with support for custom aliases out of the box. Allowing you to maintain a clean and organised project.


		## What are aliases?

		Aliases are _keywords_ you can use instead of paths.

Conversation

vtinev commented Aug 6, 2021

Changes

Testing

Docs

Uh oh!

vercel Bot commented Aug 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

astro-docs – ./docs

astro-www – ./www

Uh oh!

changeset-bot Bot commented Aug 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Uh oh!

aFuzzyBear left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vtinev Aug 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FredKSchott left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FredKSchott left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

FredKSchott commented Aug 6, 2021

Uh oh!

FredKSchott commented Aug 6, 2021

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel Bot commented Aug 6, 2021 •

edited

Loading

changeset-bot Bot commented Aug 6, 2021 •

edited

Loading

vtinev Aug 6, 2021 •

edited

Loading