Background

While creating a bibliography using nikola I found about nikola path handlers. It allows you to make reference to other posts without needing the full address (e.g. http://necromuralist.github.io/pages/nikola-inter-site-links).

Instead you can use the special link:// protocol and nikola will resolve it for you. It uses the form:

link://<kind>/<name>/

There is (of course) another form that lets you doc it using the :doc: restructured text directive. This form is more succinct, and is what I'll probably stick with in the future. I originally went with the link version because I thought it would work with other markup languages, but it didn't (or at least not with org-mode).

Post-Paths

In this case I'm trying to link to another post so the link kind is post_path, which will resolve to either posts or pages. Because it can be either one, you need to extend the path to this form:

link://post_path/posts/<post-slug>/

`link <link://post_path/posts/pruning-large-files-from-git-with-bfg/>`__

Doc Role

This is a restructured-text role that nikola supports to make it easier to install links. The previous example using this style would be done like this:

:doc:`link <pruning-large-files-from-git-with-bfg>`

Which creates this link.

Conclusion

The doc method seems much easier for posts, but the links method covers many other cases and might be useful otherwise. It should be noted that both methods work for pages as well (stories), although the link version will need the path changed. In my case, all the pages are under the stories folder so the link would be change to something like:

`link <link://post_path/stories/story-slug/>`__

1 Background

This is about removinge large files that have been committed to a git repository. Github has a 100 MB file limit, and I'm using Century Link's ADSL (Fiber to the Node) so my upload speeds are much slower than my download speeds, so I'd like to keep large files out of the repository. The problem when working with data is that you can often end up with very large files that accidentally get committed, then need to be removed. Here's two cases I've run into:

• I accidentally committed some large files to a git repository and couldn't push my changes up to github, having exceeded their file-size limit

• I committed a folder that had some large files that were under the limit, but were just taking too long to upload.

I stumbled upon the BFG Repo-Cleaner while looking for a solution and kept these notes so I don't forget what I did.

The instructions on the website are pretty clear, but it assumes that the large files are on a remote repository (I talk about that case here) but in my case my changes were local so I needed to change the first step from cloning the repository to cleaning the git repository (I'll call the repository big_files). In this case I decided to remove anything bigger than 50 MegaBytes.

2 The Commands

For reference, these are all the commands. I'll go over them in the sections that follow. The java -jar line pointing to the BFG jar file will have to match your download file name and location.

cd big_files
git gc
cd ../
java -jar bfg-1.12.7.jar --strip-blobs-bigger-than 50M big_files
cd big_files
git reflog expire --expire=now --all
git gc --prune=now --aggressive

I'll break this down into three parts:

1. Clean the repository

2. Run BFG to remove the file from the git history

3. Clean the repository again

cd big_files
git gc
cd ../

java -jar bfg-1.12.7.jar --strip-blobs-bigger-than 50M big_files

cd big_files
git reflog expire --expire=now --all
git gc --prune=now --aggressive

1 Background

I accidentally committed an 89 MB file to git and pushed it upstream to github. This is within the allowed file-size limit, but when I looked in the file it was filled with the same error message over and over again, so it wasn't useful to keep, anyway. I was just working with small log-files, so any large files indicated an error, anyway, so I decided to clean anything over 50 MB from the repository using BFG. The instructions on the home page mostly work, but didn't exactly work so I'm making some notes here for the next time.

2 The Process

Assuming you've downloaded the BFG jar file, this is what you need to do.

git clone --mirror <remote git address>

The --mirror flag creates a bare repository so it will look a little odd (the top level has the contents of what are normally in the .git folder). When I first tried this I thought I could clone my local copy but when I ran BFG on the clone it said that it couldn't find any large files. As noted in this bug-report the large files would be in the packfile if you clone it from a remote repository, but not necessarily in the local repository, so I had to clone it from github.

Next run the BFG.

java -jar BFG-1.12.15.jar --strip-blobs-bigger-than 50M <path to cloned mirror>

Now you have to change into the cloned repository and execute some commands to update it.

git reflog expire --expire-now --all
git gc --prune=now --aggressive

Now push it back to github.

git push

At this point the original local copy of the repository will still have the large file(s) in the history so if you just do a git pull it will think you are ahead of the remote, so you have to remove your original local repository and re-clone the remote.

rm -r <original local repository>
git clone <remote repository>

One thing that tripped me up a little was that I had removed the master branch but the BFG re-added it, so it originally looked like I had lost some changes. Once I changed back into my working branch everything was as I had expected.

Background

I'm creating an annotated bibliography using nikola, and added links to the PDFs online so I could download them again if needed. I called them all PDF Link but when I built the web-page I found that there were some restructured text errors in it that looked like this.

This stack overflow answer pointed me to anonymous links (which I had never heard of) to fix the problem.

Named and Anonymous Links

The form for hyperlinks that I learned used one underscore:

`some link<http://some-target.com>`_

This creates both a hyperlink in the document and a target that other hyperlinks can use. In this case, you can create a link back to this hyperlink somewhere else in the document using this syntax:

`some link`_

Unfortunately this means that the text used for the link has to be unique. In order to make multiple hyperlinks with the same text in them, use two underscores:

`some link <http://some-target.com>`__

This fixed it for me. Of course now the internal targets are gone as well, but they wouldn't have worked anyway.

See the Restructured Text Hyperlink Documentatation for more details.

Overview

1. Install the bootswatch 3 nikola theme (if you haven't already) (nikola install_theme bootstrap3).

2. Install the journal bootswatch theme (nikola bootswatch_theme -s journal).

3. Get the base template (nikola theme -c base.tmpl).

4. In base.tmpl, change navbar-inverse to navbar-default.

5. Change the anchor color in bootstrap.css to something less creamsicle (and do whatever other CSS adjustments you need to do).

6. If you need to, minify the CSS (cleancss -o bootstrap.min.css bootstrap.css).

7. Build the posts (nikola build).

8. Admire the fruits of your (well, other people's) labor.

Installing the theme

nikola install_theme bootstrap3

nikola bootswatch_theme -s journal

nikola build

Updating the Template

On re-loading the page I found that it mostly worked, but for some reason it looked more orange than I expected. It turns out that the nikola developer decided that navbar-inverse should be the default style for the navbar (instead of navbar-default) and the section headers are hyperlinks, which in the Journal theme are orange (by orange I really mean something closer to a creamsicle). Following the instructions in this bug report (which says that it isn't a bug, it's a feature) I copied the base template from the nikola installation (in site-packages) into the site using a built-in nikola command.

nikola theme -c base.tmpl

This command creates a file (themes/custom/templates/base.tmpl) which you can edit to override the built-in base template. I opened it up and changed the navbar-inverse CSS class to navbar-default.

<nav class="navbar navbar-default navbar-static-top">

The I re-built the nikola posts, and reloaded the page and there it was, the white navbar I wanted.

Updating the CSS

@import url("https://fonts.googleapis.com/css?family=Goudy+Bookletter+1911:400,700");

body {
  font-family: "Goudy Bookletter 1911", "EB Garamond",  Georgia, "Times New Roman", Times, serif;
  font-size: 3em;
  line-height: 1.42857143;
  color: #777777;
  background-color: #ffffff;
}

.navbar-header .navbar-brand #blog-title {
    padding-top: 19.5px;
}

npm install clean-css-cli -g
cd themes/custom_theme/assets/css/
cleancss -o bootstrap.min.css bootstrap.css

Deploy

This isn't really to do with theme-changing, but for completeness, I'll mention it anyway.

nikola github_deploy

Summary

Changing the bootswatch theme isn't as hard as it seemed, in retrospect. You just have to know the basic commands (nikola install_theme bootstrap3, nikola bootswatch_theme -s journal), know that the inverse navbar is the default (and how to change it - nikola theme -c base.tmpl), know how to update the CSS to whatever you want (by editing bootstrap.css and minifying it if necessary), and understand that you have to build the site to see the changes on the development server (nikola build).