Skip to content
spinnaker documentation site
HTML CSS JavaScript Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
_api_templates
_changelogs
_data
_includes
_layouts
_pages
_sass
assets
community
concepts
downloads/kubernetes
guides
publications
reference
setup
success-stories
.dockerignore
.gitignore
.mergify.yml
.ruby-version
.travis.yml
CNAME
Dockerfile
Gemfile
Gemfile.lock
LICENSE.txt
README.md
Rakefile
_config.yml
banner.js
favicon.ico
index.md
minimal-mistakes-jekyll.gemspec
package.json

README.md

Jekyll Installation

Swap out rbenv below for rvm if you prefer. RVM was giving me installation issues, so I found rbenv - Travis

  1. Create and run from a fresh VM instance:
    1. gcloud compute instances create jekyll --image-project=ubuntu-os-cloud --image-family=ubuntu-1404-lts --machine-type=n1-standard-1
    2. gcloud compute ssh jekyll --ssh-flag="-L 4000:localhost:4000"
  2. Install rbenv and ruby-build. Add these to $PATH:
    1. sudo apt-get install -y git bzip2 build-essential libssl-dev libreadline-dev zlib1g-dev
    2. git clone https://github.com/rbenv/rbenv.git ~/.rbenv
    3. git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
    4. echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
    5. echo 'eval "$(rbenv init -)"' >> ~/.bashrc
    6. . ~/.bashrc
  3. Install and use ruby 2.4.1
    1. rbenv install 2.4.1
    2. rbenv global 2.4.1
  4. Fork and clone your forked repo:
    1. GITHUB_USER=$USER # or something else here
    2. git clone https://github.com/$GITHUB_USER/spinnaker.github.io.git
  5. Install bundle gem
    1. cd spinnaker.github.io
    2. gem install bundle
    3. bundle install

Local Development

  1. Start Jekyll server
    1. bundle exec jekyll serve --watch
  2. (Optional): Add --incremental to speed up page generation when working on one page
    1. bundle exec jekyll serve --watch --incremental
  3. Navigate to http://localhost:4000 to see your locally generated page.

You can do the same within Docker using the included Dockerfile (the volume mount will still allow changes to files to be visible to Jekyll):

docker build --tag spinnaker/spinnaker.github.io-test .
docker run -it --rm --mount "type=bind,source=$(pwd),target=/code" \
    -p 4000:4000 spinnaker/spinnaker.github.io-test --incremental

(Optional) Host the website on Amazon S3

Hosting the documentation website on Amazon S3 allows review from look/feel perspective before a pull request is submitted. This allows peer reviews of a breaking change without needing any technical setup by the reviewer.

  1. Enable static website hosting on a S3 Bucket
  2. gem install s3_website
  3. s3_website cfg create
  4. Delete s3_id and s3_secret so that your AWS credentials can be read from ~/.aws/credentials
  5. Modify url property at _config.yml to use the CNAME that you want to use
  6. jekyll build
  7. s3_website push

Page Generation

A page named foo.md will be transformed to foo/index.html and links to foo will result in an HTTP 301 to foo/. This has two implications:

  1. It is more efficient to include the trailing / in links.
  2. If you anticipate including resources like images or subpages, create foo/index.md instead of foo.md.

During local development, see what's actually generated by browsing the _site directory.

Mermaid

Sequence diagrams can be generated with the mermaid.js library by adding {% include mermaid %} near the bottom of the page. See some of the security docs for an example.

Breadcrumbs

Each page has a breadcrumb trail at the top that is based on the URL structure. You should ensure that there is at least an index.md file within each URL directory, otherwise the links will break.

Link Checker

Keep the "broken window theory" at bay by ensuring all links work with HTML Proofer

Run link checker before committing: rake test

You can’t perform that action at this time.