Portfolio Website: Deployment & Blog System Guide

This guide covers two things you'll need once your portfolio is running locally: getting it live on the internet, and understanding how the automated blog system works so you can publish new posts confidently for years to come.

Repository: github.com/bayzed123/sayadbayezid-portfolio-

Prerequisite: This guide assumes you've already completed the Getting Started guide — your project should be personalized via setup.sh and tested locally before deploying.

In this guide

Part 1 — Deployment

• Deployment options overview
• Option A: GitHub Pages
• Option B: Netlify
• Option C: Vercel
• Connecting a custom domain
• Post-deployment checklist

Part 2 — Blog System

• How the blog pipeline works
• Writing posts in Markdown
• Writing posts in HTML (advanced)
• Adding a Table of Contents
• Adding FAQ accordions
• Publishing workflow, step by step
• Blog system troubleshooting

Reference

• Frequently asked questions
• Next steps

Part 1 — Deployment

Deployment options overview

Since this portfolio is a fully static site (plain HTML/CSS/JS with no backend), you have several free hosting options. Here's how they compare:

Tip
All three options are free for personal portfolio use and require zero server management. If you're unsure which to pick, start with GitHub Pages — it requires the fewest steps since your code already lives on GitHub.

Option A: GitHub Pages (Recommended)

Step 1 — Push your personalized code

Make sure your local changes (from running setup.sh) are committed and pushed to your fork:

git add .
git commit -m "chore: personalize portfolio with my info"
git push origin main

Step 2 — Enable GitHub Pages

1. Go to your repository on GitHub
2. Click Settings (top navigation bar)
3. In the left sidebar, click Pages
4. Under Build and deployment → Source, select Deploy from a branch
5. Under Branch, select main and folder / (root)
6. Click Save

Step 3 — Wait for deployment

GitHub will show a banner:

Your site is live at https://YOUR_USERNAME.github.io/sayadbayezid-portfolio-/

Note
The first deployment can take 1–3 minutes. If you see a 404 immediately after enabling Pages, wait a minute and refresh — this is normal.

Step 4 — Verify

Visit the URL shown in the banner. You should see your personalized homepage — not the placeholder content.

Warning
If your homepage loads but CSS/images look broken, this is almost always a relative path issue. Check that your <link> and <img> tags use relative paths (assets/css/style.css) rather than absolute root paths (/assets/css/style.css) — GitHub Pages serves your site from a subfolder (/sayadbayezid-portfolio-/), not the domain root, unless you're using a custom domain.

Option B: Netlify

Netlify offers more deployment flexibility and built-in form handling if you plan to expand your contact form later.

Step 1 — Sign up / log in

Go to netlify.com and sign in with your GitHub account.

Step 2 — Create a new site

1. Click Add new site → Import an existing project
2. Choose GitHub as your Git provider
3. Authorize Netlify to access your repositories (if prompted)
4. Select your sayadbayezid-portfolio- fork from the list

Step 3 — Configure build settings

Since this is a static site with no build step required for the homepage:

Build command:      (leave empty)
Publish directory:  .

Click Deploy site.

Step 4 — Wait for deployment

Netlify assigns a random subdomain immediately, e.g.:

https://cheerful-einstein-a1b2c3.netlify.app

You can rename this under Site settings → Change site name.

Tip
Netlify auto-detects future pushes to your main branch and redeploys automatically — no extra configuration needed for continuous deployment.

Option C: Vercel

Vercel is another excellent free option, particularly known for very fast global CDN performance.

Step 1 — Sign up / log in

Go to vercel.com and sign in with GitHub.

Step 2 — Import your repository

1. Click Add New → Project
2. Select your sayadbayezid-portfolio- fork
3. Click Import

Step 3 — Configure project

Since there's no framework/build step:

Framework Preset:   Other
Build Command:      (leave empty)
Output Directory:   .

Click Deploy.

Step 4 — Access your live site

Vercel provides a URL immediately:

https://sayadbayezid-portfolio-yourusername.vercel.app

Connecting a custom domain

If you own a domain (e.g., from Namecheap, Google Domains, or GoDaddy), here's how to connect it — the process is similar across all three platforms.

For GitHub Pages

1. In your repo root, edit the CNAME file (or create one if missing):

   yourdomain.com
   

2. At your domain registrar, add these DNS records:

   Type	Name	Value
   A	@	185.199.108.153
   A	@	185.199.109.153
   A	@	185.199.110.153
   A	@	185.199.111.153
   CNAME	www	YOUR_USERNAME.github.io

3. Back in Settings → Pages, enter your custom domain and click Save

4. Check Enforce HTTPS once the certificate is issued (can take up to 24 hours)

For Netlify / Vercel

Both platforms provide domain-specific DNS instructions automatically:

• Netlify: Site settings → Domain management → Add custom domain
• Vercel: Project → Settings → Domains → Add

Follow the exact DNS records they display — these platforms often support a simpler ALIAS/ANAME record instead of multiple A records.

Warning
DNS changes can take anywhere from a few minutes to 24-48 hours to fully propagate. Don't panic if your custom domain doesn't work immediately — use whatsmydns.net to check propagation status globally.

Post-deployment checklist

Before considering your deployment complete, verify:

• Homepage loads correctly at your live URL
• All navigation links work (no 404s)
• Images and CSS load correctly (check browser DevTools → Network tab for any red/failed requests)
• Blog page loads and displays at least your test post
• Contact form/links point to your actual email, not placeholder
• Custom domain (if used) resolves correctly and shows a valid HTTPS certificate
• Site is mobile-responsive (test on your phone or DevTools' device emulator)

Part 2 — Blog System

Now that your site is live, let's cover how to actually publish content going forward — this is the part that matters most for building the kind of high-value, consistently-updated content that search engines (and AdSense reviewers) reward.

How the blog pipeline works

Unlike traditional blogging platforms, there's no dashboard to log into. Publishing works entirely through Git:

The six-step flow

1. You write a .md or .html file locally
2. You place it in the blog_uploads/ folder
3. You push to GitHub (git push)
4. GitHub Actions triggers automatically — no manual step required
5. scripts/convert_blogs.py runs on GitHub's servers, converting your file into structured JSON
6. The JSON lands in blogs/, and blog-loader.html fetches + renders it live

Note
This entire pipeline runs on GitHub's infrastructure, not your local machine. Once you push, you can close your laptop — the post will still go live within a minute or two.

Writing posts in Markdown

Markdown is the simplest way to publish. Create a new file inside blog_uploads/:

touch blog_uploads/my-first-real-post.md

Use this structure:

# My First Real Post

This is the introduction paragraph. It's automatically used as the excerpt
shown in the blog listing page, so make it count.

## Why This Topic Matters

Explain the core idea here. Use as many paragraphs as needed.

### A Specific Detail

Sub-sections work too, and are automatically included in the Table of Contents.

## Code Examples Work Great

\`\`\`javascript
function example() {
  console.log("Markdown code blocks render with syntax highlighting");
}
\`\`\`

## Conclusion

Wrap up your post here.

Markdown formatting reference

Tip
The first # Heading in your file becomes the post title automatically — it's extracted and removed from the body, then displayed separately by the template. Don't include a title anywhere else in the file.

Writing posts in HTML (advanced)

For more visual control — custom layouts, embedded widgets, interactive elements — you can write posts directly in HTML instead of Markdown. Save the file with a .html extension in the same blog_uploads/ folder.

<h1>My Advanced Post Title</h1>
<meta name="description" content="A short summary for SEO purposes">

<p>Your intro paragraph goes here.</p>

<h2>A Major Section</h2>
<p>Content for this section.</p>

<img src="https://yourdomain.com/assets/images/blog/example.png" alt="Descriptive alt text">

<h2>Another Section</h2>
<p>More content.</p>

Warning
Always use absolute image URLs (https://yourdomain.com/...) in blog posts, not relative paths (../assets/image.png). Since blog posts can be viewed from different URL depths, relative paths frequently break.

Adding a Table of Contents

Every ## (H2) and ### (H3) heading in your post is automatically collected into a Table of Contents — no manual work needed for Markdown posts.

For HTML posts, wrap your intended TOC section like this so it matches the expected structure:

<section class="toc">
  <h3>Table of Contents</h3>
  <ul>
    <li><a href="#section-1">Section 1</a></li>
    <li><a href="#section-2">Section 2</a></li>
  </ul>
</section>

<section id="section-1">
  <h2>Section 1</h2>
  <p>Content...</p>
</section>

<section id="section-2">
  <h2>Section 2</h2>
  <p>Content...</p>
</section>

Note
For Markdown posts, you don't need to write this manually at all — the conversion script auto-generates matching id attributes on every heading and builds the TOC data structure for you.

Adding FAQ accordions

Interactive collapsible FAQ sections (like the ones in this very guide) are supported out of the box in HTML posts:

<div class="faq-section">
  <button class="accordion">Q: What is this project?</button>
  <div class="panel">
    <p>A: It's an open-source developer portfolio template with automated blogging.</p>
  </div>

  <button class="accordion">Q: Is it free to use?</button>
  <div class="panel">
    <p>A: Yes, it's free under an attribution-required open-source license.</p>
  </div>
</div>

The accompanying JavaScript (already included in assets/js/) handles the expand/collapse behavior automatically — you don't need to write any JS yourself.

Publishing workflow, step by step

Here's the exact sequence you'll repeat every time you publish a new post:

# 1. Create your post file
touch blog_uploads/how-i-built-my-portfolio.md

# 2. Write your content (using any text editor)
code blog_uploads/how-i-built-my-portfolio.md

# 3. Stage and commit
git add blog_uploads/how-i-built-my-portfolio.md
git commit -m "blog: add post about building my portfolio"

# 4. Push — this triggers the automation
git push origin main

Confirming it worked

1. Go to your repository on GitHub
2. Click the Actions tab
3. You should see a workflow run named "Blog Automation" in progress or completed with a green checkmark ✅

✅ Blog Automation
   Triggered by: push
   Duration: ~15s
   Status: Success

4. Once it shows success, visit your live blog page — the new post should appear within a minute.

Tip
Bookmark the Actions tab of your repo. It's your single source of truth for whether a post published correctly — far more reliable than just guessing based on the live site.

Blog system troubleshooting

Post doesn't appear after pushing

Check the Actions tab first. If the workflow shows a red ❌, click into it to see the exact error log. Common causes:

Post appears, but formatting looks broken

• Missing headings in TOC → Confirm you used ## (not **bold text**) for section headings
• Code blocks not highlighted → Confirm you used triple backticks with a language tag (```javascript, not just ```)
• Images not loading → Confirm you used absolute URLs, not relative paths

Duplicate posts appearing

This happens if you rename a post file without deleting the old generated JSON. Manually remove the stale file:

rm blogs/old-post-slug.json
git add blogs/
git commit -m "fix: remove stale blog JSON"
git push

Workflow runs but doesn't commit changes

This is actually expected behavior if your content didn't change the generated output — the workflow is designed to skip empty commits. If you expected a change and don't see one, check that you actually edited/added a file inside blog_uploads/ and not somewhere else.

Frequently asked questions

rm blog_uploads/old-post.md
rm blogs/old-post.json
git add -A
git commit -m "blog: remove old post"
git push

Next steps

• Getting Started Guide — if you haven't completed initial setup yet
• Customization Guide — editing colors, layout sections, and adding new pages
• Start writing your first real post and push it live using the workflow above

Further reading

• WIKI.md — full technical reference for the blog system internals
• GitHub Actions documentation — official docs for understanding workflow YAML syntax further
• Repository Issues — report bugs or request features

Help and support

Did you find what you needed?
Thank you! We received your feedback.


Privacy policy

Help us make these docs great!
All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.


⑂ Make a contribution


Learn how to contribute

Still need help?
👥 Ask the SmartGen community
💬 Contact support

Legal
© 2026 SmartGen.   Terms   Privacy   Expert services   Blog