#11: Share Content with Docusaurus & Azure Static Web Apps

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

Right this moment’s a special occasion – the 1 year anniversary of Azure Static Web Apps!
Completely satisfied Birthday SWA! πŸŽ‚ I needed to do one thing particular to rejoice!

So right here it’s – a weblog put up on how we will create a content-focused static web site with Docusaurus and deploy it using Azure Static Web Apps. Need to get a way of what sorts of static websites you’ll be able to construct with Docusaurus? Check out their showcase!

Why this demo right this moment? Effectively, it’s extremely Meta (pun supposed). You might have seen that the #30DaysOfSWA web site is constructed on Docusaurus. πŸ¦–

By sharing this tutorial, I am hoping it evokes extra of you to construct/deploy websites that showcase your personal tech journeys – whether or not its with #30Days of studying, or to characteristic your #100Devs portfolios. #LetsGetStarted! πŸŽ‰




What We’ll Cowl

  • Intro: What’s Docusaurus?
  • Quickstart: setup basic website
  • Configure: docusaurus.config.js
  • Deploy: Azure Static Net Apps
  • Customise: Themes & Plugins
  • Train: Attempt extending the demo additional



In regards to the Demo

In right this moment’s tutorial, we’ll create a basic Docusaurus website, deploy it to Azure Static Net Apps, then make some modifications to the positioning content material to validate that it rebuilds and deploys the positioning with none additional handbook effort from us. I hope to additionally contribute this again to the Docusaurus docs for instance for Deploying to Azure – suggestions to enhance that is very welcome!




What’s Docusaurus?

Docusaurus is an open-source venture from Meta that helps you construct, deploy, and preserve, open supply venture web sites. It was rated one of many high 3 rising stars of JavaScript in 2021, below the static website turbines class. It has a variety of options that made it enticing:

  • It has built-in help for search, localization and versioning
  • It help MDX (JSX-flavored Markdown) for richer content material choices
  • It has built-in help for themes and plugins to boost default behaviors
  • It’s constructed with React, making it extensible with customized parts

Learn their documentation & go to their showcase to see real-world examples. Now, let’s dive into our tutorial for constructing the demo.




1. Setup Web site

  • Setup a Docusaurus website (basic theme) in a devoted folder (www) in repo. The command mechanically installs the required packages and their dependencies.
 npx create-docusaurus@newest www basic
Enter fullscreen mode

Exit fullscreen mode

  • Let’s examine what was created for us. The output has been cleaned up for readability.
ls -l www/

README.md   
babel.config.js 
weblog/              
docs/    
docusaurus.config.js               
node_modules/        
package-lock.json    
bundle.json           
sidebars.js                 
src/                  
static/    
Enter fullscreen mode

Exit fullscreen mode

  • Let’s preview the positioning regionally, to validate this labored.
cd www
npx docusaurus begin

[INFO] Beginning the event server...
[SUCCESS] Docusaurus web site is operating at http://localhost:3000/.
Enter fullscreen mode

Exit fullscreen mode

You must see one thing like this – that is the default touchdown web page for the scaffolded Docusaurus website.

Landing Page

  • The dev server helps scorching reloading. Attempt making a minor change to the positioning supply – for instance edit docusaurus.config.js and alter the title to “My Static Net Apps Web site”. You must see this in your website preview, immediately:

Landing Page Reloaded

  • Now you can construct a production-ready model of that website as follows. Be aware that the static recordsdata are generated within the construct/ listing.
cd www/
npm run construct
..
..
[SUCCESS] Generated static recordsdata in "construct".
[INFO] Use `npm run serve` command to take a look at your construct regionally.
Enter fullscreen mode

Exit fullscreen mode




2. Deploy To Azure

Docusaurus is constructed utilizing React – so you need to use the same configuration settings for Docusaurus, when deploying to Azure Static Net Apps.

You’ve got three choices to get began:

In the event you favor the primary strategy, click on the button to go to the Azure portal, then observe the quickstart steerage, however utilizing this venture’s particulars as an alternative.

Deploy to Azure button



3… utilizing VS Code

I will use the Visual Studio Code extension to make this occur with only a few clicks.

The entire course of occurs throughout the VS Code window, and takes only a few minutes from begin to end – with guided prompts to assist all the way in which. For comfort, I’ve documented it step-by-step with screenshots (photographs legitimate for VS Code ver 1.66.2).



3.1 Set up Extension

Open Visible Studio Code (IDE) within the venture folder to your repo. Set up the Azure Static Web Apps extension by visiting this web page and clicking “Set up”.

VS Code Extension for SWA



3.2. Discover SWA Panel

When extension is put in, it is best to see this window in your VS Code editor, confirming readiness to be used.

VS Code Extension Installed

You may discover the Azure Static Net Apps choices listed in a part below “Azure”.

The extension’s documentation page and its GitHub web page each present detailed walkthroughs – examine these for probably the most present course of for this. We’ll begin by clicking the Azure icon within the VS Code sidebar, then scrolling down until we see this Static Net Apps part.



3.3 Create SWA

Click on the “+” button to start out the Create Static Net App workflow.

Activate SWA Extension

The “Create Static Net Apps” course of will create (and commit) a GitHub actions workflow for you that can automate the construct/deploy course of to your website immediately out of your supply on all future codebase modifications.

So when you have present pending codebase modifications it can first immediate you to commit them earlier than it does its magic! Let’s get that finished!

Commit changes



3.4 Configure SWA

The extension walks you thru the 5 steps proven under, every with defaults already crammed in for you. Customise them as proven, for this venture:

Step 1: Specify Mission Title
Step 1

Step 2: Choose Azure area to deploy it in
Step 2

Step 3: Specify venture title
Step 3

Step 4: Choose framework utilized by app
Step 4

Step 5: Specify folder the place website will get constructed by default
Step 5



3.5 Observe Progress

In a number of seconds, you may see this alert – this means that the workflow is creating and committing the GitHub Actions construct/deploy workflow YAML for you. πŸŽ‰

Created

In the event you examine your repository proper now, you may discover the relevant commit and the activated Actions flow (labeled ci: add Azure Static Net Apps worfklow) in progress.

You can even monitor the progress and configuration settings of your app proper there within the VS Code Sidebar, below the Static Net Apps part. Search for the venture title, and unroll contents..

Sidebar



3.6 Browse Web site!

In a number of second extra, you may get this alert:

Deployed

Now, go to the sidebar part to your venture, right-click the title to see the obtainable menu choices:

Browse

Click on “Browse Web site” to be taken to your reside deployed Docusaurus web site! That is it! Just a few clicks, customizing defaults – and also you’re finished!




4. Customise It!

At this level, you may make any modifications to the positioning supply, commit them – and watch the positioning get rebuilt and deployed with none additional motion from you!

Listed below are some issues to strive:

I made a number of instance modifications to the docusaurus.config.js file to personalize the touchdown web page content material to replicate my wants.

And I up to date the src/css/customized.css file to replicate new theme colours for darkish/mild mode – and changed the emblem.svg file.

Committing these modifications ought to mechanically rebuild and replace the deployed website. Here’s what they regarded like in my native preview, earlier than I dedicated the modifications.

Gentle Mode Darkish Mode
Light Mode Dark Mode

πŸŽ‰ Test it out: The positioning is live on Azure Static Web Apps




Train

You noticed a number of issues I did to customise the positioning. Now it is your flip! Listed below are a number of challenges you’ll be able to check out:

  • Full the tutorial to deploy your personal website!
  • Attempt Docusaurus customization: add an MDX element!
  • Attempt SWA customization: add an API to fetch content material!
  • Attempt SWA customization: add auth utilizing Twitter – use it!



Sources:

Add a Comment

Your email address will not be published. Required fields are marked *