Skip to main content

Documentation Index

Fetch the complete documentation index at: https://github-52.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Setting up a static portfolio site on GitHub Pages involves several moving parts — file paths, branch configuration, DNS records, third-party scripts — and small misconfigurations in any of them can produce confusing symptoms. This page covers the most common issues you may encounter when setting up or running the portfolio site, along with step-by-step fixes for each.
Symptom: Images render correctly on your local machine but appear broken (missing icon or empty space) when the site is published on GitHub Pages.Cause: Relative image paths like ./images/chart.png or images/chart.png are resolved relative to the current URL path. On GitHub Pages, the URL structure may include a subdirectory (e.g., https://sumit-sc.github.io/project/) that causes relative paths to resolve incorrectly.Fix: Use paths that start from the root of the site. Replace relative paths with root-relative paths:
<!-- Broken: relative path -->
<img src="images/chart.png" alt="Chart">

<!-- Fixed: root-relative path -->
<img src="/images/chart.png" alt="Chart">
If your site is deployed to a subdirectory (e.g., https://username.github.io/repo-name/), you need to include the repository base path. For a Jekyll site, add baseurl to _config.yml and prefix all asset references:
# _config.yml
baseurl: "/Sumit-SC.github.io"

<img src="{{ site.baseurl }}/images/chart.png" alt="Chart">
For a plain HTML site without Jekyll, use absolute paths that include the full base URL, or restructure your project so the site deploys from the root path where baseurl is empty.
Symptom: You push a commit to the feature/cf-admin-editor-foundation branch but the live site still shows the previous version of the page.Cause: GitHub Pages takes one to three minutes to rebuild and redeploy the site after each push. Additionally, your browser or Cloudflare’s CDN cache may be serving a previously cached version of the page.Fix:
  1. Wait for the build to complete — Navigate to the Actions tab of your repository on GitHub. Look for a workflow run triggered by your recent push. If it shows a yellow spinner, the build is still in progress. Wait for it to show a green checkmark before checking the live site.
  2. Hard refresh your browser — Once the build is complete, force your browser to bypass its local cache:
    • Windows/Linux: Ctrl + Shift + R
    • macOS: Cmd + Shift + R
  3. Purge Cloudflare cache — If you are using Cloudflare as a proxy, Cloudflare may be serving a cached version even after GitHub Pages has updated. In your Cloudflare dashboard, go to Caching → Configuration and click Purge Everything, or use Custom Purge to purge only the URLs that changed.
  4. Check for build errors — If the Actions workflow shows a red X, your build failed and GitHub Pages is still serving the last successful deployment. Click the failed workflow run to read the error log and fix the underlying issue.
Symptom: The Giscus comment widget does not appear on the page, shows a loading spinner indefinitely, or displays an error message.Cause: Giscus fails to load when repository configuration is incorrect, the repository is private, Discussions is not enabled, or the data-repo-id and data-category-id values in the script tag are wrong.Fix:
  1. Verify the repository is public — Go to Settings → Danger Zone in your repository and confirm the visibility is set to Public. Giscus cannot access Discussions on private repositories.
  2. Confirm Discussions is enabled — Go to Settings → Features and check that the Discussions checkbox is ticked. If the Discussions tab is missing from your repository navigation, it is not enabled.
  3. Regenerate the script snippet — Visit https://giscus.app, re-enter your repository name, and re-copy the generated snippet. The data-repo-id and data-category-id values are repository-specific GraphQL node IDs that must match exactly. Do not type them manually.
  4. Check the browser console for errors — Open your browser’s developer tools (F12), go to the Console tab, and reload the page. Giscus logs descriptive error messages (e.g., Error: Discussion not found) that identify the specific misconfiguration.
  5. Check that the Discussion category exists — If you specified data-category="Comments" but the Comments category has not been created in your repository’s Discussions tab, Giscus will fail to create threads. Create the category first, then regenerate the snippet.
Symptom: After configuring a custom domain, visiting the domain in a browser returns a 404 error or a Cloudflare error page.Cause: Custom domain 404 errors are usually caused by DNS records that have not propagated yet, a missing CNAME file in the repository, or incorrect Cloudflare proxy settings.Fix:
  1. Check the CNAME file — Confirm that a file named CNAME (no extension) exists in the root of your feature/cf-admin-editor-foundation branch, containing exactly one line: your custom domain (e.g., sumitsc.dev). No https:// prefix, no trailing slash. 
    sumitsc.dev
  2. Verify the DNS record in Cloudflare — In your Cloudflare DNS dashboard, confirm a CNAME record points your domain (or www subdomain) to sumit-sc.github.io. The record should have proxy status set to Proxied (orange cloud) for CDN benefits, or DNS only (grey cloud) if you prefer to let GitHub handle HTTPS directly.
  3. Wait for DNS propagation — DNS changes can take anywhere from a few minutes to 48 hours to propagate globally. You can check propagation status using a tool like https://dnschecker.org.
  4. Confirm the custom domain in GitHub Pages settings — In Settings → Pages, the custom domain field should contain your domain exactly. If it is blank or shows a different value, re-enter it and save. GitHub will attempt to provision an SSL certificate via Let’s Encrypt automatically once DNS is resolving correctly.
  5. Check for HTTPS enforcement — If GitHub Pages cannot provision a certificate (usually because DNS is not yet propagating), the Enforce HTTPS checkbox will be greyed out. Wait for DNS propagation to complete, then enable it.
Symptom: The portfolio looks correct on a desktop browser but elements overlap, text overflows, or the layout collapses in an unexpected way on mobile devices.Cause: Missing or incorrect viewport meta tag, CSS that does not account for small screen widths, or content with fixed pixel widths that exceed the mobile viewport.Fix:
  1. Add the viewport meta tag — Check that the <head> section of your HTML template includes the following meta tag. Without it, mobile browsers render the page at a desktop width and then scale it down, making text and buttons too small to use: 
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
  2. Check CSS media queries — If you have custom styles, ensure they include breakpoints for small screens. A minimal starting point: 
    /* Base styles (mobile first) */
.container {
  width: 100%;
  padding: 0 1rem;
}

/* Tablet and above */
@media (min-width: 768px) {
  .container {
    max-width: 960px;
    margin: 0 auto;
  }
}
  3. Identify the problem element with browser dev tools — Open Chrome or Firefox developer tools, click the device toolbar icon (or press Ctrl+Shift+M), and select a mobile device viewport. Use the element inspector to identify which element is causing the overflow or layout break. Look for elements with width values in fixed pixels, overflow: visible, or white-space: nowrap that prevent line wrapping on narrow screens.
  4. Test across multiple viewport sizes — Rather than testing only on your own phone, use the browser dev tools device emulator to test at common breakpoints: 320px (small phones), 375px (iPhone), 414px (large phones), 768px (tablets).

​
Still stuck?

If none of the solutions above resolve your issue, check the following resources:

Deployment guide

Review the full deployment setup including branch and GitHub Pages configuration.

Comments setup

Revisit the Giscus configuration steps from the beginning.