Building and Deploying a Next.js Blog on Azure (with Markdown Support)

This post documents my full journey creating and deploying a personal tech blog using Next.js, Markdown, and Azure App Service. I built this to sharpen my skills with cloud-native deployment pipelines and modern frontend frameworks. Along the way, I ran into some pretty frustrating issues, but learned a lot by fixing them.

1. Setting Up the Blog Locally with Next.js

1. I initialized the blog using the following command:

   npx create-next-app@latest my-blog --typescript
   

2. I enabled:

   • TypeScript
   • Tailwind CSS (originally, later removed)
   • App Router

3. I added support for Markdown by installing:

   npm install gray-matter remark remark-html
   

4. Created a posts/ folder at the root for my Markdown blog entries.

5. Added dynamic routing in pages/posts/[slug].tsx to render .md files as blog posts.

2. Replacing Tailwind CSS

I initially used Tailwind but hit PostCSS plugin issues with version 4. I eventually decided to remove Tailwind entirely and instead apply my own custom styles using globals.css, aiming for an Obsidian-like aesthetic.

I added custom CSS rules for:

• Dark background
• Headings and paragraph styling
• Markdown typography

3. Adding Blog Metadata and Structure

Each .md file includes frontmatter for:

---
title: "My Blog Title"
date: "2025-04-01"
ai: 3
---

I wrote logic to parse and display this metadata on both the homepage and individual post pages, including a custom 1–5 "AI usage" meter to reflect how much help I got from ChatGPT.

4. Adding Navigation, Branding, and Design Elements

• Created a header with a clickable logo (Cloudnavium) that links back to /
• Positioned the logo inline with the page title
• Added a short summary and contact info at the bottom of the index
• Centered images in Markdown with CSS overrides

5. Connecting a Custom Domain from Namecheap

After purchasing a domain from Namecheap:

• I added a CNAME record pointing to the default name created with my Static Webapp.
• Verified domain ownership in Azure App Service via TXT record

6. Deploying to Azure Static Web Apps

I originally attempted to deploy using Azure App Service, but ran into persistent 503 errors and deployment failures. The root cause was that App Service is not optimized for static sites like mine (Next.js with static export). After hours of troubleshooting, I realized the correct solution was to use Azure Static Web Apps.

Here's how I fixed the entire deployment pipeline:

1. Created a Static Web App in the Azure Portal:

   • Connected directly to my GitHub repository and selected the main branch
   • App location: /
   • Output location: out
   • No API location

2. Updated my next.config.js:

   const nextConfig = {
     output: 'export'
   }
   
   module.exports = nextConfig;
   

3. Updated package.json to use the right build command:

   "scripts": {
     "build": "next build"
   }
   

4. Fixed the GitHub Actions workflow to use the correct deploy action:

   - uses: Azure/static-web-apps-deploy@v1
     with:
       azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
       repo_token: ${{ secrets.GITHUB_TOKEN }}
       action: "upload"
       app_location: "/"
       output_location: "out"
       api_location: ""
   

5. After pushing, the app was successfully deployed and served over Azure’s CDN at:

   https://<azure-generated-name>.azurestaticapps.net
   

6. I set my custom domain as default and redirected the generated domain to it automatically.

7. Setting Up a Custom Domain with Namecheap

Once the static site was live, I mapped my domain purchased from Namecheap:

1. In Azure:

   • Went to the Static Web App > Custom domains
   • Clicked Add and entered my domain

2. In Namecheap:

   • Added a TXT record to verify ownership (provided by Azure)
   • Added a CNAME record pointing www to my Azure static app domain

3. Enabled HTTPS and automatic redirects in Azure.

4. Optionally, I used a URL Redirect Record in Namecheap to forward @ (root) to www.mydomain.com.

Now, the site is fully live at:

https://cloudnavium.com

8. Lessons Learned

Things that went wrong.

1. Created an App Service in Azure when I should have made a Static Web App:

   • Runtime: Node 18 LTS
   • OS: Linux
   • Pricing Tier: Free (F1) initially

2. Ran into issues:

   • Node 22 incompatibility (had to downgrade to Node 18)
   • Incorrect repo structure (src/ folder confused Azure)
   • Pushed too large of a file initially (node_modules)
   • Git merge conflicts during rebase
   • Missing .github/workflows/*.yml file (had to restore it manually)

• Don’t push node_modules to GitHub, use .gitignore
• Tailwind v4 isn’t stable with PostCSS out-of-the-box in Azure
• Don't build the local project on Onedrive and don't use Onedrive as a makeshift version control, just use github
• Pay attention to the logs instead of balling out

Final Thoughts

This blog is my home base now where I’ll post about DevOps, Azure, AI, and other stuff I’m learning in public. It’s not perfect, and I’m still tweaking things, but I built it (basically entirely with ChatGPT prompts) from the ground up.

If you're working on your own blog or need help deploying a Next.js app, feel free to reach out. I'm happy to share what I’ve learned, including all the mistakes.

I used ChatGPT to organize my thoughts and summarize this journey, but every technical task, error, and configuration was done and debugged by me personally.