How to Build a Remote Work Portfolio Site with Vercel and MDX

User avatar placeholder
Written by Tamzid Ahmed

September 10, 2026

Full‑stack developers who land remote gigs need a showcase that loads instantly, ranks well, and lets hiring managers explore code samples without friction. In this guide we build a remote work portfolio site on Vercel using MDX, covering everything from project setup to continuous deployment.

Why a Remote Work Portfolio Matters for Developers

A well‑crafted portfolio is more than a résumé; it’s a live demonstration of your tech stack, design thinking, and problem‑solving style. Recruiters often compare portfolios side‑by‑side, so performance, accessibility, and clear documentation become decisive factors.

Prerequisites and Toolchain

Before writing code, make sure you have the following installed:

  • Node.js 20+ (LTS)
  • Git for version control
  • Vercel CLI (npm i -g vercel)
  • Next.js 14 – the framework that powers Vercel’s edge network
  • MDX 2 – lets you write JSX inside Markdown files

These tools keep the workflow lean and allow you to ship updates with a single command.

Setting Up the Project with Next.js and MDX

Start by creating a fresh Next.js app that includes MDX support out of the box.

  1. Run npx create-next-app@latest my-portfolio --typescript
  2. Navigate into the folder: cd my-portfolio
  3. Install MDX dependencies: npm i @next/mdx @mdx-js/react
  4. Create next.config.mjs and add the MDX plugin:
import mdx from "@next/mdx";
export default mdx({
  extension: /.(md|mdx)$/,
});

Now any .mdx file placed in pages or components will be rendered as a React component.

Configuring MDX for Project Showcases

To keep portfolio entries consistent, create a reusable ProjectCard component that expects front‑matter like title, tech, link, and github. Use gray-matter to parse the front‑matter.

import matter from "gray-matter";
export async function getStaticProps() {
  const files = await fs.readdir("content/projects");
  const projects = files.map((filename) => {
    const file = fs.readFileSync(`content/projects/${filename}`, "utf8");
    const { data, content } = matter(file);
    return { ...data, content };
  });
  return { props: { projects } };
}

Each MDX file now lives in content/projects and can include interactive code snippets thanks to JSX support.

Adding Dynamic Project Data

Because MDX compiles to React, you can embed live CodeSandbox or ReactLive components to let visitors toggle themes or view component state. This dynamic element signals that you can ship production‑ready interactivity.

Optimizing SEO and Performance

Search engines treat static HTML as authoritative. Vercel’s edge network serves pre‑rendered HTML for every route, so ensure you generate static pages for each project.

  • Use next/head to set unique <title> and meta description per project.
  • Generate an sitemap.xml with next-sitemap to improve crawlability.
  • Compress images with next/image – it automatically serves WebP on supported browsers.

Run a Lighthouse audit after deployment; aim for a Performance score above 95 to impress both recruiters and hiring managers.

Deploying to Vercel

Vercel provides a zero‑config CI/CD pipeline that works directly with GitHub. Follow these steps to get your site live:

  1. Push the repository to GitHub (or GitLab). Ensure vercel.json contains the correct outputDirectory (usually .next).
  2. Run vercel in your terminal. The CLI will prompt for project name and link to the Git repo.
  3. Select the “Static Site Generation” option when asked. Vercel will detect the next.config.mjs file automatically.
  4. After the first build, Vercel generates a preview URL. Verify that images load, meta tags are correct, and the /projects page lists every MDX entry.
  5. Finally, enable the “Custom Domain” feature in the dashboard and point your domain’s CNAME to cname.vercel-dns.com.

These five steps are succinct enough for a featured snippet, and they cover the entire deployment workflow.

Keeping Your Portfolio Updated

Remote work contracts evolve quickly. Automate updates with a simple GitHub Action that runs on a schedule and pulls new data from a private Trello board or Notion database.

name: Sync Projects
on:
  schedule:
    - cron: "0 0 * * MON"
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Update MDX files
        run: node scripts/sync-projects.js
      - name: Commit & Push
        run: |
          git config user.name "github-actions"
          git add .
          git commit -m "chore: sync projects"
          git push

With this automation, your portfolio stays fresh without manual effort, reinforcing the impression of an active, engaged developer.

Conclusion

Building a remote work portfolio site with Vercel and MDX gives full‑stack developers a fast, SEO‑friendly platform to display projects, demonstrate live code, and impress remote hiring teams. Follow the step‑by‑step workflow, leverage static generation for performance, and automate updates to keep the site current. Start today by deploying a minimal prototype and iterate based on recruiter feedback.

Leave a Comment