Developer Portfolio and Blog Generator from GitHub and Markdown
Most students have a GitHub profile full of unexplained repositories and no page that says what they have built. Build a generator that turns a small config file, selected GitHub repositories and Markdown posts into a fast static portfolio and blog, with proper SEO metadata, generated Open Graph images and a scheduled rebuild. Other students can fork it and publish their own site in an afternoon, which gives you real users to test with.
Beginner
Achievable by one student in a semester with familiar tools.1 semester · 1 to 2 students
7 to ship
4 optional extrasSuggested stack
What you should ship
- A template repository with a documented YAML config for profile, links and featured repositories
- Build-time GitHub data fetching with caching and a token kept in repository secrets
- Project pages and a Markdown blog with tags, reading time and an RSS feed
- Titles, descriptions, canonical URLs, a sitemap and JSON-LD on every page
- Generated Open Graph images for the home page, each project and each post
- A GitHub Actions workflow that rebuilds on push and once a day and deploys to a static host
- A trial with at least ten students measuring time from fork to live site, with Lighthouse results in the report
If you have time left
- A command line tool that creates the config by asking a few questions
- Draft posts with private preview links
- Suggestions for which repositories to feature, based on README quality and recent activity
- Custom domain support with setup instructions for common domain registrars
Problem
A mentor or hiring manager who opens a student's GitHub sees repositories named project1, assignment-3 and test. The work may be good, but nothing explains it. A personal site helps, but students either spend weeks on a design they never finish or use a template that is slow, has no metadata and looks like everyone else's.
What you build
A template repository and a small build tool:
- A YAML config file with the student's name, headline, links and the repositories to feature.
- A build step that pulls each featured repository's description, languages, stars, last commit date and README summary from the GitHub API.
- Project pages generated from that data, with an optional Markdown file per project for the story: the problem, what the student did and what they learned.
- A blog built from Markdown files, with tags, reading time and an RSS feed.
- SEO: titles, descriptions, canonical URLs, a sitemap, JSON-LD for the person and each post, and an Open Graph image generated at build time for every page.
- A GitHub Actions workflow that rebuilds and deploys the site on every push and once a day.
Suggested architecture
- A static site generator such as Astro, or Next.js with static export, deployed to GitHub Pages, Cloudflare Pages or Netlify.
- Fetch GitHub data at build time only, with a token stored as a repository secret, and cache responses so builds stay inside rate limits.
- Generate Open Graph images with Satori or a headless browser, at the recommended 1200 by 630 pixels.
- Keep the default theme plain, fast and accessible. Offer two or three colour schemes, not a theme marketplace.
Milestones by month
- Month 1: config format, GitHub data fetching with caching, project pages.
- Month 2: Markdown blog, RSS, SEO metadata, sitemap and JSON-LD.
- Month 3: Open Graph image generation, scheduled rebuilds, documentation for forking and setup.
- Month 4: a trial with at least ten students, fixes, performance and accessibility audit, report and demo.
How it will be assessed
- Time for a new user to go from fork to live site, measured with at least ten students who have not seen the project.
- Lighthouse scores for performance, accessibility and SEO on the default theme, with the results explained.
- Structured data that passes validation, and shared links that show the correct preview on LinkedIn and WhatsApp.
- The quality of the setup documentation, judged by how many trial users needed help.
Pitfalls
- Showing vanity metrics such as streaks and contribution counts. They reward activity, not quality.
- Calling the GitHub API from the browser on every visit, which exposes rate limits and slows the page.
- Building a drag and drop site builder. The config file and Markdown are the product.
- Adding SEO features without checking them. Test every preview and every sitemap entry.
Ideas and guidance, not finished projects
These are project ideas and scoping guidance, published free for students to use as a starting point. I do not build, write, or sell final-year projects, and I do not complete coursework for anyone. Take an idea, make it yours, and build it.
Not sure this one fits you?
I help students pick an idea that matches their skills and their deadline, then scope it down until it is finishable. Guidance only, never done for you.
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
Follow along
New writing, resources and project ideas land here first.