All pull requests should be made in the new github.com/spinnaker/spinnaker.io repo.
--------------------------------- ARCHIVED ------------------------------
The easiest way to preview and test your changes to Spinnaker.io is to run your branch locally with Docker, via the dockerfile included in the root directory.
In the root directory of your fork, run:
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
Navigate to http://localhost:4000 to see your locally generated page.
Alternatively, set up Jekyll and use it to run the site locally. It runs on Ruby, and running multiple versions of Ruby on a single system can create challenges. These instructions install rbenv
, which makes it easy to install and switch to a specific Ruby version.
gcloud compute instances create jekyll --image-project=ubuntu-os-cloud --image-family=ubuntu-1804-lts --machine-type=n1-standard-1
gcloud compute ssh jekyll --ssh-flag="-L 4000:localhost:4000"
rbenv
and ruby-build
. Add these to $PATH
:
sudo apt update
sudo apt-get install -y git bzip2 build-essential libssl-dev libreadline-dev zlib1g-dev
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
rbenv install 2.4.1
rbenv global 2.4.1
GITHUB_USER=$USER # or something else here
git clone https://github.com/$GITHUB_USER/spinnaker.github.io.git
bundle
gem
cd spinnaker.github.io
gem install bundler
bundle install
Your system is now ready for local preview of the documentation site.
bundle exec jekyll serve --watch
--incremental
to speed up page generation when working on one page
bundle exec jekyll serve --watch --incremental
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.
gem install s3_website
s3_website cfg create
s3_id
and s3_secret
so that your AWS credentials can be read from ~/.aws/credentials
jekyll build
s3_website push
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:
/
in links.foo/index.md
instead of foo.md
.During local development, see what's actually generated by browsing the
_site
directory.
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.
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.
Keep the "broken window theory" at bay by ensuring all links work with HTML Proofer
Run link checker before committing:
rake test