↓Skip to main content

Creating My Personal Website

Table of Contents

‘homepage screenshot’

Overview
#

This project details the creation of my personal website, designed to serve as a central hub for showcasing my technical accomplishments, sharing valuable insights gained from my projects, and fostering a community for learning and growth within the IT field. Built using Hugo, a static site generator, and hosted on GitHub Pages, the site prioritizes a professional aesthetic, ease of content creation, and cost-effectiveness.

The Challenge/Motivation
#

Why I Took This On: Fostering Growth and Sharing Knowledge
#

I embarked on this project to establish a dedicated online space where I could not only highlight my technical skills and completed projects but also contribute to the broader IT community. My core motivation stems from the belief that hoarding information hinders collective progress. By openly sharing my experiences, including the inevitable mistakes and the troubleshooting steps I undertook, I aim to provide a practical resource for others navigating similar challenges. This website is a testament to the value of being a contributing team member, pushing everyone forward, including myself, through shared knowledge and lessons learned.

Solution/Approach
#

Building a Cost-Effective, Content-Centric Platform
#

My approach involved leveraging a static site generator to prioritize fast loading times, and minimal hosting costs. I focused on a content-first strategy, choosing tools that would make writing and publishing new articles straightforward using Markdown. The development process involved setting up the local Hugo environment, selecting and customizing a theme, developing content, and configuring continuous deployment via GitHub Pages.

Technologies Used
#

What I Used and Why I Chose Them
#

  • Hugo:

    • Description: An open-source static site generator written in Go, known for its incredible speed and flexibility. It processes content (often in Markdown) and templates to generate static HTML, CSS, and JavaScript files.
    • Why I Chose It: With a lengthy list of project goals already in mind, I wasn’t keen on dedicating significant time to learning HTML/CSS from scratch for a personal website. Hugo allowed me to focus on content creation using Markdown, which was appealing due to its simplicity and the ability to learn new tricks with it. While options like Wix or Squarespace exist, I wanted to avoid recurring fees and have more control over the underlying structure.

  • Blowfish Theme:

    • Description: A feature-rich and highly customizable Hugo theme designed for blogs and personal websites, offering a modern and clean aesthetic.
    • Why I Chose It: After reviewing numerous Hugo themes, Blowfish stood out for its professional, visually appealing design and robust feature set. Its responsiveness and clean layout aligned perfectly with my goal for a polished online presence. Quite simply, I thought it was the coolest looking theme for Hugo.

  • Visual Studio Code (VSCode):

    • Description: A lightweight yet powerful source code editor developed by Microsoft, offering extensive support for various programming languages, debugging, and extensions.
    • Why I Chose It: VSCode is incredibly versatile, capable of editing multiple languages and providing syntax highlighting, which makes reading and writing code (including Markdown for Hugo) significantly easier. Its vast ecosystem of extensions further enhances productivity.

  • GitHub:

    • Description: A web-based platform for version control and collaborative software development, utilizing Git. It allows for hosting repositories, managing code changes, and tracking contributions.
    • Why I Chose It: GitHub is widely recognized as the industry standard for web-based code storage and version control. Utilizing it for this project allowed me to gain a practical understanding of Git workflows, which is invaluable for future projects and professional career development.

  • GitHub Pages:

    • Description: A free static site hosting service offered by GitHub, designed to publish websites directly from a GitHub repository.
    • Why I Chose It: The primary advantage was that it’s completely free, aligning with my goal to minimize costs. It’s also designed to seamlessly integrate with GitHub, simplifying the deployment process. GitHub Pages serves as an excellent placeholder and learning platform while I explore potentially deploying my site with cloud providers like AWS in the future to deepen my cloud skills.

  • Namecheap:

    • Description: An ICANN-accredited domain registrar and web hosting company, providing domain name registration and related services.
    • Why I Chose It: Through research, Namecheap appeared to be a reputable, cost-effective, and user-friendly domain registrar. I appreciated their straightforward approach without being overly pushy with upselling additional products.

Key Features/Components
#

What the Website Offers
#

  • Accomplishments Showcase: Dedicated sections to highlight completed IT projects, skills, and certifications.
  • Knowledge Base/Blog: A dynamic blog section where I can publish articles detailing project journeys, including challenges encountered and troubleshooting steps.
  • Interactive Content: Utilizing Markdown’s capabilities for code blocks, lists, and headings to make technical content easily digestible.
  • Responsive Design: Ensures the website is accessible and visually appealing across various devices (desktops, tablets, mobile).

Technical Deep Dive
#

Implementation, Challenges, and Learning
#

During the setup of Hugo and the Blowfish theme, I encountered a few initial hurdles.

  • Challenge 1: Deciphering Hugo Configuration Files: Understanding the myriad of settings within Hugo’s configuration files (like hugo.toml, languages.en.toml, menus.en.toml, and params.toml) and precisely how each line influenced the website’s appearance and functionality was initially daunting.

    • Troubleshooting: I immersed myself in the Blowfish theme’s dedicated blog and documentation. By systematically reviewing the configuration options and experimenting with changes, I began to build a mental map of their impact on the site’s design and features.
    • Learning: This process significantly improved my grasp of configuration granularity in static site generators, highlighting the importance of detailed documentation for effective customization.

  • Challenge 2: Selective Table of Contents Display: A specific challenge involved controlling the visibility of the Table of Contents (ToC), aiming to display it only on particular pages rather than universally.

    • Troubleshooting: This is an ongoing challenge. I am currently exploring various methods within Hugo’s templating system and front matter configurations to achieve this selective display, investigating whether it can be controlled on a per-page basis or requires more global adjustments.
    • Learning: This ongoing problem is deepening my understanding of Hugo’s rendering pipeline and the interplay between content, layouts, and configuration for fine-grained control over page elements.

  • Challenge 3: Page Layout Customization: Determining the most effective way to customize individual page layouts, whether through existing front matter options, .toml adjustments, or by creating custom layout templates, presented a design and implementation decision point.

    • Troubleshooting: I am actively investigating the capabilities of both front matter and the main configuration file for page-specific styling and structure. Concurrently, I’m assessing the necessity and feasibility of developing custom Hugo layout files to achieve desired unique page designs.
    • Learning: This exploration is providing valuable insights into Hugo’s templating hierarchy and the different avenues available for achieving specific visual and functional layouts, informing best practices for maintaining a flexible and scalable site design.

  • Challenge 4: index.md vs. _index.md Differentiation: Understanding the subtle yet significant distinction between index.md and _index.md files within Hugo’s content organization was a source of confusion.

    • Troubleshooting: I conducted practical experiments by renaming these files and observing the resulting changes in my website’s structure and content rendering. This hands-on approach quickly illuminated the specific roles and implications of each file naming convention.
    • Learning: This direct experience solidified my understanding of Hugo’s content organization principles, particularly how it distinguishes between content pages and section/list pages, which is crucial for building a well-structured site.

  • Challenge 5: Expected Hugo File Structure: Grasping the optimal and expected file structure for a Hugo project to ensure proper rendering and maintainability was a foundational challenge.

    • Troubleshooting: I extensively consulted the official Hugo documentation and blog, cross-referencing best practices for organizing content, static assets, layouts, and data. Through iterative adjustments and observing their effects on my site, I began to converge on an effective and maintainable structure.
    • Learning: This process reinforced the importance of adhering to convention over configuration where possible in static site generators, and provided a clear roadmap for organizing future Hugo projects efficiently.

  • Challenge 6: Domain Name System (DNS) Configuration: My website was initially inaccessible due to incorrect DNS configurations at the domain registrar. Specifically, I had not properly configured the A/AAAA records and CNAME record.

    • Troubleshooting: I researched the purpose and configuration of various DNS record types, including A (IPv4 address), AAAA (IPv6 address), and CNAME (canonical name). This helped me understand how these records direct internet traffic. I then carefully configured the necessary records on Namecheap’s DNS management page, pointing my domain to GitHub Pages’ IP addresses and setting up the CNAME for the custom domain.
    • Learning: This was a significant learning curve in understanding the fundamentals of how internet traffic is routed and the critical role of DNS in web accessibility. It provided me with a foundational understanding of network infrastructure beyond just application development.

  • Challenge 7: GitHub Pages Deployment Issues (Post-DNS): Even after configuring DNS, my website still didn’t appear, indicating issues beyond just domain resolution. This turned out to be a two-part problem directly related to GitHub Pages deployment.

    • Troubleshooting - Part A (Hugo hugo.toml baseURL): The first issue was an incorrect baseURL specified in my Hugo hugo.toml file. It wasn’t set to my custom domain (https://dylan-it.com/), which can cause problems with relative links and how GitHub Pages serves the site. Correcting this was crucial.
    • Troubleshooting - Part B (GitHub Actions YAML Configuration for public/ directory): The second, and more complex, issue involved correctly configuring the GitHub Actions workflow YAML file itself for deployment. The workflow was attempting to run the hugo command and update the main branch of the repository, but the generated static files needed to be specifically placed and recognized by GitHub Pages. The solution was to precisely define the deployment steps within the YAML file to ensure Hugo’s output was correctly generated into the ./public directory, and that GitHub Pages was configured to serve from this public folder on the main branch. This involved ensuring the action ran hugo to build the site and then deployed the contents of the public directory, aligning with GitHub Pages’ expected serving location.
    • Learning: This experience gave me deep insights into both Hugo’s site configuration and the intricacies of GitHub Actions for CI/CD, especially when deploying to GitHub Pages with custom domains. I learned how vital it is to correctly configure the deployment pipeline within the YAML file to match the hosting service’s expected build output location and serving branch.

  • Challenge 8: Unwanted Download Prompt from Theme: My website currently displays an annoying notification or prompt asking visitors to download the webpage.

    • Troubleshooting: I’m currently investigating the source of this prompt. My initial guess is that it’s a default feature of the Blowfish theme, likely related to a Progressive Web App (PWA) configuration. I’m currently sifting through the theme’s configuration options and source code to identify and disable this functionality. This involves looking for specific PWA settings, service worker registrations, or template partials responsible for the notification.
    • Learning: This ongoing challenge is deepening my understanding of theme customization, specifically how to identify and override default behaviors in complex themes. It’s also introducing me to the concepts of PWAs and how they interact with web browsers, which is a valuable area of web development.

Outcomes and Impact
#

A Platform for Growth and Contribution
#

The creation of my personal website has yielded significant positive outcomes:

  • Centralized Portfolio: I now have a professional, centralized location to showcase my IT projects and skills to potential employers and collaborators.
  • Enhanced Learning: The process of building and documenting this site has deepened my understanding of static site generators, version control, and continuous deployment.
  • Community Contribution: I have a dedicated platform to share my knowledge and experiences, fulfilling my goal of contributing to the IT community by documenting challenges and solutions.
  • Cost-Effectiveness: By leveraging open-source tools and free hosting, I’ve maintained a negligible operational cost, making it sustainable for long-term use.

Future Enhancements/ Learning
#

What’s Next for the Website
#

  • Future Plans:
    • Explore deploying the website on AWS
    • Integrate a comments section to foster more direct interaction and feedback from readers.
    • Create more content as I continue my IT journey
  • Recommendations: For anyone looking to build a personal or project website, I highly recommend exploring static site generators like Hugo. The initial learning curve is quickly overcome by the benefits of performance, and ease of content management.

Screenshots/Demonstration/Resources
#

Screenshots
#

you can see from the screenshot above that .toml files are quite expansive and have little description within the file itself. to understand the changes you are making use the configurations page on blowfish’s website. Configurations

take note of how there are several index.md and _index.md files. Hugo expects nested directories with index.md files representing articles and _index.md files representing list pages. reading through the Hugo docs page can be incredibly helpful!

Links#

Hugo’s homepage, you can download hugo, read up on how to use it, and search through themes.

Blowfish was my favorite looking theme, the homepage is where you can test out the page, download the theme, and review how to manipulate the theme to fit your needs.

I watched Ken’s youtube video, and then read his blog post to get started with this project.

  • hugo.yaml file for github pages that google Gemini helped me produce.
name: Deploy Hugo site to GitHub Pages

on:
  push:
    branches:
      - main # Workflow triggers on pushes to main

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages # Important: Link to the GitHub Pages environment
      url: ${{ steps.deployment.outputs.page_url }} # Expose the deployed URL

    permissions:
      contents: read # Only need read access for source files
      pages: write # To deploy to GitHub Pages
      id-token: write # For OpenID Connect (OIDC) authentication with GH Pages

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: 'latest' # Or a specific version

      - name: Build Hugo Site
        # Ensure Hugo builds the site into the 'public' directory
        # The 'public' directory will be picked up by the upload-pages-artifact action
        run: hugo --minify # Use --minify for production builds
        working-directory: .

      - name: Setup Pages
        uses: actions/configure-pages@v5 # Required for GH Pages deployments

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3 # Uploads the 'public' directory
        with:
          path: './public' # Path to your built Hugo site

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4 # Deploys the uploaded artifact

Glossary Entries
#