Skip to content

Commit 8c3bafe

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

File tree

1 file changed

+331
-0
lines changed

1 file changed

+331
-0
lines changed

‎_drafts/announcing-pixyll-version-3.md‎

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

0 commit comments

Comments
 (0)