Merge pull request #111413 from aaronpowell/aapowell/assa-gatsby

Gastby tutorial

Author: ttorble

articles/static-apps/media/static-web-apps-publish-gatsby/basic-app-details.png

@@ -1,178 +1,142 @@
 ---
-title: "Tutorial: Publish a Gatsby site to App Service Static Apps"
-description: #Required; article description that is displayed in search results. 
-services: #Required for articles that deal with a service; service slug assigned to your service by ACOM.
+title: "Tutorial: Publish a Gatsby site to Azure Static Web Apps"
+description: This tutorial shows you how to deploy a Gatsby application to Azure Static Web Apps.
+services: static-web-apps
 author: aaronpowell
-ms.service: azure-functions
-ms.topic:  tutorial
+ms.service: static-web-apps
+ms.topic: tutorial
 ms.date: 05/08/2020
 ms.author: aapowell
 ---
 
-<!--
-Refer to the following guide for more details:
-  https://review.docs.microsoft.com/en-us/help/contribute/contribute-how-to-mvc-tutorial?branch=master
--->
+# Tutorial: Publish a Gatsby site to Azure Static Web Apps
 
-<!---Recommended: Removal all the comments in this template before you sign-off or merge to master.--->
+This article demonstrates how to create and deploy a [Gatsby](https://gatsbyjs.org) web application to [Azure Static Web Apps](overview.md). The final result is a new Static Web Apps site (with the associated GitHub Actions) that give you control over how the app is built and published.
 
-# Tutorial: Publish a Gatsby site to App Service Static Apps
+In this tutorial, you learn how to:
 
-<!---Required:
-Starts with "Tutorial: "
-Make the first word following "Tutorial:" a verb.
---->
+> [!div class="checklist"]
+>
+> - Create a Gatsby app
+> - Setup an Azure Static Web Apps site
+> - Deploy the Gatsby app to Azure
 
-Introductory paragraph.
+[!INCLUDE [quickstarts-free-trial-note](../../includes/quickstarts-free-trial-note.md)]
 
-<!---Required:
-Lead with a light intro that describes, in customer-friendly language,
-what the customer will learn, or do, or accomplish. Answer the
-fundamental "why would I want to do this?" question.
---->
+## Prerequisites
 
-In this tutorial, you learn how to:
+- An Azure account with an active subscription. If you don't have one, you can [create an account for free](https://azure.microsoft.com/free/).
+- A GitHub account. If you don't have one, you can [create an account for free](https://github.com/join).
+- [Node.js](https://nodejs.org) installed.
 
-> [!div class="checklist"]
-> * All tutorials include a list summarizing the steps to completion
-> * Each of these bullet points align to a key H2
-> * Use these green checkboxes in a tutorial
-<!---Required:
-The outline of the tutorial should be included in the beginning and at
-the end of every tutorial. These will align to the **procedural** H2
-headings for the activity. You do not need to include all H2 headings.
-Leave out the prerequisites, clean-up resources and next steps--->
-
-If you don't have a <service> subscription, create a free trial account...
-<!--- Required, if a free trial account exists
-Because tutorials are intended to help new customers use the product or
-service to complete a top task, include a link to a free trial before the
-first H2, if one exists. You can find listed examples in
-[Write tutorials](contribute-how-to-mvc-tutorial.md)
---->
-
-<!---Avoid notes, tips, and important boxes. Readers tend to skip over
-them. Better to put that info directly into the article text.--->
+## Create a Gatsby App
 
-## Prerequisites
+Create a Gatsby app using the Gatsby Command Line Interface (CLI):
 
-- First prerequisite
-- Second prerequisite
-- Third prerequisite
-<!---If you need them, make Prerequisites your first H2 in a tutorial. If
-there's something a customer needs to take care of before they start (for
-example, creating a VM) it's OK to link to that content before they
-begin.--->
-
-## Sign in to <service/product/tool name>
-
-Sign in to the <service> portal.
-<!---If you need to sign in to the portal to do the tutorial, this H2 and
-link are required.--->
-
-## Procedure 1
-
-<!---Required:
-Tutorials are prescriptive and guide the customer through an end-to-end
-procedure. Make sure to use specific naming for setting up accounts and
-configuring technology.
-Don't link off to other content - include whatever the customer needs to
-complete the scenario in the article. For example, if the customer needs
-to set permissions, include the permissions they need to set, and the
-specific settings in the tutorial procedure. Don't send the customer to
-another article to read about it.
-In a break from tradition, do not link to reference topics in the
-procedural part of the tutorial when using cmdlets or code. Provide customers what they need to know in the tutorial to successfully complete
-the tutorial.
-For portal-based procedures, minimize bullets and numbering.
-For the CLI or PowerShell based procedures, don't use bullets or
-numbering.
---->
-
-Include a sentence or two to explain only what is needed to complete the
-procedure.
-
-1. Step 1 of the procedure
-1. Step 2 of the procedure
-1. Step 3 of the procedure
-   
-   <!---Use screenshots but be judicious to maintain a reasonable length. 
-   Make sure screenshots align to the
-   [current standards](https://review.docs.microsoft.com/help/contribute/contribute-how-to-create-screenshot?branch=master).
-   If users access your product/service via a web browser the first 
-   screenshot should always include the full browser window in Chrome or
-   Safari. This is to show users that the portal is browser-based - OS 
-   and browser agnostic.--->
-1. Step 4 of the procedure
-
-## Procedure 2
-
-Include a sentence or two to explain only what is needed to complete the procedure.
-
-1. Step 1 of the procedure
-1. Step 2 of the procedure
-1. Step 3 of the procedure
-
-## Procedure 3
-
-Include a sentence or two to explain only what is needed to complete the
-procedure.
-<!---Code requires specific formatting. Here are a few useful examples of
-commonly used code blocks. Make sure to use the interactive functionality
-where possible.
-
-For the CLI or PowerShell based procedures, don't use bullets or
-numbering.
---->
-
-Here is an example of a code block for Java:
-
-```java
-cluster = Cluster.build(new File("src/remote.yaml")).create();
-...
-client = cluster.connect();
-```
-
-or a code block for Azure CLI:
-
-```azurecli-interactive 
-az vm create --resource-group myResourceGroup --name myVM --image win2016datacenter --admin-username azureuser --admin-password myPassword12
-```
-
-or a code block for Azure PowerShell:
-
-```azurepowershell-interactive
-New-AzureRmContainerGroup -ResourceGroupName myResourceGroup -Name mycontainer -Image microsoft/iis:nanoserver -OsType Windows -IpAddressType Public
-```
+1. Open a terminal
+1. Use the [npx](https://www.npmjs.com/package/npx) tool to create a new app with the Gatsby CLI. This may take a few minutes.
 
+   ```bash
+   npx gatsby new static-web-app
+   ```
 
-## Clean up resources
+1. Navigate to the newly created app
 
-If you're not going to continue to use this application, delete
-<resources> with the following steps:
+   ```bash
+   cd static-web-app
+   ```
 
-1. From the left-hand menu...
-2. ...click Delete, type...and then click Delete
+1. Initialize a git repo
 
-<!---Required:
-To avoid any costs associated with following the tutorial procedure, a
-Clean up resources (H2) should come just before Next steps (H2)
---->
+   ```bash
+   git init
+   git add -A
+   git commit -m "initial commit"
+   ```
 
-## Next steps
+## Push your application to GitHub
+
+You need to have a repository on GitHub to create a new Azure Static Web Apps resource.
+
+1. Create a blank GitHub repository (don't create a README) from [https://github.com/new](https://github.com/new) named **gatsby-static-web-app**.
+
+1. Next, add the GitHub repository you just created as a remote to your local repo. Make sure to add your GitHub username in place of the `<YOUR_USER_NAME>` placeholder in the following command.
+
+   ```bash
+   git remote add origin https://github.com/<YOUR_USER_NAME>/gatsby-static-web-app
+   ```
+
+1. Push your local repository up to GitHub.
+
+   ```bash
+   git push --set-upstream origin master
+   ```
+
+## Deploy your web app
+
+The following steps show you how to create a new static site app and deploy it to a production environment.
+
+### Create the application
+
+1. Navigate to the [Azure portal](https://portal.azure.com).
+
+1. Select **Create a Resource** and search for **Static Web Apps**.
+
+   :::image type="content" source="./media/static-web-apps-publish-gatsby/create-in-portal.png" alt-text="Create a Static Web Apps (Preview) in the portal":::
+
+1. For _Subscription_, accept the subscription that is listed or select a new one from the drop-down list.
+
+1. In _Resource group_, select **New**. In _New resource group name_, enter **gatsby-static-web-app** and select **OK**.
+
+1. Next, provide a globally unique name for your app in the **Name** box. Valid characters include `a-z`, `A-Z`, `0-9` and `-`. This value is used as the URL prefix for your Static Web App in the format of `https://<YOUR_APP_NAME>.azurestaticapps.net`.
+
+1. For _Region_, select an available region close to you.
 
-<!-- Uncomment this block and add the appropriate link
+1. For _SKU_, select **Free**.
+
+   :::image type="content" source="./media/static-web-apps-publish-gatsby/basic-app-details.png" alt-text="Details filled out":::
+
+1. Click the **Sign in with GitHub** button.
+
+1. Select the **Organization** under which you created the repository.
+
+1. Select the **gatsby-static-web-app** as the _Repository_ .
+
+1. For the _Branch_ select **master**.
+
+   :::image type="content" source="./media/static-web-apps-publish-gatsby/completed-github-info.png" alt-text="Completed GitHub information":::
+
+### Build
+
+Next, add configuration settings that the build process uses to build your app.
+
+1. Click the **Next: Build >** button to edit the build configuration
+
+1. To configure the settings of the step in GitHub Actions, set the _App location_ to **/**.
+
+1. Set _App artifact location_ to **public**.
+
+   A value for _API location_ isn't necessary as you aren't deploying an API at the moment.
+
+   :::image type="content" source="./media/static-web-apps-publish-gatsby/build-details.png" alt-text="Build Settings":::
+
+### Review and create
+
+1. Click the **Review + Create** button to verify the details are all correct.
+
+1. Click **Create** to start the creation of the App Service Static Web App and provision a GitHub Action for deployment.
+
+1. Once the deployment completes click, **Go to resource**.
+
+1. On the resource screen, click the _URL_ link to open your deployed application. You may need to wait a minute or two for the GitHub Action to complete.
+
+   :::image type="content" source="./media/static-web-apps-publish-gatsby/deployed-app.png" alt-text="Deployed application":::
+
+## Clean up resources
+
+[!INCLUDE [static-web-apps-cleanup-resource](../../includes/static-web-apps-cleanup-resource.md)]
+
+## Next steps
 
 > [!div class="nextstepaction"]
-> [Next steps button](contribute-get-started-mvc.md)
-
--->
-
-<!--- Required:
-Tutorials should always have a Next steps H2 that points to the next
-logical tutorial in a series, or, if there are no other tutorials, to
-some other cool thing the customer can do. A single link in the blue box
-format should direct the customer to the next article - and you can
-shorten the title in the boxes if the original one doesn't fit.
-Do not use a "More info section" or a "Resources section" or a "See also
-section". --->
+> [Add a custom domain](custom-domain.md)