Merge pull request #111418 from aaronpowell/aapowell/assa-hugo

Hugo quick start

Author: PMEds28

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

@@ -1,178 +1,188 @@
 ---
-title: "Tutorial: Publish a Hugo 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 Hugo site to Azure Static Web Apps"
+description: Learn how to deploy a Hugo 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 Hugo 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 [Hugo](https://gohugo.io/) web application to [Azure Azure Static Web Apps](overview.md). The final result is a new Azure Static Web Apps with the associated GitHub Actions that give you control over how the app is built and published.
 
-# Tutorial: Publish a Hugo 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 Hugo app
+> - Setup an Azure Static Web Apps
+> - Deploy the Hugo 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).
 
-> [!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 Hugo App
 
-## Prerequisites
+Create a Hugo app using the Hugo 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. Follow the [installation guide](https://gohugo.io/getting-started/installing/) for Hugo on your OS.
 
+1. Open a terminal
 
-## Clean up resources
+1. Run the Hugo CLI to create a new app.
 
-If you're not going to continue to use this application, delete
-<resources> with the following steps:
+   ```bash
+   hugo new site static-app
+   ```
 
-1. From the left-hand menu...
-2. ...click Delete, type...and then click Delete
+1. Navigate to the newly created app.
 
-<!---Required:
-To avoid any costs associated with following the tutorial procedure, a
-Clean up resources (H2) should come just before Next steps (H2)
---->
+   ```bash
+   cd static-app
+   ```
 
-## Next steps
+1. Initialize a git repo.
+
+   ```bash
+    git init
+   ```
+
+1. Next, add a theme to the site by installing a theme as a git submodule and then specifying it in the Hugo config file.
+
+   ```bash
+   git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
+   echo 'theme = "ananke"' >> config.toml
+   ```
+
+1. Commit the changes.
+
+   ```bash
+   git add -A
+   git commit -m "initial commit"
+   ```
+
+## Push your application to GitHub
+
+You need a repository on GitHub to connect to Azure Static Web Apps. The following steps show you how to create a repository for your site.
+
+1. Create a blank GitHub repo (don't create a README) from [https://github.com/new](https://github.com/new) named **hugo-static-app**.
+
+1. Add the GitHub repository 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>/hugo-static-app
+   ```
+
+1. Push your local repo 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 App**.
+
+   :::image type="content" source="./media/static-web-apps-publish-hugo/create-in-portal.png" alt-text="Create a Static 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 **hugo-static-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 app in the format of `https://<APP_NAME>....`.
+
+1. For _Region_, select an available region close to you.
+
+1. For _SKU_, select **Free**.
+
+   :::image type="content" source="./media/static-web-apps-publish-hugo/basic-app-details.png" alt-text="Details filled out":::
 
-<!-- Uncomment this block and add the appropriate link
+1. Click the **Sign in with GitHub** button.
+
+1. Select the **Organization** under which you created the repo.
+
+1. Select the **hugo-static-app** as the _Repository_ .
+
+1. For the _Branch_ select **master**.
+
+   :::image type="content" source="./media/static-web-apps-publish-hugo/completed-github-info.png" alt-text="Completed GitHub information":::
+
+### Build
+
+Next, you add configuration settings that the build process uses to build your app. The following settings configure the GitHub Action workflow file.
+
+1. Click the **Next: Build >** button to edit the build configuration
+
+1. Set _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-hugo/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 Azure Static Web Apps and provision a GitHub Action for deployment.
+
+1. Once the deployment completes, navigate to your terminal and pull the commit with the GitHub Action to your machine.
+
+   ```bash
+   git pull
+   ```
+
+1. Open the Hugo app in a text editor and open the _.github/workflows/azure-pages-<WORKFLOW_NAME>.yml_ file.
+
+1. Replace the line `- uses: actions/checkout@v1` (line 18) with the following, to build the Hugo application.
+
+   ```yml
+   - uses: actions/checkout@v2
+        with:
+          submodules: true
+
+   - name: Setup Hugo
+     uses: peaceiris/[email protected]
+     with:
+       hugo-version: "latest"
+
+   - name: Build
+     run: hugo
+   ```
+
+1. Commit the updated workflow and push to GitHub.
+
+   ```bash
+   git add -A
+   git commit -m "Updating GitHub Actions workflow"
+   git push
+   ```
+
+1. Wait for the GitHub Action to complete.
+
+1. In the Azure portal's _Overview_ window of newly created Azure Static Web Apps resource, click the _URL_ link to open your deployed application.
+
+   :::image type="content" source="./media/static-web-apps-publish-hugo/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)