Skip to content

Commit 8146651

Browse files
ashawleyashawley
committed
Blog post for Pixyll 3
1 parent e510150 commit 8146651

File tree

1 file changed

+337
-0
lines changed

1 file changed

+337
-0
lines changed

‎_posts/2019-03-18-announcing-pixyll-version-3.md‎

Lines changed: 337 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,337 @@
1+
---
2+
layout: post
3+
title: Announcing Pixyll version 3.0
4+
date: 2019-03-18 23:03
5+
summary: Now, Pixyll is easier to use with Jekyll
6+
categories: jekyll pixyll
7+
---
8+
9+
It's easier to use Pixyll as your Jekyll theme.
10+
11+
Pixyll is now available as a gem-based theme as version 3.0.
12+
13+
With a gem-based theme, you no longer need to fork the git repository.
14+
15+
The following will explain using the gem-based theme. Although if you prefer, you can continue to do so.
16+
17+
Pixyll users who used a Git fork, can keep their fork and can get a sense of the breaking changes in 3.0 and also how to resolve them in the section on [existing Pixyll sites](#existing-pixyll-sites) and by reviewing the changes in the [release notes for 3.0](https://github.com/johno/pixyll/releases/tag/v3.0.0).
18+
19+
We'll start by outlining how existing Jekyll users enable Pixyll as their theme.
20+
21+
## Existing Jekyll sites
22+
23+
If you have an existing Jekyll site, you can move your Jekyll site to Pixyll in the following steps:
24+
25+
1. Add the Pixyll gem to your `Gemfile`.
26+
2. Set the theme to `pixyll` in your `_config.yml` file.
27+
3. Add jekyll-paginate to the plugins section of your `_config.yml` file.
28+
4. Configure how many posts to list per page by adding a value for `paginate` (e.g. `4`) in your `_config.yml` file.
29+
5. Change the layout in your `index.md` to be `home`.
30+
6. Rename your `index.md` to `index.html`.
31+
7. Modify your `contact.html` to use the `contact` layout.
32+
8. Change your blog posts to use the `post` layout.
33+
9. Change any other pages on your Jekyll to use the `page` layout.
34+
35+
That's a lot of steps. They are nearly the same as those for starting a new site, so you can walk through each task, one-at-a-time, in the next section.
36+
37+
If you have a pre-existing Pixyll-based site, then you can also follow the next steps and a few additional steps for [existing Pixyll sites](#existing-pixyll-sites) at the end.
38+
39+
## New sites
40+
41+
Before starting a new Jekyll site, you need to have [Bundler](https://bundler.io) and [Jekyll](https://jekyllrb.com) installed.[^1]
42+
43+
```sh
44+
gem install --no-document bundler # If you don't have bundler installed
45+
gem install --no-document jekyll
46+
```
47+
48+
You can use Jekyll to create a skeleton site for you:
49+
50+
```sh
51+
jekyll new my-pixyll-site
52+
```
53+
54+
You should change in to the new site's directory, and have Bundler download and manage the dependencies for your Jekyll site.
55+
56+
```sh
57+
cd my-pixyll-site
58+
bundle install
59+
```
60+
61+
### 1. Add Pixyll to your Gemfile
62+
63+
You'll want to add Pixyll to your Gemfile:
64+
65+
```ruby
66+
gem "pixyll", "~> 3.0"
67+
```
68+
69+
The default theme for Jekyll is Minima, so you can remove the entry `gem "minima"`.
70+
71+
Then run the Bundler "install" command so Bundler will both download and manage the dependencies for Pixyll:
72+
73+
```sh
74+
bundle install
75+
```
76+
77+
The `~> 3.0` means that Bundler will set Pixyll to automatically update to any 3.0 version. This would include Pixyll versions 3.0.1, 3.1.2 and 3.9.9 (These new versions don't exist, today).
78+
79+
We promise not to introduce breaking changes in 3.0, per [Semantic Versioning](https://semver.org/), but Pixyll is provided "as is" without warranty. We can't guarantee that there won't be breaking changes with upgrading.
80+
81+
You can pin your version of Pixyll by keeping a `Gemfile.lock` file or by [changing the version specification](https://bundler.io/v1.17/gemfile.html) in your `Gemfile`. When you have a `Gemfile.lock`, you can manually run `bundle update pixyll` to upgrade Pixyll to the latest 3.0 version.
82+
83+
### 2. Add Pixyll to your Gemfile
84+
85+
Edit your `_config.yml` to use Pixyll as your theme:
86+
87+
```yml
88+
theme: pixyll
89+
```
90+
91+
There should already be an entry there
92+
93+
### 3. Add jekyll-paginate to plugins
94+
95+
Add `jekyll-paginate` to the "plugins" section of your your `_config.yml`:
96+
97+
```yml
98+
plugins:
99+
- jekyll-paginate
100+
```
101+
102+
If you already have an entry for `github-pages` in your `Gemfile`, then you don't need to add the `jekyll-paginate` gem.
103+
104+
If you happen to not have the `github-pages` gem, then you need to add the `jekyll-paginate` gem.
105+
106+
```ruby
107+
group :jekyll_plugins do
108+
gem "jekyll-paginate", "~> 1.1.0"
109+
end
110+
```
111+
112+
```yml
113+
gem "pixyll", "~> 3.0"
114+
```
115+
116+
### 4. Configure posts per page
117+
118+
Set the number of posts to list per page by adding `paginate` in your `_config.yml` file. A good default is 4 posts per page:
119+
120+
```yml
121+
paginate: 4
122+
```
123+
124+
### 5. Use the home layout
125+
126+
Set the layout for your `index.md` to be the `home` layout:
127+
128+
```yml
129+
layout: home
130+
```
131+
132+
> Existing Pixyll users can remove the body of the page below the preamble.
133+
134+
### 6. Rename your index file
135+
136+
Because the Jekyll paginate plugin only works from an HTML file, you need to rename your `index.md` to `index.html`:
137+
138+
```sh
139+
git mv index.md index.html
140+
```
141+
142+
### 7. Use the contact layout
143+
144+
In order to use the contact page that ships with the Pixyll theme and get future fixes and improves, you should modify the `contact.html` in the root directory:
145+
146+
```yml
147+
---
148+
layout: contact
149+
title: Say Hello
150+
permalink: /contact/
151+
tags: contact
152+
---
153+
```
154+
155+
> For existing Pixyll users, you'll need to remove the body of the page below the preamble.
156+
157+
Add the contact page to the site navigation in the header:
158+
159+
```yml
160+
header_pages:
161+
- about.md
162+
- contact.html
163+
```
164+
165+
### 8. Use the post layout
166+
167+
Set the layout for all your blog posts to be `post`:
168+
169+
```yml
170+
layout: post
171+
```
172+
173+
### 9. Use the page layout
174+
175+
For any other pages on your Jekyll site that aren't the home page or a blog post, set the layout those other pages to be `page`:
176+
177+
```yml
178+
layout: page
179+
```
180+
181+
## Existing Pixyll sites
182+
183+
If you had an existing site using Pixyll, you have some additional steps.
184+
185+
You can try pull in the latest changes, but risks causing "git problems" for you. If you want you can just try to do the steps from the section above, in particular see (1), (2), (5), (7) from above.
186+
187+
Once you have done the steps from above, then you can migrate your existing Pixyll site with the following steps:
188+
189+
10. Remove the includes and layout templates.
190+
11. The icons have moved to `assets/img`.
191+
12. Rename the `pixyll.scss` file to `main.scss`.
192+
13. Remove the `_sass` directory.
193+
14. Add jekyll-sitemap to your `Gemfile`.
194+
15. Add a `Rakefile`.
195+
196+
A detailed description of each of these tasks is below.
197+
198+
### 10. Remove the templates
199+
200+
The layout and include templates are bundled in the gem for the Pixyll theme. You should remove the old ones:
201+
202+
```sh
203+
git rm _layouts/center.html
204+
git rm _layouts/default.html
205+
git rm _layouts/page.html
206+
git rm _layouts/post.html
207+
git rm _includes/ajaxify_content_form.html
208+
git rm _includes/footer.html
209+
git rm _includes/head.html
210+
git rm _includes/header.html
211+
git rm _includes/navigation.html
212+
git rm _includes/pagination.html
213+
git rm _includes/post_footer.html
214+
git rm _includes/share_buttons.html
215+
git rm _includes/social_links.html
216+
```
217+
218+
If you want to cutomize Pixyll, you can pull one or more of the layout or template files from the Pixyll git repoistory or follow the instructions at [Overriding theme defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults) from the Jekyll theme
219+
220+
### 10. Move your icons
221+
222+
The Pixyll theme provides default browser icons (also known as "favicons") and expects them to be in the `/assets/img` subdirectory.
223+
224+
They used to be in the root directory. If you had customized your icons, you need to move them to the new location:
225+
226+
```sh
227+
mkdir assets assets/img
228+
git mv apple-touch-icon-57x57.png assets/img/apple-touch-icon-57x57.png
229+
git mv apple-touch-icon-114x114.png assets/img/apple-touch-icon-114x114.png
230+
git mv apple-touch-icon-72x72.png assets/img/apple-touch-icon-72x72.png
231+
git mv apple-touch-icon-144x144.png assets/img/apple-touch-icon-144x144.png
232+
git mv apple-touch-icon-60x60.png assets/img/apple-touch-icon-60x60.png
233+
git mv apple-touch-icon-120x120.png assets/img/apple-touch-icon-120x120.png
234+
git mv apple-touch-icon-76x76.png assets/img/apple-touch-icon-76x76.png
235+
git mv apple-touch-icon-152x152.png assets/img/apple-touch-icon-152x152.png
236+
git mv apple-touch-icon-180x180.png assets/img/apple-touch-icon-180x180.png
237+
git mv favicon-192x192.png assets/img/favicon-192x192.png
238+
git mv favicon-160x160.png assets/img/favicon-160x160.png
239+
git mv favicon-96x96.png assets/img/favicon-96x96.png
240+
git mv favicon-16x16.png assets/img/favicon-16x16.png
241+
git mv favicon-32x32.png assets/img/favicon-32x32.png
242+
git mv favicon.ico assets/img/favicon.ico
243+
```
244+
245+
### 11. Rename pixyll.scss (optional)
246+
247+
If you customized `pixyll.scss` or any of the [Sass](https://sass-lang.com/) `.scss` files, then you need to move it to the `assets` directory and rename it `main.scss`:
248+
249+
```sh
250+
mkdir assets assets/css
251+
git mv css/pixyll.scss assets/css/main.scss
252+
```
253+
254+
If you haven't made any modifications to the main stylesheet file, then you might not get the style changes in the gem-based Pixyll theme. So you should just delete your `css/pixyll.scss` file:
255+
256+
```sh
257+
258+
```
259+
260+
### 12. Remove Sass files (optional)
261+
262+
If you customized any of the [Sass](https://sass-lang.com/) `.scss` files, then you'll want to keep your Sass files.
263+
264+
If you haven't made any modifications to the stylesheets, then you won't get the style changes in the gem-based Pixyll theme. You should just delete your copies of the `_sass` subdirectory:
265+
266+
```sh
267+
git rm -r _sass/
268+
```
269+
270+
### 13. Add jekyll-sitemap to your Gemfile (optional)
271+
272+
Pixyll 2.0 enabled the Jekyll plugin `jekyll-sitemap` in the `_config.yml`.
273+
274+
```yml
275+
plugins:
276+
- jekyll-sitemap
277+
```
278+
279+
It produces a `sitemap.xml` file to your site in support of the [Sitemaps.org](https://sitemaps.org) standard for search engines. If you're using Pixyll as a gem-based theme, you will be missing this gem. To add it back, put the following line in your `Gemfile`:
280+
281+
```ruby
282+
group :jekyll_plugins do
283+
gem "jekyll-sitemap", "~> 1.2.0"
284+
end
285+
```
286+
287+
Then run the Bundler "install" command so Bundler will download the dependency:
288+
289+
```sh
290+
bundle install
291+
```
292+
293+
### 14. Add a Rakefile (optional)
294+
295+
In order to use the `Rakefile` that ships with the Pixyll theme and get future fixes and improvements, you should createa `Rakefile` at the root directory of your site:
296+
297+
```ruby
298+
spec = Gem::Specification.find_by_name 'pixyll'
299+
rakefile = "#{spec.gem_dir}/Rakefile"
300+
load rakefile
301+
```
302+
303+
The rake tasks help you with routine tasks for your Jekyll site.
304+
305+
$ rake list
306+
Tasks: draft, post, preview, undraft
307+
(type rake -T for more detail)
308+
309+
Add a new post:
310+
311+
$ rake 'post[Hello\, world]'
312+
Creating new post: _posts/2019-02-08-hello-world.md
313+
314+
Add a new draft:
315+
316+
$ rake 'draft[Hello\, world]'
317+
Creating new draft: _drafts/hello-world.md
318+
319+
Publish a draft:
320+
321+
$ rake undraft[hello-world.md]
322+
Original date of draft: 2019-02-08 04:28
323+
Moving _drafts/hello-world.md to _posts/2019-02-08-hello-world.md...done.
324+
Modifying date for post to '2019-02-08 04:29'...done.
325+
326+
## GitHub pages
327+
328+
If you use [GitHub pages](https://pages.github.com/) to publish your Jekyll-based site, you can continue to use Pixyll by forking the repo, but you can now use Pixyll as [a theme on GitHub pages](https://github.blog/2017-11-29-use-any-theme-with-github-pages/).
329+
330+
```yml
331+
remote_theme: johno/pixyll
332+
```
333+
334+
You will need to follow all the Pixyll 3.0 changes, see above, to use Pixyll as your theme on GitHub pages.
335+
336+
---
337+
[^1]: This presumes you installed [Ruby](https://ruby-lang.org), already.

0 commit comments

Comments
 (0)