Planning a developer portfolio website

A portfolio site is the one place where you choose the order in which a reader meets your work. A reader who follows the link on your resume may read only its first page, so that page must say who you are, show two or three projects with their results and give a way to reach you, and the rest of the site supports it.

This lesson plans the site of Farah, the invented data analyst of the GitHub lessons: the pages it needs and what each must prove, a home page that works in one screen, an address on GitHub Pages, and contact routes that never hand out her phone number.

Five pages, each with one job

Plan the site from what a reader must be able to check, not from a template. Five pages cover it (MySmartCoPilot guidance), and on a one-page site, which is fine for a student, they become five sections:

Step through the path most readers take through Farah’s site:

Each case-study page is the kind of page writing a project case study builds. The program checks Farah’s first plan and her final one against the table:

# Checks the plan of an invented data analyst's portfolio site, Farah's, before and after, against the pages this
# lesson plans (MySmartCoPilot guidance): a home page that features two or three case studies and links the contact
# route, a page for each case study, an about page, a resume page with an HTML version and a PDF, and a contact route
# without a home address or a personal phone number. Press Edit, describe your own site in MINE, and run it again.
import re

BEFORE = {
    "/": {"kind": "home", "links": ["/about/", "/blog/"]},
    "/about/": {"kind": "about", "links": ["/"]},
    "/blog/": {"kind": "blog", "links": ["/"]},
    "/projects/": {"kind": "list", "links": ["/projects/library-loans/"]},
    "/projects/library-loans/": {"kind": "case-study", "links": ["/"]},
    "/contact/": {"kind": "contact", "text": "Call me on +91 90000 12345, or visit Flat 4B, 12 Lake Road, Kolkata."},
}
AFTER = {
    "/": {"kind": "home", "links": ["/projects/library-loans/", "/projects/rainfall/", "/projects/ward-maps/",
                                    "/resume/", "/contact/"]},
    "/projects/library-loans/": {"kind": "case-study", "links": ["/", "/resume/"]},
    "/projects/rainfall/": {"kind": "case-study", "links": ["/"]},
    "/projects/ward-maps/": {"kind": "case-study", "links": ["/"]},
    "/about/": {"kind": "about", "links": ["/"]},
    "/resume/": {"kind": "resume", "formats": ["html", "pdf"], "links": ["/"]},
    "/contact/": {"kind": "contact",
                  "text": "Write to farah.jobs@example.com, or find me on LinkedIn. I live in Kolkata."},
}
MINE = None  # your own site, in the same shape
PHONE = re.compile(r"\+?\d[\d -]{8,}\d")
STREET = re.compile(r"\b(?:flat|road|street|lane|nagar|house)\b", re.I)


def checks(site):
    pages = list(site.values())
    home = next((p for p in pages if p["kind"] == "home"), {"links": []})
    studies = [url for url, p in site.items() if p["kind"] == "case-study"]
    featured = [url for url in home["links"] if url in studies]
    resume = next((p for p in pages if p["kind"] == "resume"), {})
    contact = next((p for p in pages if p["kind"] == "contact"), {})
    linked = [site[url]["kind"] for url in home["links"] if url in site]
    return {
        "two or three case studies on the home page": 2 <= len(featured) <= 3,
        "a page for each case study": len(studies) >= 2,
        "an about page": any(p["kind"] == "about" for p in pages),
        "a resume in HTML and as a PDF": {"html", "pdf"} <= set(resume.get("formats", [])),
        "a contact route linked from home": bool(contact) and "contact" in linked,
        "no phone number or street address": bool(contact) and not PHONE.search(contact["text"])
        and not STREET.search(contact["text"]),
    }


for label, site in [("before", BEFORE), ("after", AFTER)] + ([("mine", MINE)] if MINE else []):
    found = checks(site)
    print(f"{label}: {len(site)} pages, {sum(found.values())} of {len(found)} checks pass")
    for name, ok in found.items():
        if not ok:
            print(f"  fails: {name}")

before: 6 pages, 1 of 6 checks pass
  fails: two or three case studies on the home page
  fails: a page for each case study
  fails: a resume in HTML and as a PDF
  fails: a contact route linked from home
  fails: no phone number or street address
after: 7 pages, 6 of 6 checks pass

Her first plan passed 1 check of 6. Its home page linked an about page and a blog, but no case study and no contact page; it had one case study and no resume, and its contact page gave her phone number and street address. The final plan has seven pages and passes all six. A blog can stay, but it is not one of the five jobs, so it no longer takes the space on the home page that the case studies need.

The home page answers three questions in one screen

The top of the home page, its herohero: The first block of a web page, shown before the reader scrolls. On a portfolio's home page it says who you are, the work you want and what you build., answers who you are, what you build and where the proof is, before the reader scrolls. Farah’s first hero spends its words on enthusiasm; the second spends about as many on facts. The program checks both:

# Checks two hero texts, the first words of Farah's home page, for what a reader needs on the first screen: her name,
# the role she wants, what she builds, and one result with a number, in at most 40 words. The checks and the 40-word
# budget are MySmartCoPilot guidance. Press Edit, paste your own hero text into MINE, and run it again.
import re

BEFORE = ("Welcome to my corner of the internet! I'm a passionate, curious and detail-oriented data enthusiast who "
          "loves turning chaos into clarity. Explore my journey, my skills and my projects below, and let's connect!")
AFTER = ("Farah Siddiqui, data analyst, looking for a first full-time role. I build dashboards and reports from public "
         "and college data: the college library now reorders books from my dashboard of three years of loans.")
MINE = None  # your own hero text
NAME = "Farah"
ROLE = re.compile(r"\b(analyst|developer|engineer|designer|scientist)\b", re.I)
BUILDS = re.compile(r"\b(dashboards?|reports?|pipelines?|models?|apps?|APIs?|services?|websites?|tools?)\b", re.I)


def checks(text):
    words = re.findall(r"[\w'-]+", text)
    return {
        "her name": NAME in text,
        "the role she wants": bool(ROLE.search(text)),
        "what she builds": bool(BUILDS.search(text)),
        "a result with a number": bool(re.search(r"\b\d|\b(?:one|two|three|four|five|six|seven|eight|nine|ten)\b", text)),
        "at most 40 words": len(words) <= 40,
    }, len(words)


for label, text in [("before", BEFORE), ("after", AFTER)] + ([("mine", MINE)] if MINE else []):
    found, count = checks(text)
    print(f"{label}: {count} words, {sum(found.values())} of {len(found)} checks pass")
    for name, ok in found.items():
        if not ok:
            print(f"  fails: {name}")

before: 33 words, 1 of 5 checks pass
  fails: her name
  fails: the role she wants
  fails: what she builds
  fails: a result with a number
after: 34 words, 5 of 5 checks pass

The first hero, 33 words, passes 1 check of 5: it is short, and it says nothing else a reader can use. The second, 34 words, passes all five. It names a role and a kind of work, so a reader knows at once which postings she fits, and it gives one result that the case study linked under it can prove. The budget of 40 words is MySmartCoPilot guidance: it leaves room on a phone’s first screen for the case studies, which are the next thing a reader looks for. Under the hero, show each featured case study as a short card: its title, one line with its result and a link.

GitHub Pages gives a site one of two kinds of address

GitHub Pages serves a site from a repository, in two kinds. A user siteuser site: A GitHub Pages site published from a repository named <owner>.github.io, in lower case, and served at https://<owner>.github.io/. Each account can have one. is published from a repository named <owner>.github.io, in lower case, and served at https://<owner>.github.io/; an account has one. Any other repository can publish a project siteproject site: A GitHub Pages site published from any other repository of an account and served at https://<owner>.github.io/<repository>/, or under the user site's custom domain. at https://<owner>.github.io/<repository>/. In the repository’s Pages settings you choose its publishing sourcepublishing source: What GitHub Pages publishes a site from, chosen in the repository's Pages settings: a branch, from its root or its /docs folder, or a GitHub Actions workflow.: a branch, from its root or its /docs folder, or a GitHub Actions workflow. The program works out the address of each kind for Farah’s account:

# Works out the address GitHub Pages gives each of an account's sites, by the rules of GitHub Docs: a user site is
# published from a repository named <owner>.github.io, in lower case, and served at https://<owner>.github.io/, one per
# account; any other repository publishes a project site at https://<owner>.github.io/<repository>/; a custom domain on
# the user site is used by the account's project sites too, unless a project site sets its own. The account and its
# domains are invented (.example is a name reserved for examples). Press Edit, try your own names, and run it again.
OWNER = "Farah-Example"


def address(repository, user_domain=None, own_domain=None):
    owner = OWNER.lower()
    if repository.lower() == f"{owner}.github.io":
        if repository != f"{owner}.github.io":
            return f"no site: name the repository {owner}.github.io, in lower case"
        return f"https://{user_domain}/" if user_domain else f"https://{owner}.github.io/"
    if own_domain:
        return f"https://{own_domain}/"
    return f"https://{user_domain}/{repository}/" if user_domain else f"https://{owner}.github.io/{repository}/"


CASES = [
    ("The user site", "farah-example.github.io", None, None),
    ("A project site", "library-loans-dashboard", None, None),
    ("The user site, with a custom domain", "farah-example.github.io", "www.farah.example", None),
    ("The project site, under that domain", "library-loans-dashboard", "www.farah.example", None),
    ("A project site with its own domain", "rainfall-analysis", "www.farah.example", "rain.farah.example"),
    ("A user site named with capitals", "Farah-Example.github.io", None, None),
]
for label, repository, user_domain, own_domain in CASES:
    print(f"{label}:\n  {repository} -> {address(repository, user_domain, own_domain)}")

The user site:
  farah-example.github.io -> https://farah-example.github.io/
A project site:
  library-loans-dashboard -> https://farah-example.github.io/library-loans-dashboard/
The user site, with a custom domain:
  farah-example.github.io -> https://www.farah.example/
The project site, under that domain:
  library-loans-dashboard -> https://www.farah.example/library-loans-dashboard/
A project site with its own domain:
  rainfall-analysis -> https://rain.farah.example/
A user site named with capitals:
  Farah-Example.github.io -> no site: name the repository farah-example.github.io, in lower case

The portfolio belongs on the user site, at the shortest address the account has, and each demo on a project site. A custom domain set on the user site moves the project sites under it too, unless one sets its own, as the rainfall analysis does. Take your own domain only if you will keep renewing it. GitHub recommends a www subdomain and verifying the domain before you add it, because a disabled site whose custom domain still points at GitHub is at risk of a domain takeoverdomain takeover: Someone else serving their own content at your domain. GitHub warns that a disabled Pages site with a custom domain is at risk, and verifying the domain stops other users taking it.. Answer two questions to choose:

In short: the portfolio on the user site, each demo on a project site, and a domain of your own only if you will look after it.

GitHub Pages’ limits are far above what a portfolio needs. A published site may be at most 1 GB; traffic has a soft ceiling of 100 GB of bandwidth monthly, and builds a soft ceiling of 10 per hour, which is lifted when your own Actions workflow builds the site. It is not meant for running an online business or for sensitive transactions such as passwords or card numbers, a site is public on the internet even when its repository is private, and a push can take up to 10 minutes to appear. A new site on github.io is served over HTTPS; with a custom domain, select Enforce HTTPS in the Pages settings. For other hosts and their rules, see hosting demos without paying.

Contact routes that do not expose you

GitHub says it records and keeps the IP address of every visitor to a GitHub Pages site, for security, whether or not that visitor is signed in to GitHub. Say so in a line on the site, and say so as well about anything you add, such as an analytics script. The same care runs the other way: whatever you publish about yourself stays findable long after the job search.

The resume you offer as a PDF on the site is public too, so give it the same contact block as the site: the job-mail address and your city. Once the site is live, search your name. Google’s Results about you looks for search results carrying your phone number, home address or e-mail address, and you can ask Google to drop each one from its results; what not to publish covers the rest of a job seeker’s privacy.

Practise: plan Arjun’s site

Arjun’s first plan has a blog but no about page, a resume without a web version, and his phone number and street on the contact page. Fix it from his records; the sample tests check the five jobs of this lesson:

# Arjun's first plan for his portfolio site: each page's address, its kind, the pages it links and, for the contact
# page, its text. Fix it from his records in the prompt.
SITE = {
    "/": {"kind": "home", "links": ["/blog/"]},
    "/blog/": {"kind": "blog", "links": ["/"]},
    "/projects/seat-booker/": {"kind": "case-study", "links": ["/"]},
    "/projects/mess-menu-api/": {"kind": "case-study", "links": ["/"]},
    "/resume/": {"kind": "resume", "formats": ["pdf"], "links": ["/"]},
    "/contact/": {"kind": "contact", "links": ["/"], "text": "Phone: +91 90000 00000. Home: 7 Station Road, Nagpur."},
}

import re

from arjun_site import SITE

PHONE = re.compile(r"\+?\d[\d -]{8,}\d")
STREET = re.compile(r"\b(?:flat|road|street|lane|nagar|house)\b", re.I)


def pages(kind):
    return [url for url, page in SITE.items() if page["kind"] == kind]


def test_home_features_case_studies():
    """has a home page that features two or three case studies, each with a page of its own"""
    assert pages("home"), "the site needs a home page"
    studies = pages("case-study")
    featured = [url for url in SITE[pages("home")[0]]["links"] if url in studies]
    assert len(studies) >= 2, "give at least two projects a case-study page"
    assert 2 <= len(featured) <= 3, f"the home page links {len(featured)} case studies: feature two or three"


def test_about_and_resume():
    """has an about page and a resume page with an HTML version and a PDF"""
    assert pages("about"), "add an about page: a short bio and your current focus"
    assert pages("resume"), "add a resume page"
    formats = set(SITE[pages("resume")[0]].get("formats", []))
    assert {"html", "pdf"} <= formats, f"the resume page offers {sorted(formats)}: give an HTML page and a PDF"


def test_contact_linked_and_safe():
    """links a contact page from home, with a route for job mail and no phone number or street address"""
    assert pages("contact"), "add a contact page"
    contact = SITE[pages("contact")[0]]
    assert pages("contact")[0] in SITE[pages("home")[0]]["links"], "link the contact page from the home page"
    text = contact["text"]
    assert "@" in text or "form" in text.lower(), "give an e-mail address for job mail, or a form"
    assert not PHONE.search(text), "no phone number on a public page"
    assert not STREET.search(text), "no street address on a public page: a city is enough"

Then test yourself on the plan, the hero, the address and the contact routes; the questions begin where your answers have been weakest:

Interview questions

Warm-up (fresher to mid-level): What pages does a developer portfolio site need?

Five jobs, as five pages or as five sections of one page. A home page says who I am and the work I want, and features two or three case studies with a result each. Each case study proves one project, with links to its code and its demo. An about page gives a short bio and my current focus, a resume page offers the resume as a web page and as a PDF, and a contact page gives an address for job mail and my city, never my phone number or street.

Warm-up (fresher to mid-level): How does a GitHub Pages user site differ from a project site?

A user site is published from a repository named after my account, <owner>.github.io in lower case, and is served at https://<owner>.github.io/; an account has only one. A project site can be published from any other repository and is served at https://<owner>.github.io/<repository>/. I put my portfolio on the user site and each project’s demo on its own project site. If I set a custom domain on the user site, the project sites move under that domain too.

Two questions of this module’s bank go further:

Key takeaways

• A portfolio has five jobs: a home page that sends the reader to proof, a case study per project, an about page, a resume as a web page and a PDF, and a contact route.
• The home page’s first words say who you are, the work you want, what you build and one result, in about 40 words, with two or three case studies right under them.
• GitHub Pages serves one user site per account at <owner>.github.io and a project site per repository under it; take a custom domain only if you will keep renewing it, and verify it.
• Give the site one route for job mail and your city, never your phone number or home address, and say that GitHub Pages logs visitors’ IP addresses.