blewjy / powerpointlabs-website

Jekyll-powered website for PowerPointLabs. Deployed at http://powerpointlabs.info

PowerPointLabs' Website

This is the website and documentation for the PowerPointLabs project.

Contributing To PowerPointLabs-Website

Interested to contribute? Please take a moment to review the guidelines for contributing.

Dev Prerequisites

1. Install SourceTree (recommended), GitHub for Windows, or at least, Git.
2. Install Vagrant and VirtualBox.
3. Install a text editor that supports using spaces for indentation, e.g. Sublime Text 2.
4. Install a modern web browser, e.g. Chrome.

Setup

The website is generated using Jekyll. An easy way to get up and running is to just use Vagrant (which requires VirtualBox).

This README assumes no existing knowledge of how Vagrant (or Jekyll) works. In a nutshell, Vagrant is a nifty wrapper for a virtual machine (the "guest", running Ubuntu 14.04.5 LTS in our case) which can be automatically setup with our project's dependencies, while letting us use our own familiar editors/tools on the "host".

Isn't it overkill to use Vagrant just for a simple Jekyll site? Maybe. It's been tricky to get running on Windows in the past, though, so this is perhaps in a strange way easier.

Fork and clone the source codes from this repo. With Vagrant and VirtualBox installed, cd into the project's root directory and run:

$ vagrant up

This starts up the virtual machine, installs Jekyll, and also installs the site's dependencies. This might take a few minutes to complete.

Development (with local previewing)

After the virtual machine has set up and the vagrant up command completed without errors, you are ready to work on the site through the virtual machine:

$ vagrant ssh
$ cd /pptlabs-website
$ jekyll serve --host 0.0.0.0 --port 4000 --force_polling

vagrant ssh gives us an ssh session on the guest machine. /pptlabs-website is a shared folder which maps to the project root on the host: this lets us modify the website's files in our editor of choice, and still have them accessible within the guest.

The site should now be accessible on localhost:4000 on the host, and can be modified with any changes automatically propagating to the guest (and visible after a quick refresh of the browser).

We need --force_polling since Jekyll's normal method of checking for changes doesn't work with VirtualBox's shared folders. We also need to specify the host or the site will be served on the guest's localhost instead, and won't be accessible from the host.

Building for Deployment

Change the base url in _config.yml to /~pptlabs for the public release or /~pptlabs/dev for the dev release of the website and uncomment the line.

baseurl: /~pptlabs/dev

Nothing special here: jekyll build will output the site's files to _site. rake does two things; inlines JS & CSS and compresses all images in _site.

$ vagrant ssh
$ cd /pptlabs-website
$ jekyll build
$ rake

If want to run the inline task only, do rake inline.

How to...

Add a new Team Member

Adding a new team member to the About Us page is fairly simple: save their picture to img/team, open _data/developers.yml, and add a new object there containing their name, the absolute path to the picture, and an optional URL.

Add a new Shape

Similar to adding team members, add the shape's picture and file to shapes, open _data/shapes.yml, and add a new object containing the shape's details. An optional license (licenseTerms) and submitter (submitter) field can be included as well.

Adding User Guide Sections

There are two steps to add a new User Guide section.

1. Add a new section in the right navigation sidebar.

This is in _data/docs.yml - add a new object containing the title of the new section. The order will affect the sequence of the sections.

2. Add the new section.

We're (ab)using Jekyll's blog generation to do this - create a new Markdown file in _docs/, and add the following fields to its front-matter at the top (using the Spotlight as an example):

---
layout: docs
title: Spotlight
sample: "/samples/spotlight%20sample.pptx"
---

Field	Purpose
layout	This is just kept as "docs"
title	The name of the new section. This is usually the feature being documented.
sample	An optional sample file to be linked to in the section's header.

3. Add new subsections in the right navigation sidebar.

To add new subsections to the right navigation sidebar, add a new a with class="anchor-bookmark" and an id attribute in the subsection's heading just before the text. Using the Shortcuts documentation as an example:

## ![]({{ site.baseurl }}/img/docs/misc-1.png) <a class="anchor-bookmark" id="edit-name"></a> Edit Name

4. Write the doc

Write the document using Google Docs, and share it with project mentor for document review. When document review is passed, this script can be used to generate the Markdown from Google Docs document.

Then use the generated Markdown to construct the web page. Modification of styles and image links may be required.

5. Add new HTML dependencies utilizing inlining/concatenation of JS & CSS

1. Make sure that the dependencies themselves do not depend on some other dynamic dependency (if dynamic dependency, it is advised to link it with external link).
2. Download local copies of the JS/CSS file and store them anywhere in the project directory.
3. Link them in the HTML files as per normal (look at existing dependencies for example).

rake inline will automatically find and replace the script or link tag with the respective file contents.