README.md 3.61 KB
Newer Older
Matthew Verbyla's avatar
Matthew Verbyla committed
1
# The Minimal theme
Matthew Verbyla's avatar
Matthew Verbyla committed
2

Matthew Verbyla's avatar
Matthew Verbyla committed
3
[![Build Status](https://travis-ci.org/pages-themes/minimal.svg?branch=master)](https://travis-ci.org/pages-themes/minimal) [![Gem Version](https://badge.fury.io/rb/jekyll-theme-minimal.svg)](https://badge.fury.io/rb/jekyll-theme-minimal)
Matthew Verbyla's avatar
Matthew Verbyla committed
4

Matthew Verbyla's avatar
Matthew Verbyla committed
5
*Minimal is a Jekyll theme for GitHub Pages. You can [preview the theme to see what it looks like](http://pages-themes.github.io/minimal), or even [use it today](#usage).*
Matthew Verbyla's avatar
Matthew Verbyla committed
6

Matthew Verbyla's avatar
Matthew Verbyla committed
7
![Thumbnail of minimal](thumbnail.png)
Matthew Verbyla's avatar
Matthew Verbyla committed
8
9
10

## Usage

Matthew Verbyla's avatar
Matthew Verbyla committed
11
To use the Minimal theme:
Matthew Verbyla's avatar
Matthew Verbyla committed
12
13
14
15

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

    ```yml
Matthew Verbyla's avatar
Matthew Verbyla committed
16
    theme: jekyll-theme-minimal
Matthew Verbyla's avatar
Matthew Verbyla committed
17
18
19
20
21
22
23
24
    ```

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

    ```ruby
    gem "github-pages", group: :jekyll_plugins
    ```

Matthew Verbyla's avatar
Matthew Verbyla committed
25
26


Matthew Verbyla's avatar
Matthew Verbyla committed
27
28
29
30
## Customizing

### Configuration variables

Matthew Verbyla's avatar
Matthew Verbyla committed
31
Minimal will respect the following variables, if set in your site's `_config.yml`:
Matthew Verbyla's avatar
Matthew Verbyla committed
32
33
34
35
36
37
38
39
40

```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:

```yml
Matthew Verbyla's avatar
Matthew Verbyla committed
41
logo: [Location of the logo]
Matthew Verbyla's avatar
Matthew Verbyla committed
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
show_downloads: ["true" or "false" 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:

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

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

### Layouts

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

Matthew Verbyla's avatar
Matthew Verbyla committed
64
1. [Copy the original template](https://github.com/pages-themes/minimal/blob/master/_layouts/default.html) from the theme's repository<br />(*Pro-tip: click "raw" to make copying easier*)
Matthew Verbyla's avatar
Matthew Verbyla committed
65
66
67
68
69
70
2. Create a file called `/_layouts/default.html` in your site
3. Paste the default layout content copied in the first step
4. Customize the layout as you'd like

## Roadmap

Matthew Verbyla's avatar
Matthew Verbyla committed
71
See the [open issues](https://github.com/pages-themes/minimal/issues) for a list of proposed features (and known issues).
Matthew Verbyla's avatar
Matthew Verbyla committed
72
73
74

## Project philosophy

Matthew Verbyla's avatar
Matthew Verbyla committed
75
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.
Matthew Verbyla's avatar
Matthew Verbyla committed
76
77
78

## Contributing

Matthew Verbyla's avatar
Matthew Verbyla committed
79
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](docs/CONTRIBUTING.md) for instructions on how to contribute.
Matthew Verbyla's avatar
Matthew Verbyla committed
80
81
82
83
84

### Previewing the theme locally

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

Matthew Verbyla's avatar
Matthew Verbyla committed
85
1. Clone down the theme's repository (`git clone https://github.com/pages-themes/minimal`)
Matthew Verbyla's avatar
Matthew Verbyla committed
86
87
88
89
90
91
92
2. `cd` into the theme's directory
3. Run `script/bootstrap` to install the necessary dependencies
4. Run `bundle exec jekyll serve` to start the preview server
5. Visit [`localhost:4000`](http://localhost:4000) in your browser to preview the theme

### Running tests

Matthew Verbyla's avatar
Matthew Verbyla committed
93
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` one before the test script will work.