Jekyll site with Sass styling using npm. Development happens on master, and deployment is done by pushing the built site to gh-pages.
sudo apt update
sudo apt install -y ruby-full build-essential zlib1g-dev
sudo apt install -y nodejs npmsudo pacman -Syu --needed ruby base-devel
sudo pacman -Syu --needed nodejs npmBy default, gem install tries to write to system directories and requires sudo. To keep everything in your home directory, add the following to your shell config (~/.bashrc, ~/.zshrc, etc.):
export GEM_HOME="$HOME/.gem"
export PATH="$GEM_HOME/bin:$PATH"Then reload your shell (exec bash, exec zsh, etc. or open a new terminal) and install Bundler:
gem install bundlerFrom the repository root:
bundle config set --local path "vendor/bundle"
bundle install
npm installThis installs Ruby gems into vendor/bundle/ (project-local) and Node packages into node_modules/. Both are gitignored.
Run all
bundleandnpmcommands from the project directory.
- Compile Sass to CSS:
npm run scssThe scss script in package.json runs sass --verbose --watch assets/scss:assets/css to compile SCSS in assets/scss/ into CSS in assets/css/. It watches for changes and automatically applies them, so you can keep it running while developing. This runs in the foreground, so you need to open a new terminal for Jekyll.
- Run Jekyll:
bundle exec jekyll serve --draftsSite will be available at http://localhost:4000. This command also runs in the foreground. You can stop it with Ctrl+C when done.
If
Gemfileorpackage.jsonchange (e.g., aftergit pull), re-runbundle installand/ornpm installbefore building.
- Config: _config.yml
- Pages: _pages/
- Projects collection: _projects/
- Layouts: _layouts/
- Includes: _includes/
- Sass/SCSS sources: assets/scss/
- Compiled CSS output: assets/css/
To add a new project, create a new Markdown file in the _projects/ directory with the following front matter:
---
layout: posts
title: "Title of project here"
featured: true
status: active
summary: "Short summary here."
tags:
- tag 1
- tag 2
- ...
links: # Optional, you can leave `code` and `paper` empty if not applicable
code: code link
paper:
- paper link 1
- paper link 2
- ...
---Projects will be automatically listed on the "Projects" page, and the featured: true flag will make them appear in the featured section on the homepage. You can also add project-specific content below the front matter, which will be rendered on the individual project page.
Regular pages reside in the _pages/ directory. The current setup supports both Markdown and HTML files to be placed here. Pages use the default layout, which includes the common header, navigation bar, footer, and global styling. Each page must have the appropriate front matter at the top:
---
layout: default
title: "Page Title"
permalink: /page-url/ # Optional, but highly recommended for clean URLs
head: # Optional, for any page-specific includes
- html tag in <head> 1
- html tag in <head> 2
- ...To add a new menu item to the navigation bar, edit the _includes/navbar.html file. You can add a new <li> element with a link to the desired page and use the same logic to set the "active" class based on the current page URL. For example, to add a "People" menu item linking to /people/, you would add:
<li>
<a href="{{ '/people/' | relative_url }}"{% if page.url == '/people/' or page.url contains '/people/' %} class="active"{% endif %}>People</a>
</li>Make sure to place it in the correct position within the <ul> to maintain the desired order of menu items.
Important: The site is built from gh-pages, not master. Keep gh-pages clean: it should contain only the built site (i.e., the contents of the _site/ folder after running bundle exec jekyll build), and nothing else.
- Develop on
master - Build locally
- Deploy by replacing
gh-pageswith_site/contents
- On
master, build the site without the--draftsflag to exclude draft posts:
bundle exec jekyll build- Switch to
gh-pages:
git checkout gh-pages- Replace
gh-pagescontents with the latest build:
git pull origin gh-pages # Ensure you have the latest changes
git rm -rf .
cp -r _site/* .- Commit and push:
git add -A
git commit -m "build $(date -Iseconds)" # Using ISO 8601 format for precise timestamps
git push origin gh-pages- Switch back to
masterto continue development:
git checkout masterAfter the steps above, CSS files will be naturally missing and need to be recompiled on master to be included during development.
- Always ensure you are on the correct branch (
masterfor development,gh-pagesfor deployment) before running build or deployment commands. - Built output is in
_site/(ignored via .gitignore). - The
gh-pagesbranch should only contain the built site. Do not commit source files or development changes togh-pages.