
I was cleaning up my [Neovim config files](https://github.com/roginfarrer/dotfiles) as I periodically do, and I found a handful of "sensible defaults" that I had copied from others' dotfiles long ago. Being one to eagerly eliminate redundant code, and especially skeptical of code thats intentions are unclear to me, I started consulting the Neovim help manual. Much to my delight, I discovered I had about a dozen lines in my config that merely reaffirmed the default settings. Bye, unnecessary code!

Speaking of sensible defaults, a very popular plugin recommended to newcomers to Vim is [vim-sensible][vim-sensible], which establishes "a universal set of defaults that (hopefully) everyone can agree on." One of Vim's most loved qualities is its backwards compatabilities with its predecessor vi and versions decades old. That said, that means it also ships with settings in 2020 that make you scratch your head. Why would syntax highlighting be disabled by default?? vim-sensible is "one step above `'nocompatible'` mode", establishing a set of defaults that makes sense in the modern era of text editing.

But what of Neovim? Should new users of Neovim adopt vim-sensible? Does Neovim need to be "reset"?

From my perspective, the answer is **no**, vim-sensible is _mostly_ redundant. (I'll address the "mostly" part in a second). You'll be happy to hear that most of the defaults established in vim-sensible are corroborated by Neovim. If you're curious, here's a (almost) comprehensive summary of the settings defined by vim-sensible and its setting in Neovim defaults.

## vim-sensible & Neovim defaults compared

- ✅ = Neovim and vim-sensible are aligned
- ❌ = Neovim and vim-sensible differ
- ❗ = Neovim and vim-sensible differ, but in a very subtle way

| Rule                         | Neovim | Notes                                                           |
| ---------------------------- | ------ | --------------------------------------------------------------- |
| `filetype`                   | ✅     |                                                                 |
| `plugin`                     | ✅     |                                                                 |
| `indent`                     | ✅     |                                                                 |
| `syntax`                     | ✅     |                                                                 |
| `autoindent`                 | ✅     |                                                                 |
| `autoread`                   | ✅     |                                                                 |
| `backspace=indent,eol,start` | ✅     |                                                                 |
| `incsearch`                  | ✅     |                                                                 |
| `laststatus=2`               | ✅     |                                                                 |
| `ttimeout`                   | ✅     |                                                                 |
| `ruler`                      | ✅     |                                                                 |
| `wildmenu`                   | ✅     |                                                                 |
| `encoding=utf-8`             | ✅     |                                                                 |
| `tabpagemax=50`              | ✅     |                                                                 |
| `t_Co=16`                    | ✅     | Neovim doesn't need this setting                                |
| `ttimeoutlen=100`            | ❌     | Neovim defaults to 50                                           |
| `scrolloff=1`                | ❌     | Neovim defaults to 0                                            |
| `sidescrolloff=5`            | ❌     | Neovim defaults to 0                                            |
| `display+=lastline`          | ❗     | Neovim defaults to display=lastline,msgsep                      |
| `listchars`                  | ❗     | vim-sensible and Neovim depart from the vi defaults differently |
| `formatoptions+=j`           | ❗     | Neovim: formatoptions=tcqj                                      |
| `history=1000`               | ❗     | Neovim defaults to 10000                                        |
| `sessionoptions-=options`    | ❗     | Neovim deprecated sessionoptions                                |
| `viewoptions-=options`       | ❗     | Neovim deprecated viewoptions                                   |

As you can see, most of what we think are the most critical options to enable by default (syntax highlighting, filetype detection, etc) are made the defaults in Neovim. vim-sensible and Neovim start to diverge on more nuanced settings, that arguably aren't relevant to most newcomers of Vim.

## Does Neovim need a "neovim-sensible"?

Unlike Vim, I think a total newcomer to Neovim could get started and be mostly happy with the defaults, and for anything that they encounter they don't like, they can Google a solution for it. That said, here are a few settings that most folks will _probably_ add to their config at some point:

```vim
" Allows you to change buffers even if the current on has unsaved changes
set hidden

" Intuit the indentation of new lines when creating them
set smartindent

" Return to last edit position when opening files
" It's some magic I picked up somewhere, no idea how it works
" or what alternatives are out there
au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g'\"" | endif

" Who wants .swap files??
set noswapfile

" Enable mouse support
set mouse=a

" Turn persistent undo on
" means that you can undo even when you close a buffer/VIM
set undodir=~/.vim_runtime/temp_dirs/undodir
set undofile
```

[vim-sensible]: https://github.com/tpope/vim-sensible


Neovim and vim-sensible

Web Components and React Components - A Comparison


One of the longest standing bugs I've encountered with [`useCollapse`](https://github.com/roginfarrer/react-collapsed) is a never-ending expanding animation when there's padding applied to the collapsed element.

`useCollapse` is a custom hook for creating accessible, animated collapse components.

I've exhausted countless hours on this one edge case bug, where if padding is applied to the collapse element, the animation will just never end: it keeps growing!

<iframe
     src="https://codesandbox.io/embed/react-collapsed-infinite-animation-bug-5gwfw?fontsize=14&hidenavigation=1&theme=dark"
     style="height:500px; border:0; border-radius: 4px; overflow:hidden;"
     title="react-collapsed infinite animation bug"
     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr"
     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
   ></iframe>

What's going on here? Well, it has to do with how the hook attempts to accommodate content changes within the collapse element. When the transition ends, we do a check to make sure that the height of the element matches the height we set the element to animate to before the transition began:

```javascript
// Abbreviated to keep it concise

const handleTransitionEnd = () => {
  // The height comparisons below are a final check before completing the transition
  // Sometimes this callback is run even though we've already begun transitioning the other direction
  // The conditions give us the opportunity to bail out, which will prevent the collapsed content from flashing on the screen
  if (isOpen) {
    const height = getElementHeight(el);
    if (height === styles.height) {
      // just reset style overrides
      setStyles({});
    } else {
      // If the heights don't match, this could be due the height of the content changing mid-transition
      // If that's the case, re-trigger the animation to animate to the new height
      setStyles((oldStyles) => ({ ...oldStyles, height }));
    }
  }
};
```

At the end of the animation, we measure the element again, and compare the element's height to the height we animated to: `height === styles.height`. If they're not identical, we set the height to the element's current height, hoping to eventually reach a point where the element's dimensions stop fluctuating and settle.

When the collapse element does not have vertical padding applied, this solution works pretty well, and the animation will reliably settle. However, when vertical padding is applied, we get the bouncing accordion in the sandbox above, as the function compares over and over again the current element's height and the height it intended to animate to.

In the hours spent debugging this, I considered a number of variables. Was `scrollHeight` the incorrect way to be measuring height? Was `clientHeight` or `offsetHeight` more appropriate? (I concluded no, `scrollHeight` should in fact be accounting for the element's true dimensions, including padding.)

Did I need to explicitly account for padding in the measurement? One peculiarity I was finding was that at that moment in the transition lifecycle, `offsetHeight` produced the number closest to the actual height of the element, and `clientHeight` and `offsetHeight` were actually returning not the height of the element, but _just_ the padding! So maybe I needed to add the two together?

```javascript
const handleTransitionEnd = () => {
  if (isOpen) {
    const height = el.current.scrollHeight + el.current.clientHeight;
    if (height !== styles.height) {
      setStyles((oldStyles) => ({ ...oldStyles, height }));
    }
  }
};
```

This also never worked, and the infinite animation continued.

I then also considered that using the `onTransitionEnd` callback was flawed. While `onTransitionEnd` seemed like the perfect lifecycle hook for detecting when the transition ended (surprise!), maybe it would be better to use a `setTimeout` given the duration of the animation. I tried refactoring useCollapse with `setTimeout`, and that just caused more compromises and challenges.

After hours and hours of fiddling with DOM measurement calculations, through refactors of the utility from component to hook, I'd just about given up. I'd added a "gotcha" section to the repo's documentation, and had added an error that would throw in runtime if the developer applied padding to the collapse element. I thought the fix didn't exist.

## `border-box`, to the rescue!

Later on, when I was rewriting demos for v3 of `useCollapse`, I came across a tiny style bug when using a `<div>` element for the collapse toggle button (to show it can still be accessible without a `<button>` element.) Lo and behold, making a `div` resemeble a `button` element is actually a little tricky, and I noticed a weird spacing issue, that when I set a fixed width on the toggle button, the `button` element complied, but the `div` did not! Aha, I said to myself: the issue was the element not having `box-sizing: border-box`. And, of course, it was, and the `div` element did then actually respect the width I had provided.

And then, a lightbulb went off!

![Andy for parks and rec looking excited](/images/andy.gif)

It was `box-sizing`! I quickly added `box-sizing: border-box` to the collapse element, and poof! the bug was gone!

How did a single line of CSS fix this JavaScript conundrum? Let's dive into why this change was significant.

## `content-box` vs `border-box`

First of all, what is [`box-sizing`](https://devdocs.io/css/box-sizing)? This property determines how the browser will calculate the total width and height of an element. The default value for `box-sizing` is `content-box`, which constrains the measurement to _only_ the element's content, not accounting for its `padding` or `border`. `border-box`, in contrast, _includes_ that `padding` and `border`.

Because it's a CSS property, you might assume that this only affects other CSS properties. But it actually changes how the browser will measure the element in JavaScript.

Let's take a look at how that manifests:

<iframe
     src="https://codesandbox.io/embed/measuring-height-border-box-1ymee?fontsize=14&hidenavigation=1&theme=dark"
     style="height:500px; border:0; border-radius: 4px; overflow:hidden;"
     title="Measuring height, border-box"
     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr"
     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
   ></iframe>

Above, we measure the height of two elements in the same manner. Both have padding, and only one has the `box-sizing` value changed from `content-box` (the browser default) to `border-box`. When we measure the height of element with `content-box`, we get 100, which is the height we explicitly set on the element, and does not include the padding. The element with `border-box` yields 120, which is both the height we set on the element, and includes the padding (10 on the top and bottom: 100 + 10 + 10 = 120).

Going back to `useCollapse`, now when the transition ends and we calculate the height of the element, we're now actually measuring the true total height of the element and its content, so we get an accurate comparison, and the animation will finally end!

Here's `useCollapse` today with padding applied to the element:

<iframe
     src="https://codesandbox.io/embed/inspiring-poitras-fzc16?fontsize=14&hidenavigation=1&theme=dark"
     style="height:500px; border:0; border-radius: 4px; overflow:hidden;"
     title="inspiring-poitras-fzc16"
     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr"
     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
     ></iframe>

You'll notice that something still doesn't look so hot with that animation...

<img src="/images/usecollapse-padding-glitch.gif" alt="collapse jankiness" />

This is a problem that I think has no solution. When an element has a fixed height of 0, but still has padding, that padding will still be visible, even with `overflow: hidden`.

<figure><img src="/images/usecollapse-height-padding.png" alt="Collapse element still has height if padding is applied to it" />
<figcaption>Padding artificially expands the element's height. `height: 0; overflow: hidden; padding: 20px`</figcaption>
</figure>

So when the collapse animation ends, we will get that flash.

But at least the animation will end!


DOM measurements, box-sizing, and padding with React Collapsed


Downloading your data off Facebook is super easy, but one thing I noticed is that it doesn't download the photos you're tagged in. I was super let down by this since it's the PRIMARY data I want from the site. In case you don't know, when you download your data from Facebook using the export tool, the only media you get is the media you uploaded. I find this silly, since if you uploaded it, you probably have the original files somewhere else! But not the ones you're tagged in.

Since I was deleting my Facebook account (more on that later), I really wanted to have my own copy of the photos I was tagged in. There's no easy "Download" button to click, unfortunately, but that doesn't mean it isn't possible, especially if you get crafty.

## Get all the photos of you on one page

To do this, I largely followed [this guide](https://gnmerritt.net/deletefacebook/2018/04/03/fb-photos-of-me/), but I found that it wasn't always clear (misses some of the helpful tips in the comments). This post recommends using the link [https://www.facebook.com/search/YOUR-ID-NUM-HERE/photos-of/intersect](https://www.facebook.com/search/YOUR_ID_NUM_HERE/photos-of/intersect) to see all the photos you're tagged in, and that's what I used. (There might be another page to get these photos, but I'm not sure.)

As you see, you'll need to get your unique Facebook ID number:

1.  Go to your [profile page](https://www.facebook.com/me).
2.  Find the browser option `View Source` to get a long page of the code that makes up the page. On a Mac, you can hit `Option + Cmd + U`.
3.  Press `Ctrl + F` (Windows) or `Cmd + F` (Mac) and type **fb://**. The number following this is your Facebook ID, and you can use that in the URL above.

Once you hit that URL, you should see a page that has all of the photos you're tagged in!

_Make sure you continue scrolling until all of the photos are loaded on the page._

## Grab the direct URL to each photo

Now that every photo is loaded, scroll back to the top and click on the first photo in the grid, which will pop-up the image spotlight. While the image is still open, open the browser console in `Developer Tools`. You can do this on the Mac by hitting `Option + Cmd + I`. That will open a side pane in your window. Click on the `Console` tab.

Now, you might get a big red warning about running strange JavaScript in the console. Don't worry, nothing below will do anything malicious, and in fact, I'll do my best to explain what each line does. Besides, I'm advocating to get off Facebook here 😝.

Alright, now for the fun part! Copy and paste the code below into the Console, and hit Enter.

```js
let interval;
const photos = [];
interval = setInterval(() => {
  photos.push(
    document.querySelector('._2-sx').firstElementChild.getAttribute('src')
  );
  document.querySelector('a.next').click();
}, 3000);
```

What does this do? It creates a loop that will collect the direct URL for each image, then will progress to the next image, collect that URL, and so on. It spends 3 seconds on each photo, since any less time seems to cause the loop to stall and break.

Now, this isn't perfect: sometimes it will get stuck on a photo, which I think is due to the fact that it can't find the "next arrow" to click or something. When that happens, stop the loop by entering this into the console:

```js
clearInterval(interval);
```

Then close out of the current image you're on, and open the image _following_ the one the loop got stuck on. Once there, copy and paste the below into the console, and hit Enter again:

```js
interval = setInterval(() => {
  photos.push(
    document.querySelector('._2-sx').firstElementChild.getAttribute('src')
  );
  document.querySelector('a.next').click();
}, 3000);
```

This just restarts the loop! And hopefully it will continue trucking on. You might find you have to restart the loop a couple times (at least I did).

As this runs, you won't see anything happen other than the spotlight progressing from image to image. But that's okay! In the background, each URL is being collected into an array, which in this case is basically a collection or list of the URLs, which we'll use to export all of these URLs to download.

## Once the loop stops

Once the loops stops, type the word `photos` into the console, and hit Enter. If everything went okay, you'll get a long result of URLs! We'll use these URLs to quickly download each image. To get them out of the console easily, run the below in the Console, which will spit out each URL onto its own line:

```js
const uniquePhotos = [...new Set(photos)];
uniquePhotos.forEach(photo => console.log(photo));
```

The above just filters the array down to only the unique URLs (when the loop got stuck above, it probably continually collected the same URL over and over again), then just spits out each URL on a new line. Now copy and paste the result into a new `.txt` file.

Almost there! Now that we have the link to every file, we'll run a script to download them all onto your local drive.

## Download the files!

At this point, you should have a `.txt` file with the direct link to every photo you're tagged in. Open the Terminal application.

```bash
# Go to your Pictures folder
cd ~/Pictures
# Make a new folder for your FB photos
mkdir fb-photos
# Go into the new folder
cd fb-photos
# ...And download! Place the path to your file inside the brackets below
cat <path to your file here> | sed -E 's/VM[[:digit:]]+:[[:digit:]]+ //' | xargs -n1 -P4 wget
```

Eh, voila! You should see the `fb-photos` directory fill up with files. If you get an error like `xargs: wget: No such file or directory`, then enter `brew install wget`, and try again. If You don't have Homebrew installed, then you'll need to install that first.

All of the photos might not be recognized by the operating system as a photo: to fix this, you can rename each file individually. Or, you can enter the following into the terminal:

```bash
# Install the rename utility
brew install rename
# Rename the files to look like photos!
rename 's/\?_nc_cat.*//g' *
```

That's it! Facebook doesn't keep a super high resolution for the photos unfortunately, but this should yield the same results as downloading each photo individually.

---

## Why am I doing this?

I deleted my Facebook account! I've been off Facebook (via deactivation only) since sometime last summer (~7 months), and in light of the recent Facebook privacy scandals, I just wanted off. In the time that I've been off, I haven't missed it one bit. The only downside is that I no longer get Facebook event invites, but if they are important enough, my friends will tell me!


Download Photos of You from Facebook


Last month I killed my YouTube addiction. Maybe addiction is too strong a word, but I had a nasty habit of falling into the related videos rabbit hole. There's been more instances of me re-watching (RE-WATCHING) talk show interviews (TALK SHOW) for an hour or hours more than I intended to. YouTube is great, and there's a number of channels I happily follow, but I don't like how YouTube makes it so easy to fall victim to unintended binges.

This phenomenon isn't rare. YouTube makes skipping from video to video easy and enticing to keep the viewer on the platform, and ultimately, watch more ads. Every video provides a custom list of “related videos”, which is a mix of suggestions based on the current video and other somewhat related videos that YouTube can guess you might click on based on your viewing activity. But that’s not all: the Home tab is filled with videos you're probably interested in, and just like any social network, it’s one that I found myself aimlessly scrolling through while bored or while looking to tune out.

My problem with binging on YouTube is that it doesn't feel like the pleasant distraction I’m looking for. I'm happy to catch up on my favorite channels. But it's so easy to click on a related video. YouTube watching evolves into a continuous test of willpower.

I've removed many addicting social media platforms from my life (bye, Facebook), but I didn’t want to cut out YouTube altogether. But I also knew that relying on my own self-control was a fruitless task. It would be like fighting against biology.

So I got creative. I'll explain how I extracted my video feed out of YouTube's addictively curated experience and enforced some healthy limits on my time inside the app.

### From YouTube to RSS

One way I would get sucked into YouTube binges is by opening the YouTube app itself to check the feed. This would inevitably lead to scrolling through the Home tab, full of videos curated to get me to click, which was no good. I had to get my feed out of the app.

Hmm, I needed a **R**eally **S**imple way to **S**yndicate my feed... oh, yeah, that's what RSS is for!

I still use RSS for following a few blogs, so it made a lot of sense to bring my YouTube subscriptions there. You might think this would be manual and tedious task. Fortunately this isn't the case. YouTube allows you to [export your subscription feed](https://www.youtube.com/subscription_manager) to an OPML file, which conveniently enough, is the precise format that RSS expects!

I use [Inoreader](https://www.inoreader.com/) to manage my RSS feeds, and the app makes it easy to import and OPML file. Inoreader created a folder with all of my YouTube subscriptions. One nice thing about RSS managers is that you can organize feeds into folders, unlike YouTube. I follow a lot of Tech channels, so it's nice to give them their own folder.

Each new video becomes a new item in the feed, which shows a link to the video and text of the description. This situation is perfect for me: I can read the description to check if the video is actually worth watching before it plays, something that isn’t really possible on the app itself.

### Killing the curated feed

Even though I copied over my feed to RSS, this wouldn’t stop me from seeing the Home tab or related videos. So something had to happen to the YouTube app itself. But I still needed something to watch the YouTube videos on. It’s possible to watch the YouTube videos without the app, but then you lose out on some features that make watching a good experience, like picture-in-picture and background playback, among others.

The YouTube app doesn't allow you to hide the Home or Trending video feeds, but signing out of the app seemed like a pretty effective way to make those videos less interesting to me.

At this point I opted to install [YouTube Vanced](https://www.xda-developers.com/youtube-vanced-apk/), a modified APK of the YouTube app. The modifications add a number of features, like removing ads, and AMOLED friendly black theme, and more. You can't sign in without some extra work, either. I won’t dive into all of the features of it here, but it’s worth investigating if you have an Android phone! At this point, I disabled the stock YouTube app altogether.

Now, the Home tab and the suggested videos are no longer connected to my account, so the app doesn’t have my long viewing history to predict what I would click on. And to make sure the app wouldn’t start developing a new log of my favorite videos, I enabled the recently released incognito modes, which **prevents the app from keeping a record of both my searches and watching history.** With these enabled, I’m presented a blissful list of clickbait and viral videos I could care less about!

Moving the subscriptions to YouTube and then making the app less enticing put a good left and right hook on my app addiction. All was left was the final jab:

### Setting time limits

To prevent my watching sessions from going off the rails, I wanted to prevent myself from spending too much time in the app. Thanks to the recently released version of Android, my phone's OS offers an easy way to do this with a new feature: Digital Wellbeing. Android Pie's new suite of health focused features offers the ability to put time limits on apps. So now I can't spend more than 30-45min a day on the app.

### How's it working?

It's been a month or two that I've been working with this system, and it's been perfect. I'm happy to report that I can't remember the last Conan O'Brien interview I've watched. (Sorry, Conan.)

Obviously just deleting the app is the best way to stay off the platform. But for someone like me who wants to continue to use the platform, this has been a good system for me.


Creating a YouTube Walled Garden


Last week I rebuilt this site on [Jekyll](http://jekyllrb.com), and it’s freaking awesome.

I’ve heard the name Jekyll tossed around on the interwebs for a while now, but I never completely understood how it worked. When I pulled up their homepage, I immediately closed the page with just a hint that I would have to use Terminal.

But the truth is, Jekyll isn’t all that complicated, once you break it down into its parts. It took me a whole day to figure it out, port over my css and html, and configure it for live deployment. But that was because I had about 10 tabs open each telling me what to do.

So for all you non-programmers interested in Jekyll, this is for you.

**But first!** I want to reiterate that I’m no programmer. I’m only somewhat familiar with Javascript and PHP. I can’t tell you how the engine behind Jekyll works. But, I can get you up in running in laymen’s terms.

[Here we go!](http://youtu.be/k900hqBNc14)

## What we’re doing

Okay, so there’s many ways to build a Jekyll website. This process will all depend on where you want to host your site and how you like to work with your stylesheets. So to clarify, here’s what I’m going to explain:

1.  How to install Jekyll to a local directory
2.  How to incorporate [Compass](http://compass-style.org) and [SASS](http://sass-lang.com) into the workflow
3.  Setting up [Github Pages](http://github.com) hosting
4.  Configuring [Github for Mac](https://mac.github.com) to easily deploy your local repository.
5.  Setting up [Amazon S3](http://s3.amazonaws.com) and Cloudfront for a quick and dirty CDN.

Whew! Okay, now we can start.

## What you need to know first

Let’s first define Jekyll in it’s simplest terms: **Jekyll is “a simple, blog aware, static site generator.”**

If you’re a casual designer/web coder like me, you’re somewhat familiar with this generation concept. In Wordpress, for example, themes include a `header.php`, `index.php`, and a `footer.php`. When you visit your webpage, Wordpress then merges all these files together, the PHP generating HTML that is spit out to your browser.

Jekyll works in a similar way. _Except there’s no PHP._ Instead of calling the header with something like `<?php get_header(); ?>`, we will use Liquid tags, which look like this: `{ % include header.html % }`.

So now we understand two portions of the Jekyll directory. We have a `_layouts` folder that holds are page templates (i.e., posts, pages, homepage, and more). We also have an `_includes` folder for modules we use across every page, like the HTML head, header, and footer.

We also have a `_posts` folder for our blog posts, a `_sass` folder for our not-yet-synthesized SCSS files, and a `css` folder for our synthesized CSS files.

**HOLD!** If you’re not already familiar with the SASS language, I highly suggest you read through their website. It’s pretty easy to pickup, and it makes organizing your styles _way easier_ than with plain CSS.

We also have a `_config.yml` file which we’ll use later to configure our site’s “settings.” (I use quotations because that’s not _really_ what it’s called, but it’s easier to understand that way.)

And finally, there’s a `_site` folder that functions similarly to a `public_html` folder. It’s where Jekyll synthesizes our static site. We’ll leave this folder alone so Jekyll can do it’s thing without us getting in the way.

## Setting up the local directory

Navigate to where you want your Jekyll installation to live, and create a folder for the project. I’ll call it `jekyll` for simplicity’s sake.

Now open up Terminal. It’s time to install Jekyll and some of the tools we need.

### Install Jekyll

In Terminal, enter these lines to create a Jekyll installation:

```bash
$ cd /your/folder/location/jekyll
$ sudo gem install jekyll
$ jekyll new .
```

With this we navigated to the folder that we want to install jekyll into, we installed Jekyll (`sudo` to bypass permission errors), and created a new Jekyll repository in our folder. At this point, Jekyll has built a skeleton directory in the folder. I encourage you to stop at this point and poke around and get familiar with the file structure.

### Installing Compass and Sass

This one took me a while to figure out, because when you install Compass and create a build, it adds its own SASS and stylesheet folders. It took me a little while to figure out how to configure Compass to find my Sass files and then synthesize them into the right folder. So I’ll break it down.

```bash
sudo gem install sass
sudo gem install compass
compass create
```

Okay, so at this point Compass has added three folders: `config.rb`, `sass` (as distinct from `_sass`), and `stylesheets`. It’s now time to decide how you want to organize your assets. I decided to keep the structure from the Jekyll installation, so I deleted `sass` and `stylesheets`. Then open `config.rb` in a text editor.

```yaml
# Change line 6 to:

css_dir = "css"

# Change line 7 to:

sass_dir = "\_sass"
```

Compass should now do its job correctly.

### Now for \_config.yml

In this file, you configure a lot of the major variables for your site, like its URL path, name, description, directory, etc. There’s a bunch of things you can do here, but to get you started, here’s what I use:

```yaml
source: .
destination: ./\_site
includes: ./\_includes

markdown: kramdown
permalink: /:title.html

name: RoginFarrer.com
base_url: ''
url: http://roginfarrer.com
description: 'A blog covering Tech news, design, productivity, health, and the arts by Rogin Farrer.'
root_desc: 'RoginFarrer.com — Tech, Design, and Theater'

exclude: ['README.markdown', 'config.rb']
include: ['.htaccess']

paginate: 10
```

Be sure to change the variables like `name` to your own!

### Local repository complete!

We’ve now got our local directory up and running! When you’re ready to open your site locally, open your terminal to a new window.

```bash
$ cd /your/folder/location/jekyll
$ jekyll serve -w
```

Terminal will start running Jekyll! It will also spit out a local web address like `http://127.0.0.1:4000/` which you can enter to your browser. BAM! There’s your site!

Then to get compass running, type in the usual command:

```
$ compass watch
```

That’s it! You’re good to go with your local repository.

## Setting up GitHub Pages

Conveniently, GitHub offers users one free website that lives at `http://yourusername.github.io. We’re going to set up our new Jekyll repository there.

We’re also going to need GitHub for Mac. If you’re like me, you are probably pretty confused by the interface. No worries! We’ll get through it.

In the upper left, click on the plus to add a new repository. Because we’ve already set up our Jekyll directory, highlight “Add” at the top locate the folder. Then hit ‘Create Repository.’

<figure>
<img class="center" src="http://cdn.roginfarrer.com/Screen-Shot-2014-12-14-00-19-05.png" />
</figure>

Now we have to make our first ‘commit,’ which is essentially our first sync to the GitHub servers. In the ‘Summary’ box, type something like “Initial commit,” and then hit ‘Commit & Sync’ in the upper right.

Another dialogue box comes up, and now we’ll have to name the repository. Enter `yourusername.github.io`. Then hit ‘Push Repository.’

## Success!

And there you are! You’ve got a new Jekyll site published on the web. For more on how to publish posts and pages, I highly recommend you check out [Jekyll’s own documentation](http://jekyllrb.com/docs/). They’re thorough and pretty helpful.

## Why Jekyll?

Now that we’ve got our Jekyll site up and running, let’s talk about the advantages of Jekyll over conventional blogging platforms. While a flat-file structure lacks any kind of user interface or WYSIWYG editor, in return we benefit from the flexibility and ease of development.

### Easy deployment

While Wordpress is a powerful platform in its own right, modifying your theme files is tedious and disorganized. As someone who is constantly making tweaks to my site’s source files, I’d have to jump through many hoops to do so in Wordpress. To try any changes locally, I’d have to make sure I had an updated directory on my computer, make my changes, then use FTP to overwrite the files on my host’s server. If I wanted to make changes directly to my live site, I’d either have to use Wordpress’s clunky file editor or edit through the FTP client.

In this case, I’d have numerous versions of my theme all over my drive, and could never be sure of which version was which.

Jekyll keeps your local directory and the deployed directory in sync. I can use my local directory to easily and quickly make changes, and with a click of a button, it can be synced to my deployed repository. Easy-peasy.

### Flexibility

I can’t tell you how many hours I have lost trying to create custom post types for Wordpress. The task involves creating new templates, adding custom fields to the post editor, and making additions to `functions.php`. Not being a programmer, it was incredibly frustrating.

With Jekyll, custom post types are a breeze. They only require a new template in the `_layouts` folder. The ability to create your own liquid tags in a posts Front Matter make link posts really easy.

Front Matter also makes adding meta content to a page super easy. The way I have my homepage now, I like to publish a truncated post summary with links to the full page. Doing this on Wordpress can involve plugins, adding input fields to the post editor, and other headaches. But with Front Matter, I only need to add another line for `summary`, which i can reference in my `index.html` with a liquid tag, like `{{ page.summary }}`.

## There’s a lot more to like

I’ve only scratched the surface on what Jekyll can do, and I’m still discovering, too. I just set up Pygments as my syntax highlighter, for instance. (If a tutorial for that sounds interesting, let me know.) While Jekyll can look a little scary, it’s really a lot of fun and easy to learn. Hope this helps anyone getting started!


Articles