How to Create a Documentation Site With CI/CD and Syntax Linting

• Thu, Sep 30, 2021
• 5-minute read

This tutorial explains how to create a documentation site with automatic deployments and syntax linting.

Tools

The tools you need are all free to use and are the following:

• Hugo A Static Site Generator.
• Azure Static Web Apps Static web sites hosting service (Free for personal use, see Pricing).
• Vale Grammar and syntax linter.
• GitHub Repository hosting.
• GitHub Actions GitHub feature for automation pipelines.

Creating the Static Site

To create a new Hugo site:

1. Install Hugo:

   brew install hugo
   

2. Create a new Hugo app:

   hugo new site your-documentation-site
   

3. Change directory into your new site:

   cd your-documentation-site
   

4. Initialize a Git repository:

   git init
   

5. Visit Hugo Themes to browse for available themes for your site.
6. Follow instructions to install the theme, usually you can do so with git submodule:

   git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
   

7. Add the theme to the config file (depending on the theme it’s a YAML or TOML file):

   echo theme = \"ananke\" >> config.toml
   

8. Ensure that your production or stable branch is named ‘main’:

   git branch -M main
   

9. Add and commit the changes:

   git add -A
   git commit -m “initial commit”
   

See detailed instructions on how to install and get started with Hugo.

Create a GitHub Repository for Your Docs

To create a GitHub repository and host your documentation site:

1. Go to GitHub and create an account if don’t have one already.
2. Click the New button to create a new repository.
   1. Provide a name for your docs repository.
   2. Add a description (Optional).
   3. Choose if you want your repository to be Private or Public.
   4. Leave all checkboxes unselected.
3. Click the Code button on the top right corner of your repository page and copy the HTTPS (or SSH if have SSH enabled).
4. Add your GitHub repository as a remote by running the following command on a Terminal window inside your project directory:

   git remote add origin <your repository HTML or SSH address>
   

5. Push your site to your GitHub repository:

   git push --set-upstream origin main
   

Deploy your Docs Site to Azure Static Web Apps

To deploy your static site to Azure Static Web Apps,

1. Go to the Azure Portal and create an account if you don’t have one already.
2. Click the + Create a resource button.
3. Search for Static Web App and select it.
4. Click the Create button.
5. On the Basics tab,
   1. Select the Free Trial subscription type.
   2. In the Resource Group, type a name for your new site resource group.
   3. In the Name field, type the name with which you want to identify your Static Site in Azure.
   4. In the Hosting plan section, select the Free: For hobby or personal projects plan type.
   5. Select a region to host your site (select the one that is closest to you).
   6. In the Deployment details section, select the GitHub source.
   7. In GitHub account, click the Sign in with GitHub button.
6. Authenticate with your GitHub account when prompted.
   1. Select your GitHub organization (it can be your user name if you don’t have any organization set up).
   2. Select where you hosted your static site.
   3. Select the main branch.
      The Build Details section appears below.
7. In the Build Presets field, select Hugo from the dropdown menu and leave the default values for the rest of the fields.
8. Click the Next: Tags > button and leave the default empty values.
9. Click the Next: Review + create > button.
10. Click Create.
11. Once the deployment is complete, click Go to resource.
12. Click the URL link. A new window opens with your deployed static site.

You can see another tutorial by the Microsoft team at this location.

Configure Vale Linter for Your Site

Now you have a Static Site ready to create and publish your documentation through an automated pipeline to an Azure Static Web Apps site. Let’s configure the Vale linter to add a syntax and grammar checker to your GitHub Actions pipelines!

1. Install Vale on your OS.
2. In your project’s root directory, create a .vale.ini file with the following:

   StylesPath = styles
   
   Vocab = Blog
   
   [*.md]
   BasedOnStyles = Microsoft, write-good
   

3. Download the Vale boilerplate project to a location different than your docs site directory.
4. Copy the styles folder and paste it in your project’s root directory.
5. Create a vale_linter.yml file in the <your-documentation-site>/.github/workflows/ directory with the following content:

   name: Linting
   on:
   push:
       branches: [main]
   
   jobs:
   prose:
       runs-on: ubuntu-latest
       steps:
       - name: Checkout
       uses: actions/checkout@master
   
       - name: Vale
       uses: errata-ai/vale-action@v1.4.0
       with:
           # Optional
           styles: |
           https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip
           https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip
           # Optional
           config: https://raw.githubusercontent.com/errata-ai/vale/master/.vale.ini
   
           # Optional
           files: path/to/lint        
       env:
           # Required
           GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
   

6. Save all your changes and commit them:git add -Agit commit -m “vale linter configuration”
7. Push your changes to the GitHub repository:git push origin main

This configuration takes the preset rules defined in the Microsoft style guide and the write-good rules defined by Vale. Every time you push new Markdown files it checks them and provides warnings, suggestions, and errors according to the selected guidelines. It can provide messages about capitalization, grammar rules, and conditions defined in the different styles that you select.

You can also define and create your own style guidelines and use them in your project as you would use the ones shown in this example. You can see more details in the Vale Styles and Usage documentation.

Add New Content

Your site is now ready with automatic deploys and a style checker so that every time you push new content in a Markdown file it triggers the Azure deploy and the Vale syntax linter pipelines.

1. Create a new post:
   hugo new posts/<your_new_post>.md
2. Add metadata to your post with a front matter block at the beginning of your file:

   ---
   title: "Your Title Here"
   date: 2021-10-01T19:26:18-06:00
   layout: post
   ---
   

3. Add content to your post and save your changes.
4. Add your changes and commit them:

   git add -A
   git commit -m “first post”
   

5. Push your changes to your repository:
   git push origin main
6. Navigate to your GitHub repository and go to the Actions tab. You can see the Microsoft Azure and Vale pipelines running.
7. Once the pipelines complete successfully,
   1. Your changes are published automatically to your site.
   2. You can open the Vale pipeline to see the list of suggestions, errors, or warnings that Vale detected.

You can also run Vale locally before you push your changes if you want to work on the suggestions before you publish your changes by running the command:

vale <your_markdown_file>.md

See more details on Vale CLI usage documentation.