Jekyll-portfolio

A Jekyll template based on the Minima theme, with the addition of a portfolio page template.

Deployment to github pages is done through Github action, see below.

Contents At-A-Glance

This template is based on the latest version of Minima, with slightly modified site branding, an addition of a portfolio layout, and Staticman static comments support.

• For all other files and configuration options not described here, please refer to the Minima documentation
• For a step-by-step tutorial on how to set up Staticman for your own site, please refer to Travis Downs' post on the subject.

Layouts

Refers to files within the _layouts directory, that define the markup for your theme.

• portfolio.html — The layout for your portfolio. Builds your portfolio based on a collection stored in _portfolio.
  This file will only render if a .md page with layout: portfolio in it's front matter is present
• post.html — Modified from Minima's version to include Staticman static comments.

Portfolio

Refers to files within the _portfolio directory, which contain the Markdown files that define each portfolio project, and contain the brief description of the project to be displayed in mouseover events.

Each file in the directory can contain the following front matter:

place: # Integer, optional. See collection definition in _config.yml.
cover: coverimg.jpg # Optional but highly desirable. See assets/img/portfolio, below.
title: "A short title" # Will display in the short description of the project.
tags: tag1 tag2 # Tags for filtering relevant projects by buttons in the portfolio.html layout.
link: https://github.com/UriShX/Jekyll-portfolio # Optional, if the project can be linked to a blog post, etc.
modal:
  - code:
        link: https://raw.githubusercontent.com/githubuser/portfolio/master/some-arduino-script.ino
        lang: cpp # Required if code key is in use
        # linenos: linenos="1 22"
  - md: https://raw.githubusercontent.com/githubuser/portfolio/master/README.md
  - img: project_image1.png # See assets/img/portfolio, below.
  - img: project_image2.gif # See assets/img/portfolio, below.
  - img: coverimg.jpg # See assets/img/portfolio, below.

The modal key elements' order defines the default behavior of the gallery modal windows. If the first element is either a md or a code link, the first modal will display the parsed content of this file, and will display a link to a lightbox gallery. If the first element is img, the first modal to display for each project will be a lightbox, and if one of the modal sub-keys is either md or code they will be displayed as a placeholder image link, which when pressed will lead to the modal containing the parsed code or markdown.

The front matter does not have to contain any subkeys in the modal key to disaply the project with a brief description and a cover image

Sass

Refers to .scss files within the _sass directory that define the theme's styles.

• drublic-css-modal/ — This library contains the CSS based modal files. See documentation at css-modal.
• minima/ — This library contains the customized files which define the layout for Minima,including the portfolio layout, the custom header, and the imports of all .scss and .css files.

Assets

Refers to various asset files within the assets directory.

• assets/css/zenburn.css — Pygments / Rouge code highlighting. From jekyll-pygments-themes.
• assets/img/banner.png — Site branding banner. Configure in _config.yml.
• assets/img/logo.png — Site branding logo. Used as placeholder cover image for portfolio projects which do not specify a cover image in their front matter. Configure in _config.yml.
• assets/img/portfolio/ — Parent folder for portfolio projects' images. Each project should have it's own subfolder, eg.:
  ├ _portfolio/
  │ ├ project1.md
  │ └ project2.md
  ├ _assets/
  │ └ img/
  │ └ portfolio/
  │  ├ project1/
  │  │ ├ image1.gif
  │  │ └ image2.gif
  │  └ project2/
  │   └ image1.gif \
• assets/img/portfolio/twotone_description_black_48pt_3x.png — Placeholder image for modal galleries which contain both code or markdown files as well as images.
• assets/script/modal* — Files used by css-modal, for use in portfolio projects.
• assets/scripts/portfolio-tag-filter.js — Used in portfolio.html. Filters portfolio projects according to selected tag (button), and changes the close <a> tag href to the selcted tag.
• assets/script/staticman-comments.js — Static comments JS controller, for use with Staticman.
• assets/minima-social-icons.svg — A composite SVG file comprised of symbols related to various social-media icons.
  This file is used as-is without any processing. Refer section on social networks for its usage.\

Added the Hackaday logo.

Plugins

• Minima comes with jekyll-seo-tag plugin preinstalled to make sure your website gets the most useful meta tags. See usage to know how to set it up.
• Plugins included in the Gemfile:
  • jekyll-remote-include — Based on netrics/jekyll-remote-include.
    I've added the possibility to allow passing the link parameter to the Liquid tag, in order to get the link from a portfolio project's front matter.
    There's an open pull request for the change.
  • jekyll-highlight-param — Based on Jekyll's highlight Liquid tag to allow passing the language parameter from a portfolio project's front matter.

Deploy to github

Since the site uses plugins and a custom template, I am using a Github action by limjh16/jekyll-action-ts to publish the site to github pages.
You can find a sample workflow file for publishing the site to a github pages user site in the main directory of this repo, named sample_publish_workflow.yml.

Since this repository contains only the template for my site, it uses a workflow by sepulsa to create a PR on my site's hidden repository. You can find that workflow configuration file for this repo, under .github\workflows.

Usage

To use this template you can download or git clone this repository. If you do, please replace the site's branding (assets\img\logo.png, assets\img\log_code.png, assets\img\banner.png), and replace it with your own \

Have the following line in your config file:

theme: minima

Portfolio configuration

The portfolio.html relys on a definition of a dedicated collection, called portfolio. The markdown files for this collection are placed in the _portfolio/ directory, as decribed above. Have the following in your _config.yml:

collections:
  portfolio:
    sort_by: place # Optional, less comfortable to use then order.
    order: # Optional, but much better in practice than sort_by.
      - project5.md
      - project2.md
      - project1.md

In the above example, The projects will be displayed in the following order:

1. Project5
2. Project2
3. Project1
4. Project3
5. Project4

Followed by any other projects found in the _portfolio/ directory

Author Metadata

From Minima-3.0 onwards, site.author is expected to be a mapping of attributes instead of a simple scalar value:

author:
  name: John Smith
  copyright-year: 2020
  email: "[email protected]"

Social networks

I have added the Hackaday logo to Minima's default social networks icons. \

Check out the documentation for how to set up social network configuration in the Minima readme.

Enabling Excerpts on the Home Page

To display post-excerpts on the Home Page, simply add the following to your _config.yml:

show_excerpts: true

Static comments in posts

To use static comments using Staticman in posts instead of Minima's default Disqus, Travis Downs' post on the subject was a great starting point for me, and there's a staticman.yml file included in the main folder of this repo, as well as the required lines in _config.yml for setting up Google reCaptcha.
Comments are enabled in the post's front matter:

comments: true

Development

To test your site, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using your template and the contents. As you make modifications, your site will regenerate and you should see the changes in the browser after a refresh.

License

The theme is available as open source under the terms of the MIT License.