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 --incrementalNavigate 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.
- (Optional) Create and run from a fresh VM instance, and forward the Jekyll default port (4000):
gcloud compute instances create jekyll --image-project=ubuntu-os-cloud --image-family=ubuntu-1804-lts --machine-type=n1-standard-1gcloud compute ssh jekyll --ssh-flag="-L 4000:localhost:4000"
- Install
rbenvandruby-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 - Install and use ruby 2.4.1
rbenv install 2.4.1 rbenv global 2.4.1 - Fork and clone your forked repo:
GITHUB_USER=$USER # or something else here git clone https://github.com/$GITHUB_USER/spinnaker.github.io.git - Install
bundlegemcd spinnaker.github.io gem install bundler bundle install
Your system is now ready for local preview of the documentation site.
- Start Jekyll server
bundle exec jekyll serve --watch
- (Optional): Add
--incrementalto speed up page generation when working on one pagebundle exec jekyll serve --watch --incremental
- Navigate to http://localhost:4000 to see your locally generated page.
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.
- Enable static website hosting on a S3 Bucket
gem install s3_websites3_website cfg create- Delete
s3_idands3_secretso that your AWS credentials can be read from~/.aws/credentials - Modify url property at _config.yml to use the CNAME that you want to use
jekyll builds3_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:
- It is more efficient to include the trailing
/in links. - If you anticipate including resources like images or subpages, create
foo/index.mdinstead offoo.md.
During local development, see what's actually generated by browsing the
_sitedirectory.
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
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent