From e3d73149f77793126efbc6b696f6e5ed90fb3252 Mon Sep 17 00:00:00 2001 From: Peter Singh Date: Tue, 27 Jul 2021 15:35:23 +0100 Subject: [PATCH] DOC: revisions made to the setup section (#864) * this is the last time im changing these files.... * This is Thats these two files finished off... * Updated the section setup, a bit * trying to resolve the conflict Co-authored-by: Matthew Phillips --- docs/src/config.ts | 2 +- docs/src/pages/getting-started.md | 17 +++-- docs/src/pages/installation.md | 122 ++++++++++++++++++++++++------ docs/src/pages/quick-start.md | 40 +++++++--- 4 files changed, 138 insertions(+), 43 deletions(-) diff --git a/docs/src/config.ts b/docs/src/config.ts index 98d23fc42..ad69bd16d 100644 --- a/docs/src/config.ts +++ b/docs/src/config.ts @@ -4,8 +4,8 @@ export const sidebar = [ link: '', children: [ { text: 'Getting Started', link: 'getting-started' }, - { text: 'Installation', link: 'installation' }, { text: 'Quickstart', link: 'quick-start' }, + { text: 'Installation', link: 'installation' }, { text: 'Examples', link: 'examples' }, { text: 'Astro vs. X', link: 'comparing-astro-vs-other-tools' }, ], diff --git a/docs/src/pages/getting-started.md b/docs/src/pages/getting-started.md index df7e42b25..d416fff8f 100644 --- a/docs/src/pages/getting-started.md +++ b/docs/src/pages/getting-started.md @@ -1,6 +1,7 @@ --- layout: ~/layouts/Main.astro title: Getting Started + --- Astro is a modern static site builder. Learn what Astro is all about from [our homepage](https://astro.build/) or [our release post](https://astro.build/blog/introducing-astro). This page is an overview of the Astro documentation and all related resources. @@ -9,30 +10,32 @@ Looking for a quick overview of what Astro is? [Visit our homepage.](https://ast ## Try Astro -The easiest way to try Astro is to run `npm init astro` in a new directory on your machine. This CLI command will walk you through starting a new Astro project. +The easiest way to try Astro is to run `npm init astro` in a new directory on your machine. Our CLI wizard will assist you in starting a new Astro project. -Read our [Installation Guide](/installation) for a full walk-through on getting set up with Astro. +To get started with Astro in 5 quickly and easy steps, visit our [Quick-Start guide](quick-start). + +Alternatively, read our [Installation Guide](/installation) for a full walk-through on getting set up with Astro. ### Online Playgrounds -If you're interested in playing around with Astro in the browser, you can use an online code playground. Try a Hello World template on [CodeSandbox](https://codesandbox.io/s/astro-template-hugb3). +If you're interested in playing around with Astro in the browser, you can use an online code playground. Try our "Hello World!" template on [CodeSandbox](https://codesandbox.io/s/astro-template-hugb3). _Note: some features (ex: Fast Refresh) are currently limited on CodeSandbox._ ## Learn Astro -People come to Astro from different backgrounds and with different learning styles. Whether you prefer a more theoretical or a practical approach, we hope you'll find this section helpful. +All manner of people come to Astro from different backgrounds bringing with them different learning styles. Whether you prefer a more theoretical or a practical approach, we hope you'll find this section helpful. - If you prefer to **learn by doing**, start with our [examples library](https://github.com/snowpackjs/astro/tree/main/examples). - If you prefer to **learn concepts step by step**, start with our [basic concepts and guides](/core-concepts/project-structure). -Like any unfamiliar technology, Astro does have a learning curve. With practice and some patience, you _will_ get the hang of it. +Like any unfamiliar technology, Astro comes with a slight learning curve. However, with practice and some patience, we know, you _will_ get the hang of it, in no time. ### Learn `.astro` Syntax -When you begin to learn Astro, you'll see many files using the `.astro` file extension. This is the **Astro component syntax**: a special HTML-like file format that Astro uses for templating. It was designed to feel familiar to anyone with HTML or JSX experience. +When you begin to learn Astro, you'll see many files using the `.astro` file extension. This is **Astro's Component Syntax**: a special HTML-like file format which Astro uses for templating. It was designed to feel familiar to anyone with HTML or JSX experience. -Our guide on [Astro components](/core-concepts/astro-components) walks you through the new syntax, and is the best way to learn. +Our helpful guide on [Astro components](/core-concepts/astro-components) introduces you to the Astro syntax, and is the best way to learn. ### API Reference diff --git a/docs/src/pages/installation.md b/docs/src/pages/installation.md index 9865573b0..399fdf633 100644 --- a/docs/src/pages/installation.md +++ b/docs/src/pages/installation.md @@ -8,47 +8,77 @@ There are a few different ways to install Astro in a new project. ## Prerequisites - **Node.js** - `v12.20.0`, `v14.13.1`, `v16.0.0`, or higher. -- **A text editor** - We recommend [VS Code](https://code.visualstudio.com/) with the [Astro extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). -- **A terminal** - Astro is mainly accessed by terminal command-line. +- **Text editor** - We recommend [VS Code](https://code.visualstudio.com/) with our [Official Astro extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). +- **Terminal** - Astro is mainly accessed via the terminal's command-line. -## Recommended Install +For demonstration purposes, we will be using [`npm`](https://www.npmjs.com/) in the examples below, but you could also use [`yarn`](https://yarnpkg.com/) or [`pnpm`](https://pnpm.io/) if you prefer an npm alternative. -`npm init astro` is the easiest way to install Astro in a new project. Run this command in your terminal to start our `create-astro` install wizard to walk you through setting up a new project. +## Create Astro -```bash -mkdir -cd +`npm init astro` is the easiest way to install Astro in a new project. Run this command in your terminal to start our `create-astro` install wizard to assist you with setting up a new project. + +```shell +# With NPM npm init astro + +# Yarn +yarn create astro ``` -Follow the CLI instructions to install Astro with one of our official project starter templates. +[`create-astro`](https://github.com/snowpackjs/astro/tree/main/packages/create-astro) wizard lets you choose from a set of [starter templates](/examples) or alternatively, you could import your own Astro project directly from Github. -Once completed, jump over to our [Quickstart Guide](/quick-start#start-your-project) for a 30-second walkthrough on how to start & build your new Astro project! +```bash +# Note: Replace "my-astro-project" with the name of your project. +# npm 6.x +npm init astro my-astro-project --template starter +# npm 7+, extra double-dash is needed: +npm init astro my-astro-project -- --template starter + +# yarn +yarn create astro my-astro-project --template starter + +# Import Astro project from Github +npm init astro my-astro-project -- --template [GITHUB_USER]/[REPO_NAME] + +# Import Astro from nested paths: +npm init astro my-astro-project -- --template [GITHUB_USER]/[REPO_NAME]/path/to/example +``` + +After `create-astro` scaffolds out your project, you would need to install the projects dependencies. To do this, enter: + +``` bash +npm install +``` + +You can now [Start](#start-astro) your Astro project. Once you have completed assembling your Astro project you can then [Build](#build-astro) your project. Astro would then package up your application and have the static files ready for you to [Deploy](/guides/deploy) to your favourite hosting provider ## Manual Install +You can also setup Astro without the aide of the `create-astro` wizard, below are the few extra steps that are required to get Astro going. + ### Set up your project -Create an empty directory with the name of your project, and then navigate into it: - ```bash -mkdir -cd -# Note: Replace with the name of your project. +# Make and enter a new directory +mkdir my-astro-project +cd my-astro-project ``` -Create a new `package.json` file for your project. Astro is designed to work with the npm ecosystem of packages, which is managed in a `package.json` project manifest. If you don't know what the `package.json` file is, we highly recommend you to have a quick read on [the npm documentation](https://docs.npmjs.com/creating-a-package-json-file). +Create an empty directory with the name of your project, and then navigate into it: + +### Create `package.json` ```bash # This command will create a basic package.json for you npm init --yes ``` +Astro is designed to work with the entirety of the npm package ecosystem. This is managed by a project manifest at the root of your project known as `package.json` . If you're not familiar with the `package.json` file, we highly recommend you to have a quick read over it on [the npm documentation](https://docs.npmjs.com/creating-a-package-json-file). + ### Install Astro -If you've followed the instructions above, you should have a directory with a single `package.json` file inside of it. You can now install Astro in your project. +Following the instructions above, you should have a directory with a single `package.json` file inside of it. You can now setup Astro inside your project. -We'll use `npm` in the examples below, but you could also use `yarn` or `pnpm` if you prefer an npm alternative. If you aren't familiar with `yarn` or `pnpm`, then we strongly recommend sticking with `npm`. ```bash npm install astro @@ -65,28 +95,70 @@ You can now replace the placeholder "scripts" section of your `package.json` fil } ``` +The [`start`](#start-astro) command launches the Astro Dev Server on `http://localhost:3000`. Once your project is ready, the [`build`](#build-astro) command outputs your project to the `dist/` directory. [Read more about deploying Astro in the Deploy guide.](/guides/deploy) + ### Create your first page -Open up your favorite text editor, and create a new file in your project: +Astro Open up your favourite text editor, and create a new file in your project: + +1. Create a new file at `src/pages/index.astro` +2. Copy-and-paste the following snippet (including `---` dashes) into it. ```astro --- -// 1. Create a new file at /src/pages/index.astro -// 2. Copy-and-paste this entire file (including `-` dashes) into it. +// JS/TS Code written in between the (---) code fence, +// is ran solely on the Server! +console.log('See me in the Terminal') --- +

Hello, World!

+ + + + ``` -You can create more pages in the `src/pages` directory, and Astro will use the filename to create new pages on your site. For example, you can create a new file at `src/pages/about.astro` (reusing the previous snippet) and Astro will generate a new page at the `/about` URL. +Above is an example of the Astro's Component's Syntax, which comprises of both HTML & JSX. + +You can create more pages in the `src/pages` directory, and Astro will use the filename to create new pages on your site. For example, by creating a new file at `src/pages/about.astro` (reusing the previous snippet), Astro will generate a new page at the URL : `http://localhost/about` + +## [Start Astro](#start-astro) + +```bash +npm start +``` + +Astro will now start serving your application on `http://localhost:3000`. By opening this URL in your browser, you should see the Astro's β€œHello, World” + +## [Build Astro](#build-astro) + +```bash +npm run build +``` + +This will instruct Astro to build your site and save it directly to disk. Your application is now ready in the `dist/` directory. ### Next Steps -Success! You're now ready to start developing! Jump over to our [Quickstart Guide](/quick-start#start-your-project) for a 30-second walkthrough on how to start & build your new Astro project! +Success! You're now ready to start developing! -πŸ“š Learn more about Astro's project structure in our [Project Structure guide](/core-concepts/project-structure). -πŸ“š Learn more about Astro's component syntax in our [Astro Components guide](/core-concepts/astro-components). -πŸ“š Learn more about Astro's file-based routing in our [Routing guide](core-concepts/astro-pages). +We highly encourage you to get more familiar with the way Astro works. You can do so by further exploring our Docs, we suggest that you consider the following: + +πŸ“š Learn more about Astro's project structure in our [Project Structure guide.](/core-concepts/project-structure) + +πŸ“š Learn more about Astro's component syntax in our [Astro Components guide.](/core-concepts/astro-components) + +πŸ“š Learn more about Astro's file-based routing in our [Routing guide.](core-concepts/astro-pages) \ No newline at end of file diff --git a/docs/src/pages/quick-start.md b/docs/src/pages/quick-start.md index 3613e6c43..e95a15f6a 100644 --- a/docs/src/pages/quick-start.md +++ b/docs/src/pages/quick-start.md @@ -7,8 +7,8 @@ title: Quick Start # prerequisite: check that Node.js is 12.20.0+, 14.13.1+, or 16+ node --version -# create a new project directory, and `cd` into it -mkdir mkdirtest && cd "$_" +# Make a new project directory, and navigate directly into it +mkdir my-astro-project && cd $_ # prepare for liftoff... npm init astro @@ -23,28 +23,48 @@ npm start npm run build ``` -To deploy your Astro site to production, upload the contents of the `/dist` folder (generated by running `npm run build`) to your favorite hosting provider. - -[Read more about deploying Astro in the Deploy guide.](/guides/deploy) +If you wish to learn more about the range of methods to install and setup Astro for your project's, please [read our installation guide.](installation) ## Start your project -Go back to your command-line terminal, and run the following command in your project directory: +From inside your project directory, enter the following command into your terminal: ```bash npm start ``` -Your application is now running on [http://localhost:3000](http://localhost:3000). Open this URL in your browser and you should see the text "Hello, World" that we copied in the previous step. +Astro will now start serving your application on [http://localhost:3000](http://localhost:3000). Opening this URL in your browser, you should see the Astro's "Hello, World". -Astro will listen for file changes in your `src/` directory, so you do not need to restart the application as you make changes during development. +The server will listen for live file changes in your `src/` directory, so you do not need to restart the application as you make changes during development. ## Build your project -Go back to your command-line terminal, and run the following command in your project directory: +To build your project, from inside your directory enter the following build command into your terminal: ```bash npm run build ``` -This will build your site and write it to disk in the `dist/` directory. Astro sites are static, so they can be deployed to your favorite host (Vercel, Netlify, an S3 bucket, etc.). +This will instruct Astro to build your site and save it directly to disk. Your application is now ready in the `dist/` directory. + +## Deploy you project + +Astro sites are static, so they can be deployed to your favourite host: + +- [Vercel](https://vercel.com/) +- [Netlify](https://www.netlify.com/) +- [S3 bucket](https://aws.amazon.com/s3/) +- [Google Firebase](https://firebase.google.com/) +- [Read more about deploying Astro in our Deploy guide.](/guides/deploy) + +## Next Steps + +Success! You're now ready to start developing! + +We recommend that you to take some time to get more familiar with the way Astro works. You can do so by further exploring our Docs, we suggest that you consider the following: + +πŸ“š Learn more about Astro's project structure in our [Project Structure guide.](/core-concepts/project-structure) + +πŸ“š Learn more about Astro's component syntax in our [Astro Components guide.](/core-concepts/astro-components) + +πŸ“š Learn more about Astro's file-based routing in our [Routing guide.](core-concepts/astro-pages) \ No newline at end of file