#11: Share Content with Docusaurus & Azure Static Web Apps
Tags: staticwebapps, beginners, react, javascript
Published: 2022-05-12 19:38:31

---
title: #11: Share Content with Docusaurus & Azure Static Web Apps
published: true
description: @AzureStaticApps turns 1 today 🎂 - join me for a Meta post on building content sites with @Docusaurus (also powers #30DaysOfSWA)  
tags: staticwebapps, beginners, react, javascript
series: Learn Static Web Apps with 30DaysOfSWA
canonical_url: https://www.azurestaticwebapps.dev/blog/build-with-docusaurus
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/j7qp4sgve1v3jyuwnx0s.png
---

> 🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖
> This post is now officially [added](https://docusaurus.io/docs/next/deployment#deploying-to-azure-static-web-apps) into the  <br/> next official Docusaurus documentation release adding <br/> **Azure Static Web Apps to deployment options**.
> 🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖🦖

---

Welcome to `Week 2, Day 4` of **#30DaysOfSWA**!! 

Today's a special day - the [1 year anniversary of Azure Static Web Apps](https://azure.microsoft.com/en-us/updates/azure-static-web-apps-is-now-generally-available/?WT.mc_id=30daysofswa-61155-cxall)! <br/> **Happy Birthday SWA! 🎂** I wanted to do something special to celebrate! 

So here it is - a blog post on how we can create a content-focused static website [with Docusaurus](https://docusaurus.io/) and deploy it [using Azure Static Web Apps](https://docs.microsoft.com/en-us/azure/static-web-apps/?WT.mc_id=30daysofswa-61155-cxall). Want to get a sense of what kinds of static sites you can build with Docusaurus? [Check out their showcase](https://docusaurus.io/showcase)!

Why **this** demo today? Well, it's very _Meta_ (pun intended). You may have noticed that the [#30DaysOfSWA](https://aka.ms/30DaysOfSWA) website is built on Docusaurus. 🦖

[![#30DaysOfSWA Website](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qu3ioc0144p7jxp76qf0.png)](https://aka.ms/30DaysOfSWA)

By sharing this tutorial, I'm hoping it inspires more of you to build/deploy sites that showcase your own tech journeys - whether its with #30Days of learning, or to feature your #100Devs portfolios. #LetsGetStarted! 🎉

----

## What We'll Cover
 * **Intro**: What is Docusaurus?
 * **Quickstart:** setup classic site
 * **Configure**: `docusaurus.config.js`
 * **Deploy**: Azure Static Web Apps
 * **Customize**: Themes & Plugins
 * **Exercise**: Try extending the demo further 

---

## About the Demo

In today's tutorial, we'll create a _classic_ Docusaurus site, deploy it to Azure Static Web Apps, then make some changes to the site content to validate that it rebuilds and deploys the site without any further manual effort from us. I hope to also contribute this back to the Docusaurus docs as an example for Deploying to Azure - feedback to improve this is very welcome!

* 🌟 **Tutorial source is here [on GitHub](https://github.com/fearlessly-dev/swa-demo-docusaurus)** - I'll update **that version** over time.
* 🎉  **Site is live [on Azure Static Web Apps](https://zealous-bay-0062c640f.1.azurestaticapps.net/)** - for demo purposes only.
* 🏆 **Site is showcased [on Docusaurus](https://docusaurus.io/showcase)

## Updated May 16:

Just one more thing - [**showcase it**](https://docusaurus.io/showcase) when done! 😍

{% twitter 1526202485551075329 %}

---

## What is Docusaurus?

Docusaurus is an open-source project from Meta that helps you build, deploy, and maintain, open source project websites. It was rated one of the top 3 [rising stars of JavaScript](https://docusaurus.io/) in 2021, under the _static site generators_ category. It has a number of features that made it attractive:
 * It has built-in support for search, localization and versioning
 * It support MDX (JSX-flavored Markdown) for richer content options
 * It has built-in support for themes and plugins to enhance default behaviors
 * It is built with React, making it extensible with custom components

Read their [documentation](https://docusaurus.io/docs) & visit their [showcase](https://docusaurus.io/showcase) to see real-world examples. Now, let's dive into our tutorial for building the demo.

---

## 1. Setup Site

* Setup a Docusaurus site (`classic` theme) in a dedicated folder (`www`) in repo. The command automatically installs the required packages and their dependencies.

```bash
 npx create-docusaurus@latest www classic
```

* Let's see what was created for us. The output has been cleaned up for clarity.

```
ls -l www/

README.md   
babel.config.js 
blog/              
docs/    
docusaurus.config.js               
node_modules/        
package-lock.json    
package.json           
sidebars.js                 
src/                  
static/    
```

*  Let's preview the site locally, to validate this worked.

```bash
cd www
npx docusaurus start

[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at http://localhost:3000/.
```

You should see something like this - this is the default landing page for the scaffolded Docusaurus site.

![Landing Page](https://www.azurestaticwebapps.dev/assets/images/11-landing-d8ebc8da5a467aeb258b6ff21c4f5022.png)

* The dev server supports hot reloading. Try making a minor change to the site source - for example edit `docusaurus.config.js` and change the `title` to **"My Static Web Apps Site"**. You should see this in your site preview, instantly:

![Landing Page Reloaded](https://www.azurestaticwebapps.dev/assets/images/11-reload-5e921244396d1bfeb1635ca0cbdacb66.png)

* You can now build a **production-ready** version of that site as follows. Note that the static files are generated in the **build/** directory.

```bash
cd www/
npm run build
..
..
[SUCCESS] Generated static files in "build".
[INFO] Use `npm run serve` command to test your build locally.
```

---

## 2. Deploy To Azure

Docusaurus is built using React - so you can use [the same configuration settings](https://docs.microsoft.com/en-us/azure/static-web-apps/front-end-frameworks) for Docusaurus, when deploying to Azure Static Web Apps. 

You have three options to  get started:
  * via browser with [the Azure Portal quickstart](https://docs.microsoft.com/en-us/azure/static-web-apps/getting-started?tabs=react)
  * via terminal with [the Azure CLI quickstart](https://docs.microsoft.com/en-us/azure/static-web-apps/get-started-cli?tabs=vanilla-javascript)
  * via IDE with [the VS Code Extension quickstart](https://docs.microsoft.com/en-us/azure/static-web-apps/getting-started?tabs=vanilla-javascript) 

If you prefer the first approach, click the button to go to the Azure portal, then follow the [quickstart](https://docs.microsoft.com/en-us/azure/static-web-apps/getting-started?tabs=react) guidance, but using *this* project's details instead.

[![Deploy to Azure button](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/?feature.customportal=false&WT.mc_id=30daysofswa-61155-cxall#create/Microsoft.StaticApp)


## 3... using VS Code

I'll use the [Visual Studio Code extension](https://docs.microsoft.com/en-us/azure/static-web-apps/getting-started?tabs=vanilla-javascript) to make this happen with just a few clicks. 

The whole process happens within the VS Code window, and takes just a few minutes from start to finish - _with guided prompts to help all the way_. For convenience, I've documented it step-by-step with screenshots (images valid for _VS Code ver 1.66.2_).

## 3.1 Install Extension

Open Visual Studio Code (IDE) in the project folder for your repo. Install the [Azure Static Web Apps extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestaticwebapps) by visiting this page and clicking "Install".

![VS Code Extension for SWA](https://www.azurestaticwebapps.dev/assets/images/11-extension-c840c2a0accf37e9736192e1958f12e5.png)

## 3.2. Find SWA Panel

When extension is installed, you should see this window in your VS Code editor, confirming readiness for use.

![VS Code Extension Installed](https://www.azurestaticwebapps.dev/assets/images/11-vscode-025c5fed556e79b72afe7ec0dbc49c41.png)

You'll find the Azure Static Web Apps options listed in a  section under "Azure".

The extension's [documentation page](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestaticwebapps) and its [GitHub](https://github.com/microsoft/vscode-azurestaticwebapps/wiki/Creating-a-Static-Web-App) page both provide detailed walkthroughs - check those for the most current process for this. We'll start by clicking the _Azure_ icon in the VS Code sidebar, then scrolling down till we see this `Static Web Apps` section.

## 3.3 Create SWA

Click the "+" button to start the **Create Static Web App** workflow.

![Activate SWA Extension](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ceau4cvci4gf96nh5igq.png)

The _"Create Static Web Apps"_ process will create (and commit) a GitHub actions workflow for you that will automate the build/deploy process for your site directly from your source on all future codebase changes.

So if you have _current pending codebase changes_ it will first prompt you to commit them before it does its magic! Let's get that done!

![Commit changes](https://www.azurestaticwebapps.dev/assets/images/11-commit-e4ebcc5c88eab1fec6fb83a0440f8932.png)


## 3.4 Configure SWA

The extension walks you through the five steps shown below, each with defaults already filled in for you. Customize them as shown, for this project:

> Step 1: Specify Project Name
![Step 1](https://www.azurestaticwebapps.dev/assets/images/11-swa-1-8cb3405b5fc4e11a4e3d383918af64e8.png)

> Step 2: Pick Azure region to deploy it in 
![Step 2](https://www.azurestaticwebapps.dev/assets/images/11-swa-2-655a8fad3066c3bbf9cd2bbf83d3b786.png) <br/>

> Step 3: Specify project name
![Step 3](https://www.azurestaticwebapps.dev/assets/images/11-swa-3-817208d7936e610e563ae813343b9920.png)

> Step 4: Pick framework used by app
![Step 4](https://www.azurestaticwebapps.dev/assets/images/11-swa-4-999a4b92b119f60873a0c11665a42e52.png)

> Step 5: Specify folder where site gets built by default 
![Step 5](https://www.azurestaticwebapps.dev/assets/images/11-swa-5-5175ad2d0baa4f50eb9cdd16a0a3757e.png)


## 3.5 Track Progress

In a few seconds, you'll see this alert - this indicates that the workflow is **creating and committing the GitHub Actions build/deploy workflow YAML** for you. 🎉

![Created](https://www.azurestaticwebapps.dev/assets/images/11-swa-created-e773df9ebd39489f9a193f29b8b11f45.png)

If you check your repository right now, you'll find the [relevant commit](https://github.com/fearlessly-dev/swa-demo-docusaurus/commit/1005a16c10bbbce51c8526a3c14253d1aec1a59c) and the [activated Actions flow](https://github.com/fearlessly-dev/swa-demo-docusaurus/actions/runs/2313039968) (labeled `ci: add Azure Static Web Apps worfklow`) in progress.

You can also track the progress and configuration settings of your app right there in the VS Code Sidebar, under the `Static Web Apps` section. _Look for the project name, and unroll contents.._

![Sidebar](https://www.azurestaticwebapps.dev/assets/images/11-swa-sidebar-a5431359ccd9a9680923b809465aad7a.png)


## 3.6 Browse Site! 

In a few second more, you'll get this alert:

![Deployed](https://www.azurestaticwebapps.dev/assets/images/11-swa-deployed-8ad55a927b2f4270a5223c8c03cda7ab.png)

Now, go to the sidebar section for your project, right-click the name to see the available menu options:

![Browse](https://www.azurestaticwebapps.dev/assets/images/11-swa-browse-af691ca869bdb57a2aedf4d6b8781761.png)

Click "Browse Site" to be taken to your live deployed Docusaurus website! That's it! A few clicks, customizing defaults - and you're done!

---

## 4. Customize It!

At this point, you can make any changes to the site source, commit them - and watch the site get rebuilt and deployed without any further action from you!

Here are some things to try:
 * Customize [styles or layout](https://docusaurus.io/docs/styling-layout)
 * Explore [plugins](https://docusaurus.io/docs/api/plugins) for SEO, Search etc.
 * Try [create/use MDX](https://docusaurus.io/docs/markdown-features/react#using-jsx-in-markdown) in content

I made a few example changes to the `docusaurus.config.js` file to personalize the landing page content to reflect my needs. 

And I updated the `src/css/custom.css` file to reflect new theme colors for dark/light mode - and replaced the `logo.svg` file.

Committing these changes should automatically rebuild and update the deployed site. Here is what they looked like in my local preview, before I committed the changes.

|Light Mode |  Dark Mode|
|:---|:---|
|![Light Mode](https://www.azurestaticwebapps.dev/assets/images/11-swa-light-d5adbe4e5651b33b64e27e41ac3cbced.png)|![Dark Mode](https://www.azurestaticwebapps.dev/assets/images/11-swa-dark-9ddedb1c4320bbdcd7108c1a171cba0c.png) |

🎉  **Check it out: The site is [live on Azure Static Web Apps](https://zealous-bay-0062c640f.1.azurestaticapps.net/)**

---

## Exercise

You saw a few things I did to customize the site. Now it's your turn! Here are a few challenges you can try out:

 * Complete the tutorial to deploy your own site!
 * Try Docusaurus customization: **add an MDX component!**
 * Try SWA customization: **add an API to fetch content!**
 * Try SWA customization: **add auth using Twitter - use it!**


## Resources:
 * [Docusaurus](https://docusaurus.io/) - documentation
 * [Azure Static Web Apps (SWA)](https://docs.microsoft.com/en-us/azure/static-web-apps/) - documentation
 * [#30DaysOfSWA](https://aka.ms/30DaysOfSWA) - guide tour to SWA.