Skip to content

README.md

Latest commit

 

History

History
283 lines (209 loc) · 6.18 KB

README.md

File metadata and controls

283 lines (209 loc) · 6.18 KB
Raw

codebar Blog

A Hugo-based blog for codebar, migrated from Jekyll.

Prerequisites

  • Hugo (v0.146.0 or later)
  • Node.js (v18 or later, for search indexing)
  • lychee (optional, for link checking)
  • Make (optional, for convenience commands)

Installing Hugo

macOS:

brew install hugo

Linux:

# Debian/Ubuntu
sudo apt-get install hugo

# Or download from GitHub releases
# https://github.com/gohugoio/hugo/releases

Verify installation:

hugo version

Installing Node.js

Required for search indexing with Pagefind:

macOS:

brew install node

Other platforms: Download from nodejs.org or use your package manager.

Verify installation:

node --version
npm --version

Then install dependencies:

npm install

Installing lychee (optional)

For link checking:

macOS:

brew install lychee

Other platforms:

# Download from GitHub releases
curl -sSfL https://github.com/lycheeverse/lychee/releases/latest/download/lychee-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv lychee /usr/local/bin/

Getting Started

  1. Clone the repository:

    git clone <repository-url>
cd hugo-blog

  2. Install dependencies:

    npm install

  3. Start the development server:

    hugo server --bind 0.0.0.0 --buildDrafts

    Or using Make:

    make serve

  4. Build search index (required for search to work):

    make index

  5. Open in browser: Visit http://localhost:1313

Available Commands

Using Make

make help           # Show all available targets
make build          # Build the site and index for search
make index          # Index built site with Pagefind (for search)
make serve          # Run development server
make check-links    # Check for broken links
make clean          # Remove build artifacts

Note: Search functionality requires the site to be indexed. Run make index after building, or use make build which includes indexing automatically.

Using Hugo directly

# Development server with live reload
hugo server --bind 0.0.0.0 --buildDrafts

# Build for production (without search indexing)
hugo --gc --minify

# Index for search (run after building)
npx pagefind --site public

# Build to specific directory
hugo --destination ./public

Link Checking

We use lychee to check for broken links.

Configuration: .lychee.toml

Run locally:

# Using Make
make check-links

# Or directly with lychee
lychee --config .lychee.toml --root-dir . 'content/**/*.md'

Note: Some external links may fail due to rate limiting or temporary issues. The CI runs link checks daily and creates an issue if persistent problems are found.

Project Structure

hugo-blog/
├── archetypes/           # Content templates
├── content/              # Blog posts
│   └── posts/           # Individual posts
├── static/              # Static assets
│   ├── images/         # Images
│   └── _redirects      # Cloudflare Pages redirects
├── themes/              # Hugo themes
│   └── codebar-fresh/  # Our custom theme
├── .lychee.toml        # Link checker config
├── hugo.toml           # Site configuration
├── Makefile            # Convenience commands
├── package.json        # Node dependencies (Pagefind)
└── README.md           # This file

Content Management

Creating a new post

hugo new content posts/my-new-post.md

Or manually create a file in content/posts/ with frontmatter:

---
title: "My New Post"
date: 2024-01-15T10:00:00Z
author: "Your Name"
tags: ["tag1", "tag2"]
---

Your content here...

Images

Place images in static/images/ and reference them with root-relative paths:

![Alt text](/images/my-image.jpg)

Search

The blog includes full-text search powered by Pagefind.

  • Click the search icon (🔍) in the header or press Tab to focus it
  • Type your query - results appear instantly
  • Click a result to navigate, or press Escape to close

For developers: Search requires the site to be indexed. This happens automatically when you run make build, or manually with make index.

Deployment

This site is deployed to Cloudflare Pages.

Build Settings

  • Build command: make build (or hugo --gc --minify && npx pagefind --site public)
  • Build output directory: /public
  • Environment variable: HUGO_VERSION=0.146.0

Note: For search to work in production, the build command must include Pagefind indexing.

Redirects

Redirects are configured in static/_redirects for old Jekyll URLs. See Cloudflare Pages Redirects documentation.

Migration Notes

  • Originally Jekyll (Octopress)
  • Migrated to Hugo with custom codebar-fresh theme
  • 70+ posts imported from Medium
  • Full-text search added via Pagefind
  • Feed redirected from /atom.xml to Hugo's /index.xml

Troubleshooting

Hugo not found

Make sure Hugo is installed and in your PATH:

which hugo
hugo version

Build errors

Clean and rebuild:

make clean
make build

Link checker not working

Ensure lychee is installed:

which lychee
lychee --version

Contributing

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR-USERNAME/codebar-hugo-blog.git
cd codebar-hugo-blog
  3. Create a new branch for your changes: 
    git checkout -b my-feature-branch
  4. Make your changes and test locally:
    • Run make check-links before committing
    • Test with make serve
  5. Commit and push to your fork: 
    git add .
git commit -m "description of changes"
git push origin my-feature-branch
  6. Submit a pull request from your fork to the main repository

License

This project is licensed under the MIT License.