On-Page SEO Checklist for a Developer Portfolio

An on-page SEO checklist for a developer portfolio comes down to making every page easy to understand: a unique title and meta description, one clear H1, readable URLs, descriptive image alt text and structured data that says who you are. Add a sitemap, then use Google Search Console to see what Google has actually indexed. None of this guarantees a ranking, but it addresses the common reasons a small portfolio stays invisible. If you are wondering how to get your portfolio to show up on Google, there are two jobs. Google has to find and index your pages, and your pages have to say clearly what they are about. I am a final-year Computer Science student at KFUEIT who does SEO work, and I use these checks on my own portfolio, which is built with Next.js.

Why does every page need its own title and meta description?

The title tag is the link people see in search results, and the meta description is the text Google may use for the snippet under it. Google can rewrite either one when it thinks another version fits a search better, so treat them as strong suggestions. The SEO starter guide from Google covers both. Pages that share a title are harder for search engines to tell apart. On a portfolio that usually means the default "Portfolio" title copied across every route. Put the page's main topic first and keep the title near 60 characters, since longer ones tend to be cut off (Google sets no fixed limit). Write the description as one or two plain sentences that tell a visitor what they will find.

Html

<!-- Before -->
<title>Home | Portfolio</title>
<meta name="description" content="Welcome to my website." />

<!-- After -->
<title>Fawaz Israr | Full Stack Developer (Next.js, MERN)</title>
<meta name="description" content="Final-year Computer Science student building full-stack apps with Next.js and MERN. See my projects and read my notes on SEO and web development." />

In the App Router you do not write those tags by hand. Each page.tsx exports a metadata object (or generateMetadata for dynamic routes such as blog posts) and Next.js renders the tags. I covered that code in technical SEO for Next.js.

How should I structure headings and URLs?

Use one H1 per page and make it name the page. On the home page that is your name and what you do, and on a project page it is the project name. I stick to one because it keeps the outline simple for readers and screen readers. Below it, use H2 for main sections and H3 for parts of a section, and do not jump levels to get a smaller font. For URLs, short lowercase words separated by hyphens work well. This post lives at /blog/on-page-seo-checklist-developer-portfolio, so the topic is visible before the page loads. Avoid query strings like /p?id=48 and underscores. Pick the slug before you publish. If you must change one afterwards, add a redirect (the redirects option in next.config.ts does this) so old links still land somewhere.

What makes image alt text and file names useful?

Alt text describes what an image shows. Screen readers read it out, and search engines use it to understand a picture. Write it the way you would describe the image to a friend over the phone: "Screenshot of the GoCart storefront" beats "image" and beats a string of keywords. If an image is purely decorative, use an empty alt so assistive tools skip it. File names count too. A name like gocart-storefront.jpg hints at the content and IMG_4021.jpg hints at nothing, so rename files before you upload them. Give each image a real width and height (the Image component from next/image usually asks for them) so the layout does not jump while it loads. That jump is the layout shift measured in Core Web Vitals explained.

How does internal linking help a small portfolio?

Search engines discover pages by following links, and a page that nothing links to is easy to miss. Link the home page to each project, each project back to the About page and to any related post, and keep the navigation as real links. The Link component from Next.js renders ordinary anchor elements, which crawlers can follow. Anchor text should say where the link goes. A sentence like "my multi-vendor store, GoCart" tells a reader and a crawler more than "click here" does.

Do I need Person structured data on my portfolio?

You do not need it, but it is cheap, and a portfolio is about one person, which is what the schema.org Person type describes. Structured data is extra markup, usually JSON-LD in a script tag, that states facts for machines: this site belongs to this person, and these are their profiles elsewhere. Google does not promise a special result for Person markup, so do not expect a visible change in the results page. The sameAs property lists your profiles on other sites. Only include accounts you really own, and replace the placeholder usernames below.

Tsx

// src/app/page.tsx (home page)
const personJsonLd = {
  "@context": "https://schema.org",
  "@type": "Person",
  name: "Fawaz Israr",
  url: "https://example.com",
  jobTitle: "Full stack developer",
  sameAs: [
    "https://github.com/your-username",
    "https://www.linkedin.com/in/your-username",
  ],
};

export default function Home() {
  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(personJsonLd).replace(/</g, "\\u003c"),
        }}
      />
      {/* page content */}
    </>
  );
}

Check the syntax with the Schema Markup Validator (validator.schema.org). Google's Rich Results Test will probably report nothing for plain Person markup, because Google has no search feature built on it. The replace call escapes any less-than character so a stray one in your data cannot close the script tag early, a step the Next.js docs also show. Use one name everywhere. If the site says Fawaz Israr, your GitHub and LinkedIn profiles should say it too, with a similar one-line bio and the portfolio address in their website fields. Link both ways: the profiles point to the site, and the About page points to them. I cannot cite a Google statement that matching names change rankings. I do it so that anyone checking you out lands on the same person every time.

What do canonical URLs, sitemap.xml and robots.txt do?

A canonical URL tells search engines which address is the main one when a page can be reached several ways: with or without www, with a trailing slash, with tracking parameters, or on a hosting preview address as well as your real domain. In Next.js, set metadataBase once in the root layout and alternates.canonical on each page. A sitemap.xml lists the URLs you want indexed, and the App Router can generate it from app/sitemap.ts. A robots.txt file at the root of the domain says which paths crawlers may fetch and where the sitemap is.

Text

User-agent: *
Allow: /
Sitemap: https://example.com/sitemap.xml

Robots.txt controls crawling, and a blocked URL can still be listed if other sites link to it. Do not use it to hide a private page. Put that page behind a login or add a noindex rule instead.

How do I check my results in Google Search Console?

Search Console is free, and the getting started guide explains how to add a property. Verify ownership with a DNS record for a domain property, or with an HTML tag or file for a URL-prefix property. Next.js can render the tag for you through the verification field in the metadata export. After that, do three things. Submit your sitemap in the Sitemaps report. Paste a page address into the URL Inspection tool to see whether it is indexed and, for a new page, request indexing. Then open the Page indexing report to see why any pages were left out. A status such as "Crawled, currently not indexed" is worth reading closely, and the usual response is to improve the page and its internal links, then wait. Indexing a new site can take days or longer, and a request guarantees nothing. After a few weeks the Performance report shows the queries that produced impressions, your clicks and your average position. If a page gets impressions but few clicks, rewrite its title and description and check again later.

What is the full on-page SEO checklist for a developer portfolio?

Copy this and tick items off page by page.

Give every page a unique title near 60 characters, with the main topic first.
Write a unique meta description of one or two plain sentences.
Use one H1 per page that names the page.
Order headings H2 then H3 without skipping levels, and size them with CSS.
Use short lowercase hyphenated URL slugs, and add a redirect if one changes.
Rename image files to describe their content before uploading.
Write alt text for each meaningful image and leave it empty for decorative ones.
Set width and height on images to avoid layout shift.
Link every page from at least one other page, with descriptive anchor text.
Add Person JSON-LD with real sameAs links to the home page, and check it with the Schema Markup Validator.
Use the same name and a matching short bio on your portfolio, GitHub and LinkedIn.
Set a canonical URL on each page and metadataBase in the root layout.
Generate a sitemap.xml and put its address in robots.txt.
Verify the site in Search Console and submit the sitemap.
Inspect your key URLs, request indexing for new pages, and read the Performance report again after a few weeks.

Cover photo from Unsplash.