Syncing forked repos with their upstream (source) repo

I kicked off this morning by synchronizing the nightCasper theme with the parent repo that it's forked from. This is a simple enough procedure achieved by first making sure that you have the upstream repo defined:

git remote -v

If the resulting output only shows origin, then you need to add the requisite upstream repo:

git remote add upstream https://github.com/TryGhost/Casper

Rerunning git remote -v should now show:

Next, you need to fetch the upstream repo branches:

git fetch upstream

The above command results in the creation of a local branch "upstream/master" sourced from the upstream (parent) repo.

We now switch to our repo master with:

git checkout master

And finally, we merge upstream/master into our forked repo master:

git merge upstream/master

N.B.: With nightCasper, because the theme uses yarn/gulp to generate built files, in between "git checkout master" and "git merge upstream/master", I have to launch a session into my development container and run yarn install/yarn dev to make sure that any changes brought in by the merge get compiled appropriately. This is a relatively unique aspect of Casper's build and typically doesn't have to be done.

nightCasper Post Content Improvement

Something I dislike about the Ghost's default Casper theme is how much horizontal space it wastes. Thanks to Ghost's excessive padding (170px on each side!), the post content column (actually a flexbox) is just too narrow and needlessly makes the articles seem long (due to the increased vertical space required):

This has been fixed in nightCasper with the modification of .post-full-content padding from 0 170px 6vw; to 0 100px 6vw, thus reclaiming 140px of horizontal width:

.post-full-content {
    position: relative;
    margin: 0 auto;
    padding: 0 100px 6vw;
    min-height: 230px;
    font-family: Georgia, serif;
    font-size: 2.0rem;
    line-height: 1.6em;
    background: #fff;
}

Prism.js Styling Improvements

Prism.js CSS Overrides

When a language is applied with the current Prism.js, the code block margins get horribly out of whack resulting in the code block being placed practically on top of the next element (red below).

Note that the problem doesn't happen when a language is left unspecified (green).

As usual, this is easily resolved once you identify the CSS selector responsible and add the appropriate margin to match Casper's original styling:

.post-full-content pre[class*=language-]{
    line-height: 1.3em;
    padding: 1em 3em;
    font-size: 1.5rem;
    margin: 1.5em 0px 3em;
}

Prism.js Line Numbers: Don't Show Line Counts for One-Liners

nightCasper utilizes Prism.js's Line Numbers plugin. Unfortunately, with the way this plugin works (which is nonetheless quite clever and worthy of a post by itself), if you specify a language for the code element, you always get a line count. This can actually be seen in the previous screenshot:

This seems rather silly when there's only one line. Who would explicitly reference line #1 in code with only one line? What other line could someone possibly be talking about?

So, yet again, another override is needed and, yet again, jQuery comes to the rescue:

$( document ).ready(function() {
	$(".line-numbers-rows").filter(function() {
		return $(this).children().length == 1;
	}).children().hide();
});

$( document ).ready(function() {... defers the execution of the internal code block until after the document object model (DOM) is complete. Otherwise, we wind up with a race condition and the data that the function inside it needs isn't ready yet (i.e. maybe line-numbers-rows hasn't been added to the appropriate elements yet).

Inside, a filter function is used to check each element with "line-numbers-rows" has only one child. If it is, it hides those children. (The children of line-numbers-rows is actually the spans generated by Prism.js's line number plugin. The best way to figure this sort of thing out is to simply examine the output of the code.)

In an ideal world, the best place to handle this would not be in jQuery, but rather to fix the CSS itself. However, at this point, I have no interest in maintaining yet another fork, so the jQuery will suffice for now. There are also drawbacks to fixing the Prism.js CSS that handles the line count: modification of the Prism.js CSS would mean that I would lose the CDN associated with the Prism.js that has edge servers all over the world. Not exactly a trivial loss (though I could also set up a CDN for the forked repo, but then we're back at how I don't want to maintain yet another fork).

Have a good week everyone!