Editing the Hugo Blox SSG Template Locally

Editing the Hugo Blox Static Site Generator (SSG) template locally provides a powerful and flexible way to customize your website. By installing the necessary dependencies and using Visual Studio Code (VS Code), you can take advantage of advanced features and extensions that enhance your workflow. This section will guide you through the process of setting up your local environment and utilizing VS Code to edit the Hugo Blox template effectively.

Setting Up Your Local Environment

Install Hugo

First, you need to install Hugo on your local machine. Follow the instructions in the Hugo Blox Docs to download and install the correct version of Hugo for your operating system.

Install Git

Ensure that Git is installed on your system. You can download it from the official Git website and follow the installation instructions.

Clone Your Repository

Clone your Hugo Blox site repository from GitHub to your local machine using the following command:

git clone https://github.com/yourusername/your-hugo-blox-site.git

Replace yourusername and your-hugo-blox-site with your actual GitHub username and repository name.

Installing Dependencies

For managing dependencies, you might need to use package managers like Chocolatey (for Windows) or Homebrew (for macOS). If you need to install specific versions of packages, refer to the guides on Chocolatey and Homebrew.

Editing with Visual Studio Code

Visual Studio Code (VS Code) is a powerful text editor with numerous extensions that enhance Markdown and YAML editing. Here’s how to set up and use VS Code for editing your Hugo Blox site:

Install VS Code

Download and install VS Code from the official website.

Install Helpful Extensions

Enhance your editing experience by installing the following VS Code extensions:

  • Citation Picker for Zotero: Allows you to search and insert citations from your Zotero library directly into Markdown files (Citation Picker for Zotero).
  • GitHub Actions: Provides syntax highlighting and IntelliSense for GitHub Actions workflows (GitHub Actions).
  • GitHub Codespaces: Enables you to create and manage Codespaces directly from VS Code (GitHub Codespaces).
  • GitHub Pull Requests and Issues: Allows you to review and manage GitHub pull requests and issues directly in VS Code (GitHub Pull Requests and Issues).
  • GitLens: Provides advanced Git capabilities within VS Code (GitLens).
  • Gitmoji: Adds Gitmoji support to VS Code for better commit messages (Gitmoji).
  • Go: Supports Go development with IntelliSense, debugging, and more (Go).
  • Hugo Language and Syntax Support: Adds syntax highlighting and snippets for Hugo templates (Hugo Language and Syntax Support).
  • Hugo Runner: Provides commands to run Hugo tasks directly from VS Code (Hugo Runner).
  • Hugo Snippets: Offers snippets for Hugo templates in VS Code (Hugo Snippets).
  • Hugo Tags Helper: Helps manage Hugo tags and categories in your content files (Hugo Tags Helper).
  • Hugofy: Adds support for Hugo commands and tasks in VS Code (Hugofy).
  • LaTeX Snippets: Provides LaTeX snippets for VS Code (LaTeX Snippets).
  • LaTeX Workshop: Offers LaTeX language support and preview features in VS Code (LaTeX Workshop).
  • Live Share: Enables real-time collaboration and editing in VS Code (Live Share).
  • Markdown All in One: Provides comprehensive support for Markdown editing (Markdown All in One).
  • markdownlint: Offers syntax highlighting and validation for YAML files (markdownlint).
  • Todo-Tree: Helps manage and visualize your to-do items within the code (Todo-Tree GitHub).
  • Zotenote: Allows you to search and insert Zotero notes into Markdown files (Zotenote).

Open Your Project

Open your cloned Hugo Blox site repository in VS Code by navigating to File > Open Folder and selecting the repository folder.

Editing Markdown and YAML

Utilize VS Code’s features to edit Markdown and YAML files effectively. For detailed guides, refer to Markdown Guide and Learn YAML in Y Minutes.

Deploying and Testing Locally

Run Hugo Server

Start the Hugo server to preview your changes locally. Run the following command in your project directory:

hugo server -D

This will start a local server, and you can view your site, including any draft pages, by navigating to http://localhost:1313 in your web browser.

Debugging and Troubleshooting

If you encounter any issues, refer to the Hugo Blox troubleshooting documentation for solutions.

Leveraging GitHub Codespaces

For a cloud-based development environment, consider using GitHub Codespaces. It provides a complete development environment within GitHub, allowing you to contribute immediately without setting up a local environment. GitHub Codespaces can be particularly useful for collaborative projects and when working from different machines.

Create the Dev Container Configuration

  • Create the .devcontainer Directory:
    In your Hugo project’s root directory, create a folder named .devcontainer. Run this command in your terminal:

    mkdir .devcontainer

  • Add devcontainer.json:
    Inside .devcontainer, create a file named devcontainer.json and add the following content (customize as needed):

    {
"name": "Hugo Development Environment",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
  "ghcr.io/devcontainers/features/go:1": {
    "version": "latest"
  },
  "ghcr.io/devcontainers/features/hugo:1": {
    "version": "latest",
    "extended": true
  }
},
"customizations": {
  "vscode": {
    "extensions": [
      "golang.go",
      "eliostruyf.vscode-front-matter"
    ]
  }
},
"forwardPorts": [1313],
"postCreateCommand": "hugo version && go version"
}

  • Notes:

    • Use specific versions (e.g., "version": "0.121.0" for Hugo) if you need to match your local setup.
    • Add more extensions under customizations.vscode.extensions if you use others locally (e.g., Markdown linting tools).

  • Commit the Configuration:
    Add and commit the .devcontainer folder to your repository with these commands:

    git add .devcontainer
git commit -m "Add Codespaces dev container for Hugo and Go"
git push origin main

Launch GitHub Codespaces

  • Open Your Repository on GitHub:
    Navigate to your repository on GitHub (e.g., https://github.com/your-username/your-repo).

  • Create a Codespace:
    Click the green “Code” button, then select the “Codespaces” tab. Click “Create codespace on main” (or your branch). GitHub will build the container based on devcontainer.json. This may take a few minutes the first time as it installs Hugo and Go.

  • Access the Environment:
    Once the Codespace loads, you’ll be in a VS Code-like interface in your browser, with your repo’s files loaded.

Verify the Setup

  • Check Hugo and Go:
    Open the terminal in Codespaces (Ctrl+` or Terminal > New Terminal in the menu). Run these commands:

    hugo version
go version

    • You should see output confirming the installed versions (e.g., hugo v0.121.0 and go1.21.0).

    • Fix Issues (if any):
      If either command fails, revisit devcontainer.json to ensure the features section is correct, then rebuild the Codespace (see Step 6).

Run the Hugo Server

  • Start the Server:
    In the terminal, run:

    hugo server -D
    • The -D flag includes drafts, which is handy for development.

  • Handle the Base URL (Optional but Recommended):
    To ensure links and assets work correctly in Codespaces, use this command instead:

    hugo server -D --baseURL="https://$CODESPACE_NAME-1313.$GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN" --appendPort=false
    • This dynamically sets the baseURL to match Codespaces’ forwarded URL.

Preview Your Site

  • Access the Forwarded Port:
    After starting the server, Codespaces will detect port 1313 (from forwardPorts) and show a toast notification like “Port 1313 is available.” Click “Open in Browser”. Alternatively, go to the “Ports” tab in the VS Code interface, find port 1313, and right-click to copy the public URL (e.g., https://<codespace-name>-1313.app.github.dev).

  • View the Site:
    Paste the URL in your browser. You should see your Hugo site running, with live updates as you edit files.

  • Test Changes:
    Edit a file (e.g., a Markdown post in content/) and save it. Refresh the browser to confirm the Hugo server reflects the change.

Save and Sync Changes

  • Commit Changes in Codespaces:
    Use the Source Control panel in Codespaces’ VS Code interface (or the terminal) to commit edits:

    git add .
git commit -m "Update site content from Codespaces"
git push origin main

  • Pull Locally (if needed):
    Back on your local machine, pull the changes:

    git pull origin main

(Optional) Fine-Tune the Setup

  • Adjust Resources:
    If the Codespace feels slow, go to GitHub > Codespaces settings and upgrade to a larger machine (e.g., 4-core/16GB RAM).

  • Rebuild if Config Changes:
    If you tweak devcontainer.json later, rebuild the Codespace:

  • In Codespaces, press Ctrl+Shift+P (or Cmd+Shift+P on Mac), type “Rebuild Container,” and select it.

  • Custom Scripts:
    Add a postCreateCommand in devcontainer.json for extra setup (e.g., npm install if your theme uses Node.js).

Quick Recap

  1. Add .devcontainer/devcontainer.json with Hugo and Go setup.
  2. Launch a Codespace from your repo on GitHub.
  3. Verify Hugo and Go are installed.
  4. Run hugo server -D with the dynamic baseURL.
  5. Preview the site via the forwarded port.
  6. Commit and push changes from Codespaces.

Final Notes

This setup mirrors a local Hugo development workflow in the cloud, with the configuration stored in version control for consistency. If you encounter issues (e.g., port forwarding failures or Hugo build errors), adjust the configuration and rebuild as needed. By leveraging GitHub Codespaces, you can seamlessly edit and preview your Hugo Blox site from any machine with an internet connection, streamlining your development process and enabling collaboration with team members or contributors.