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.
Create a worktree for the gh-pages branch in the _deploy directory (only needs to be done once):
git worktree add --orphan -b gh-pages _deploy
touch _deploy/.nojekyll- 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 --unpublishedSite 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: false # Set to true if you want it to appear among flagship projects
published: true # Set to false if you want to keep it as a draft and not have it appear on the site yet
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, notmaster. Keepgh-pagesclean: it should contain only the built site (i.e., the contents of the_site/folder after runningbundle exec jekyll buildon themasterbranch), and nothing else.
Important: Ensure you already have the
gh-pagesworktree set up in_deploy/as described in the Project setup section above. This only needs to be done once.
- On
master, compile the CSS and build the site without the--unpublishedflag to exclude draft posts:
npm run scss:build
bundle exec jekyll build- Navigate to the
gh-pagesbranch using the worktree that resides in the special_deploydirectory:
cd _deploy- Replace contents of the
gh-pagesworktree with the latest build:
git pull origin gh-pages # Ensure you have the latest changes
rsync -av --delete ../_site/ . --exclude .git --exclude .nojekyll- 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:
cd -After 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.