Spinnaker Website

To Develop the Site

Clone the repo
Install jekyll: gem install jekyll
Install required node modules: npm install.
Install gulp globally with npm install -g gulp.
Run gulp serve and wait for the build to finish and pop up a page

Then change any files you like and it will notify you, autorebuild less/html/md, and refresh as necessary.

When you're ready to push, just commit everything and push to gh-pages as usual. If you're worried, you can also do a manual rebuild before pushing with gulp build-all.

Site Layout

For the most part, the layout of the site content can be done any way you like. All items on the navigation that reference a page id (currently all except API docs) will always link to the correct url, regardless of that page's place in the folder structure.

Homepage

The homepage content is split into a number of markdown files to make it easy to edit despite jekyll's template limitations.

_includes/tagline.txt contains the (plain) text displayed underneath the spinnaker logo
_includes/homepage-key-feature-1 through 3 contain, form left to right, the three key feature snippets displayed right under the hero banner (the large black banner)
_includes/homepage.md contains the main content (after the 3 key features widget) for the rest of the homepage

Other Pages

API Docs

The API docs are entirely autogenerated and are placed in the doc folder at the root of the repo. They are automatically built into the site since they are based on a custom JSDoc template. The doc folder should not need to be altered in this repo in any way.

New Page Creation

There are currently 3 layout templates that new pages generally should be based on:

plain-page: As seen in the getting started pages, these are just a plain markdown file rendered at an easy to read width within the main site framework.
toc-page: Similar to a plain page, but includes a table of contents on the right and will track the user's location as they scroll through the document. Note that you must include the following at the top of your markdown file for the page to generate the table of contents, due to limitations in jekyll's markdown renderer in github pages:
```
* Table of contents. This line is required to start the list.
{:toc}
```
Please note that the automatic location tracking tends to skip a section if it's extremely short, because there's almost no scroll position where the section is considered current. This also happens if it's close to the bottom and either it or the bottom section is very short.
video-page: give the page a youtube_id entry in the front matter and it will embed that video in the page above any content you add to the markdown document itself.

New pages can be placed anywhere, though the directory structure determines their url, so it's probably best to group related pages together in a directory.

To make a new page, just

Create a new yourpagename.md file in an appropriate location
Add the recomended front matter (listed below), 3. Add it to the navigation in _data/navigation.yml, likely by its id (see below)
Add any content you want. You can break the page into pieces and use includes and all the other gh-pages supported jekyll features as usual.

Front Matter for New Pages

The following front matter is recommended on every new page:

---
layout: Required. Likely one of `plain-page`, `toc-page`, or `video-page`.
id: some_unique_id_for_this_page_to_reference_in_the_navigation_yml_file
title: A custom page title (plain text). Will be automatically prepended with the sitewide title prefix. Defaults to the value in _config.yml if left empty for a page. For safety, I recommend enclosing it in quotes.
description: A custom description of this page, in plain text, preferably 1-2 sentences. Will be used in social sharing widgets and gets picked up by search engines. Defaults to the value specified in _config.yml if left empty for a page. For safety, I recommend enclosing it in quotes.

---

Page Crosslink Helper

There's a simple link to page id helper you can use like this:

{% include link.to id="router" text="Spinnaker Router" %}

Where you can replace the id with any page's id, or even a variable (id=site.data.my_favorite_page_id), and it will always keep the correct url to that page, even if it's moved or renamed.

Code blocks

You can use triple tildes (~~~) with the language specified and your code will be automatically syntax highlighted! The following general language types are available, and have distinct highlighting:

default: specify any language other than the ones below (e.g. js, css, html, etc.).
shell/sh/bash: terminal colors (green on black).
output: a dark variant of the default highlighting theme so you can follow a user input examle with the server's response and have a contrasting but familiar theme. It attemps to autodetect language via the code prettify library, so you don't need to specify one.

Quick Vertical Spacer

Since markdown lets you embed html, you can place the following html to create a one-off vertical gap between some text content:

<div class="row row-gap-small"></div>

Where row-gap-small can be any of: row-gap-small, row-gap-medium, row-gap-large, row-gap-huge, and create 15px, 30px, 45px, and 60px of space, respectively.

Configuring the Navigation

Please see the documented code in _data/navigation.yml to configure the main top nav.

The navigation supports two levels (main and dropdown) currently. All ordering is based on the ordering in the _data/navigation.yml file itself.

TODO:

make classes more obvious in API docs
footer copyright

andyfleming/spinnaker.github.io