minimal

Minimal is a Jekyll theme for GitHub Pages

1,550

5,937

1,550

154

View on GitHub

Top Related Projects

poole

2,823

The Jekyll Butler. A no frills responsive Jekyll blog theme.

minimal-mistakes

12,328

:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.

jekyll-now

8,238

Build a Jekyll blog in minutes, without touching the command line.

minima

3,387

Minima is a one-size-fits-all Jekyll theme for writers.

beautiful-jekyll

5,321

✨ Build a beautiful and simple website in literally minutes. Demo at https://beautifuljekyll.com

academicpages.github.io

12,092

Github Pages template for academic personal websites, forked from mmistakes/minimal-mistakes

Quick Overview

Pages-themes/minimal is a Jekyll theme for GitHub Pages. It provides a clean, minimalist design for project documentation or personal websites, focusing on simplicity and readability. The theme is customizable and easy to set up for GitHub Pages users.

Pros

Simple and elegant design that puts content first
Easy to customize with minimal configuration
Responsive layout that works well on various devices
Seamless integration with GitHub Pages

Cons

Limited built-in features compared to more complex themes
May require additional customization for advanced layouts
Not suitable for projects requiring complex navigation or extensive sidebars
Limited color scheme options out of the box

Getting Started

To use the Minimal theme with your GitHub Pages site:

Add the following to your site's _config.yml:

remote_theme: pages-themes/minimal@v0.2.0
plugins:
- jekyll-remote-theme

Optionally, if you'd like to preview your site on your computer, add the following to your site's Gemfile:

gem "github-pages", group: :jekyll_plugins

Customize the theme by editing _config.yml:

title: [Your Project Title]
description: [A short description of your project]
show_downloads: [true/false]
google_analytics: [Your Google Analytics tracking ID]

Create your pages in Markdown and use the default layout:

---
layout: default
---

# Welcome to my website

This is a sample page using the Minimal theme.

With these steps, you can quickly set up a minimalist website using the pages-themes/minimal Jekyll theme on GitHub Pages.

Competitor Comparisons

poole

2,823

The Jekyll Butler. A no frills responsive Jekyll blog theme.

Pros of Poole

More comprehensive starter kit with pre-built layouts and includes
Offers a complete Jekyll setup with sample posts and pages
Provides a solid foundation for building custom themes

Cons of Poole

Less minimalistic, potentially more complex for beginners
Requires more customization to achieve a unique look
May include unnecessary features for simple projects

Code Comparison

Minimal (_layouts/default.html):

<!DOCTYPE html>
<html lang="{{ site.lang | default: "en-US" }}">
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">

Poole (_layouts/default.html):

<!DOCTYPE html>
<html lang="en-us">
  {% include head.html %}
  <body>
    {% include sidebar.html %}
    <div class="content container">
      {{ content }}
    </div>

The code comparison shows that Minimal uses a more straightforward approach with all elements in a single file, while Poole utilizes includes for modular organization. Poole's structure allows for easier customization and maintenance of individual components, but may be more complex for beginners. Minimal's approach is simpler and more lightweight, making it easier to understand and modify for those new to Jekyll themes.

minimal-mistakes

12,328

:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.

Pros of Minimal Mistakes

More feature-rich with extensive customization options
Responsive design with mobile-first approach
Active development and community support

Cons of Minimal Mistakes

Steeper learning curve due to more complex structure
Potentially slower load times due to additional features
Requires more setup and configuration

Code Comparison

Minimal:

title: Minimal theme
logo: /assets/img/logo.png
description: Minimal is a theme for GitHub Pages.
show_downloads: true
google_analytics:
theme: jekyll-theme-minimal

Minimal Mistakes:

minimal_mistakes_skin: "default"
locale: "en-US"
title: "My Awesome Site"
subtitle: "A brief description"
name: "Your Name"
description: "An amazing website."
url: "https://yourdomain.com"
repository: "username/repo-name"

The Minimal theme configuration is simpler, while Minimal Mistakes offers more detailed customization options. Minimal Mistakes provides a more comprehensive structure for larger sites or blogs, whereas Minimal is better suited for smaller, simpler projects. The choice between the two depends on the project's complexity and the desired level of customization.

jekyll-now

8,238

Build a Jekyll blog in minutes, without touching the command line.

Pros of jekyll-now

Easier setup for beginners with a more streamlined process
Includes more pre-built features and layouts out of the box
Better documentation and step-by-step instructions for getting started

Cons of jekyll-now

Less flexible and customizable compared to minimal
May include unnecessary features for users who want a simpler setup
Not as actively maintained, with fewer recent updates

Code Comparison

minimal:

title: Minimal theme
logo: /assets/img/logo.png
description: Minimal is a theme for GitHub Pages.
show_downloads: true
google_analytics:
theme: jekyll-theme-minimal

jekyll-now:

name: Your Name
description: Web Developer from Somewhere
avatar: https://raw.githubusercontent.com/barryclark/jekyll-now/master/images/jekyll-logo.png
footer-links:
  dribbble:
  email:
  facebook:
  flickr:

The code snippets show differences in the configuration files. minimal focuses on basic site information and theme settings, while jekyll-now includes more detailed personal information and social media links.

minima

3,387

Minima is a one-size-fits-all Jekyll theme for writers.

Pros of Minima

More feature-rich with built-in support for tags, categories, and social media links
Includes a responsive design out-of-the-box, adapting well to various screen sizes
Offers multiple color scheme options, allowing for easy customization

Cons of Minima

Larger file size and more complex structure, potentially slower to load
Less minimalistic, which may not suit users looking for a very simple theme
Requires more configuration to customize beyond the default options

Code Comparison

Minimal (default layout):

<body>
  <div class="wrapper">
    <header>
      {% if site.logo %}
        <img src="{{site.logo | relative_url}}" alt="Logo" />
      {% endif %}
      <h1><a href="{{ "/" | absolute_url }}">{{ site.title | default: site.github.repository_name }}</a></h1>
    </header>
    <section>
      {{ content }}
    </section>
    <footer>
      {% if site.github.is_project_page %}
      <p>This project is maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a></p>
      {% endif %}
    </footer>
  </div>
</body>

Minima (default layout):

<body>
  {% include header.html %}
  <main class="page-content" aria-label="Content">
    <div class="wrapper">
      {{ content }}
    </div>
  </main>
  {% include footer.html %}
</body>

beautiful-jekyll

5,321

✨ Build a beautiful and simple website in literally minutes. Demo at https://beautifuljekyll.com

Pros of Beautiful Jekyll

More feature-rich with built-in functionality like social media integration, Google Analytics, and comments
Highly customizable with numerous configuration options
Includes a responsive design out-of-the-box

Cons of Beautiful Jekyll

Steeper learning curve due to more complex structure and configuration
Larger file size and potentially slower load times
May require more maintenance as it has more moving parts

Code Comparison

Beautiful Jekyll configuration example:

title: My Website
author: John Doe
navbar-links:
  About Me: "aboutme"
  Resources:
    - Beautiful Jekyll: "https://beautifuljekyll.com"
    - Learn markdown: "https://www.markdowntutorial.com/"

Minimal configuration example:

title: My Website
description: A simple Jekyll theme
show_downloads: true
google_analytics: UA-XXXXXXXX-X
theme: jekyll-theme-minimal

Beautiful Jekyll offers more detailed configuration options, while Minimal keeps things simpler with fewer customization points. Beautiful Jekyll provides built-in navigation and resource linking, whereas Minimal requires manual implementation of these features.

academicpages.github.io

12,092

Github Pages template for academic personal websites, forked from mmistakes/minimal-mistakes

Pros of academicpages

More comprehensive and feature-rich for academic websites
Includes templates for publications, talks, and teaching
Offers a ready-to-use structure for academic portfolios

Cons of academicpages

More complex setup and customization process
Potentially overwhelming for users seeking a simple website
Requires more maintenance due to its extensive features

Code Comparison

minimal:

theme: jekyll-theme-minimal
title: [Your Name]
description: [Brief description]

academicpages:

title: "Your Name"
excerpt: "About me"
author_profile: true
redirect_from: 
  - /about/
  - /about.html

The minimal theme uses a simpler configuration, while academicpages offers more detailed customization options and built-in features for academic content. The academicpages code snippet shows how it handles redirects and author profiles, which are not present in the minimal theme by default.

Both repositories use Jekyll, but academicpages is specifically tailored for academic websites, offering a more comprehensive solution out of the box. The minimal theme, on the other hand, provides a clean slate for users to build upon, making it more versatile for various types of websites but requiring more work to achieve the same level of functionality as academicpages for academic purposes.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

The Minimal theme

Minimal is a Jekyll theme for GitHub Pages. You can preview the theme to see what it looks like, or even use it today.

Usage

To use the Minimal theme:

Add the following to your site's _config.yml:

remote_theme: pages-themes/minimal@v0.2.0
plugins:
- jekyll-remote-theme # add this line to the plugins list if you already have one

Optionally, if you'd like to preview your site on your computer, add the following to your site's Gemfile:
```
gem "github-pages", group: :jekyll_plugins
```

Customizing

Configuration variables

Minimal will respect the following variables, if set in your site's _config.yml:

title: [The title of your site]
description: [A short description of your site's purpose]

Additionally, you may choose to set the following optional variables:

show_downloads: ["true" or "false" (unquoted) to indicate whether to provide a download URL]
google_analytics: [Your Google Analytics tracking ID]

Stylesheet

If you'd like to add your own custom styles:

Create a file called /assets/css/style.scss in your site
Add the following content to the top of the file, exactly as shown:
```
---
---

@import "{{ site.theme }}";
```
Add any custom CSS (or Sass, including imports) you'd like immediately after the @import line

Note: If you'd like to change the theme's Sass variables, you must set new values before the @import line in your stylesheet.

Layouts

If you'd like to change the theme's HTML layout:

For some changes such as a custom favicon, you can add custom files in your local _includes folder. The files provided with the theme provide a starting point and are included by the original layout template.
For more extensive changes, copy the original template from the theme's repository
(Pro-tip: click "raw" to make copying easier)
Create a file called /_layouts/default.html in your site
Paste the default layout content copied in the first step
Customize the layout as you'd like

Customizing Google Analytics code

Google has released several iterations to their Google Analytics code over the years since this theme was first created. If you would like to take advantage of the latest code, paste it into _includes/head-custom-google-analytics.html in your Jekyll site.

Overriding GitHub-generated URLs

Templates often rely on URLs supplied by GitHub such as links to your repository or links to download your project. If you'd like to override one or more default URLs:

Look at the template source to determine the name of the variable. It will be in the form of {{ site.github.zip_url }}.
Specify the URL that you'd like the template to use in your site's _config.yml. For example, if the variable was site.github.url, you'd add the following:
```
github:
  zip_url: http://example.com/download.zip
  another_url: another value
```
When your site is built, Jekyll will use the URL you specified, rather than the default one provided by GitHub.

Note: You must remove the site. prefix, and each variable name (after the github.) should be indent with two space below github:.

For more information, see the Jekyll variables documentation.

Roadmap

See the open issues for a list of proposed features (and known issues).

Project philosophy

The Minimal theme is intended to make it quick and easy for GitHub Pages users to create their first (or 100th) website. The theme should meet the vast majority of users' needs out of the box, erring on the side of simplicity rather than flexibility, and provide users the opportunity to opt-in to additional complexity if they have specific needs or wish to further customize their experience (such as adding custom CSS or modifying the default layout). It should also look great, but that goes without saying.

Contributing

Interested in contributing to Minimal? We'd love your help. Minimal is an open source project, built one contribution at a time by users like you. See the CONTRIBUTING file for instructions on how to contribute.

Previewing the theme locally

If you'd like to preview the theme locally (for example, in the process of proposing a change):

Clone down the theme's repository (git clone https://github.com/pages-themes/minimal)
cd into the theme's directory
Run script/bootstrap to install the necessary dependencies
Run bundle exec jekyll serve to start the preview server
Visit localhost:4000 in your browser to preview the theme

Running tests

The theme contains a minimal test suite, to ensure a site with the theme would build successfully. To run the tests, simply run script/cibuild. You'll need to run script/bootstrap once before the test script will work.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot