Skip to content

README.md

Latest commit

 

History

History
273 lines (186 loc) · 10.6 KB

README.md

File metadata and controls

273 lines (186 loc) · 10.6 KB
Raw

The Last Pickle Website

Note: Changes to the master branch in this repo are automatically reflected on the live site..

See the Wiki for workflow and other information.

Contents

  1. Intro

    1. Jekyll
    2. Gulp

  2. Docker local setup

    1. Install docker
    2. Start website container
    3. Stop website container

  3. Manual local setup

    1. Install required tools

      1. Install Yarn/Node
      2. Intall Bundler

    2. Install Dependancies

      1. Install Gems
      2. Install Node modules

    3. Run website locally

  4. Redirecting Urls

  5. The _data folder

    1. assets.json
    2. staff.yml

  6. Questions

Intro

Github pages doesn't allow for any jekyll plugins; and because this site was built by a bunch of frontend nerds it needed to use front-end automation tools and workflows (sass, auto-prefix, etc.) So we've taken the heavy lifting away form github and put it in the capable hands of Gulp.

This process has two parts. The first one is the Jekyll’s _config.yml configuration and the creation of a new folder we are going to have our development files, and our gulpfile.js configuration/setup.

Part 1: Jekyll

The ./_config.yml file contains the following exclude statement which prevents files/directories from the conversion. These exclusions are relative to the site’s source directory and cannot be outside the source directory.

exclude:
  ["_dev","gulpfile.js","node_modules","package.json","npm-shrinkwrap.json"]

The _dev folder is where we keep our sass and js source files which we don’t want to be visible to the website.

Part 2: Gulp

Gulp is a node package what we're going to use to compile our assets files (see the ./_dev folder); and also serve jekyll for local development/testing.

Docker local setup

A docker container exists which contains the tooling required to build and preview the website on your local machine. Using the docker container is much quicker and easier than attempting to set up your local machine to run the site.

Install docker

Simply navigate your browser to the Docker for Mac download page and download the Mac installer Dockedr.dmg file. Follow the installation steps on the page to set up Docker on your local machine.

Start website container

From a command terminal of your choice, run the following command to build and start the website container. If this is the first time running the command, it will take several minutes to start the container. This is because the container needs to be built first and a few modules need to be downloaded to your local checkout. The next time you run the command the container start time will be quicker.

$ docker-compose build website-builder && docker-compose up website-builder

If you want the container to include blog posts being drafted (in the _drafts folder) then run the following command instead.

$ docker-compose build website-builder && docker-compose up website-builder-drafts

When the container starts you will see the following output.

    Starting Jekyll: jekyll serve  --host 0.0.0.0
 ------------------------------------------------
       Site Address: http://127.0.0.1:4000/
 ------------------------------------------------
 Configuration file: /tlp-website/_config.yml
             Source: /tlp-website
        Destination: /tlp-website/_site
  Incremental build: disabled. Enable with --incremental
       Generating...
      Build Warning: Layout 'nil' requested in atom.xml does not exist.
                     done in ... seconds.
  Auto-regeneration: enabled for '/tlp-website'
 Configuration file: /tlp-website/_config.yml
     Server address: http://0.0.0.0:4000/
   Server running... press ctrl-c to stop.

Once you see the Server running... message at the bottom you will be able to preview the site in a browser at the site address: http://127.0.0.1:4000/

Stop website container

Once you're done you can hit <control>+c to stop the container. You then must run the following command to clean up the resources used by the container, otherwise you may be unable to start the container next time.

$ docker-compose down

Manual local setup

In the bad old days before we had the docker container, you had to set up your machine to run the site locally. The steps have been left here for historical purposes, so we know what is required to render the site.

If you have copious amounts of spare time and want to take the hard road, go ahead and attempt to set up the tools so you can run site on your local. The simplicity of the instructions is misleading and you will quickly find out it is a complex tedious task in finding which versions of the tools work together. To save tearing your hair tyring to get things running on your local, we recommend you run the site using docker.

Install required tools

Step one: Install Yarn/Node

Ensure you have Node and Yarn installed. If you're on a Mac you're likely going to be tempted to use Homebrew to install Node. DON'T. Just get it from the official site, you'll save youself a lot of headaches. If you're on Linux then you know what you're doing anyway.

Install Yarn. This is replacement for NPM—still uses node modules and package.json.

Step two: Install Bundler

Ensure you have Bundler installed. This will help install all the local Ruby deps to get Jekyll working locally.

Install Dependancies

Step one: Install Gems

From the site's root run bundle install which will install the Ruby dependancies in the Gemfile in the root of the site.

Step two: Install Node modules

From the site's root run yarn which will install all the dependancies in the package.json file in the root of the site.

Run website locally

From the site's root run:

jekyll serve

The old advice is below, this is not what GitHub will do when we merge to master and it can result in the JS and CSS not being built. Keeping incase it is import:

From the site's root run bundle exec gulp. This will compile the Sass and JS and start the jekyll service. It will also watch the _dev/src folder for any Sass or Js changes. Once you're done you can hit <control>+c to stop the gulp process.

Redirecting URLs

The object of this is to allow an author to specify multiple URLs for a page or post, such that the alternative URLs redirect to the new Jekyll URL.

To use it, simply add the array to the YAML front-matter of your page or post:

title: My amazing post
redirect_from:
  - /post/123456789/
  - /post/123456789/my-amazing-post/

Redirects including a trailing slash will generate a corresponding subdirectory containing an index.html, while redirects without a trailing slash will generate a corresponding filename without an extension, and without a subdirectory.

For example...

redirect_from:
  - /post/123456789/my-amazing-post

...will generate the following page in the destination:

/post/123456789/my-amazing-post

While...

redirect_from:
  - /post/123456789/my-amazing-post/

...will generate the following page in the destination:

/post/123456789/my-amazing-post/index.html

These pages will contain an HTTP-REFRESH meta tag which redirect to your URL.

You can also specify just one url like this:

title: My other awesome post
redirect_from: /post/123456798/

For more information visit the plugin page.

The _data folder

assets.json

Gulp will generate a file: _data/assets.json. This file contains a JSON object with asset includes (js and CSS). This data is then used in the _includes/pre.html and _includes/post.html files to include cache-busted assets. Prety nifty.

staff.yml

This is essentially your staff database. All staff information is stored in here. If a staff member leaves change the active item to false. For example:

"Aaron Morton":
  active: true
  name: "Aaron Morton"
  role: "CEO"
  bio: !xml >
    <p>Aaron Morton has been working with software for over 17 years. In 2011 he left a position at the VFX company Weta Digital in Wellington to pursue his interests in Cassandra. Since then he's been helping clients around the world get the best out of Cassandra. While contributing to the project and the community through involvement in the user list and IRC channels, and code contributions.</p>
    <p>At Weta Digital he piloted the use of Cassandra to provide database services that could stand up to the render farm of 35,000 cores. The key concern at Weta was how to design a scalable persistence layer they could maintain availability in the face of hardware failure and errant clients.</p>
    <p>Prior to Weta he worked on large E-Commerce projects in London and created a Content Management System for the National BBC Radio stations.</p>
    <p>Aaron frequently <a href="/speaking">speaks</a> at meetups and conferences such as the DataStax Cassandra Summits and the Apache Software Foundation's ApacheCon. He runs the <a href="http://www.meetup.com/Data-Driven-Wellington/">Data Driven Wellington</a> meetup group to encourage local engineers to explore new technology. Aaron is also a committer for Apache Cassandra and was voted a DataStax MVP for Apache Cassandra by the community.</p>
  github: aaronmorton
  twitter: aaronmorton
  linkedin: http://www.linkedin.com/in/aaronmortonnz
  email: aaron@thelastpickle.com
  avatar_tn: aaron-morton-tn.jpg # post.author | slugify
  avatar: aaron-morton.jpg # post.author | slugify

So when you have a new staff member ensure their complete information is entered into this yaml file. Note that the bio section is in HTML.

Questions

If you're having problems or have any questions that Stackoverflow can't help you with you could check here for more info on the frontend automation processes. And if you're still having trouble you can email Darren at The Fold.