This repository contains the source code for the Zipkin documentation site
http://zipkin.io. It's the
organization page
for openzipkin
, hosted using
GitHub pages and Jekyll.
This means that everything on the master
branch is immediately and
automatically published.
It uses the static site generator Jekyll. Jekyll is implemented in Ruby and requires Ruby version >= 2.7.
Improvements to the documentation are more than welcome. This section tries to get you up to speed on how to run the site locally and make changes. Just like the documentation, this meta-documentation also welcomes all improvements. If you can, you should use OSX or Linux; Jekyll is not very well supported on Windows.
You may wish to use rbenv
to ensure your Ruby and Bundler versions are
consistent before proceeding.
bundle
jekyll serve
Install Ruby
The official documentation at https://www.ruby-lang.org/en/documentation/installation/ describes the procedure for all major operating systems.
System-level dependencies
Nokogiri, one of the components used by Jekyll, requires some system-level libraries to be in place before installation of Jekyll can begin. Things should generally work out of the box, but keep in mind that if Jekyll installation fails referencing Nokogiri, then the Installing Nokogiri document most likely has what you need.
Clone the repository
git clone https://github.com/openzipkin/openzipkin.github.io.git
Install Jekyll and friends
GitHub quite considerately provides the exact list of packages that are used
to generate the site on GitHub Pages, which means we can use the exact same
packages when running the site locally. This minimizes differences between
what you see locally, and what you'll see in production. Gemfile
defines the packages to be installed using the list provided by GitHub (and
Gemfile.lock
makes sure we all have the same versions
locally). To install these packages:
cd openzipkin.github.io
bundle
Run the site
You're now all set! The following command starts Jekyll, and makes the site available at http://localhost:4000. It'll also pick up any changes you make locally, and regenerate the site, so you can review your changes live without having to restart Jekyll.
bundle exec jekyll serve
Next up is making some changes to the site. To do that, you'll need to have a basic understanding of how the repository is structured.
Content for all the pages lives in the pages
directory. This makes it
very clear where you need to look when making changes to the website text; it's
clearly separated from all the scaffolding around the actual content. The only
exception is the home page, index.md
. It's in the root of the
repository for purely technical reasons (GitHub Pages can only serve the root
document from the root of the repository, and doesn't allow running any Jekyll
plugins).
The rest of the repository contains scaffolding; here's a list to give you a basic idea of what's what:
_data
contains lists of things that are rendered into various
parts of the page. For instance the list of tracers and instrumentation
is defined here in a structured way._includes
contains HTML snippets that are shared by some or
all pages._layouts
contains the basic HTML shared by all pages - and
references snippets in _includes
. At the time of writing, all pages use the
page
layout, and I don't foresee new layouts becoming actively used._sass
contains style-sheets implemented in Sass
.public
contains static content that's directly served to browsers as-is..editorconfig
contains
EditorConfig configuration that makes sure
editors supporting EditorConfig format files in this repository in the same
way (think spaces vs tabs)CNAME
tells GitHub pages that this site should be served at
http://zipkin.io instead of
http://openzipkin.zipkin.io. For details on
how, see
[https://help.github.com/articles/using-a-custom-domain-with-github-pages/](Using
a custom domain with GitHub Pages)Gemfile
and Gemfile.lock
describe the Ruby
packages used for building and serving this site; see the documentation of
Bundler for more details._config.yml
contains configuration options used by Jekyll
when generating the site.There are a few things to keep an eye out for while making changes to the site.
{{ site.github.url }}
at the beginning of URLs. For
example, a link to the Quickstart guide looks like this: {{ site.github.url }}/pages/quickstart
. This is expanded by Jekyll to the correct value based
on where it's running. More documentation is available
hereweight
assigned to each page. By default each page has a
weight of 100 - the default is defined in _config.yml
. This can be
overridden in each page, see index.md
for an example. Pages
with lower weight come first in the list. Pages with the same weight are
sorted however Jekyll sees fit - probably alphabetically.
_includes/sidebar.html
. As we add more
content, we may want to add more structure to the side-bar, and we may
need to re-think this approach. Worst case, we can manage the side-bar
contents manually.Once you've made your changes, you'll want to create a pull-request, so that the
changes can be merged into the master
branch of
openzipkin/openzipkin.github.io
, and so published for the betterment of all.
This section describes the steps for getting there, assuming you've followed the
instructions so far.
Fork this repository
Go to openzipkin/openzipkin.github.io, and click the "Fork" button. Or just click here.
Tell git about your fork
We're going to call your fork origin
, and the original openzipkin
repository upstream
. The following commands tell git
to make the
appropriate changes:
git remote rename origin upstream
git remote add origin git@github.com:$USER/openzipkin.github.io
git fetch upstream
Create a branch, commit and push your changes
git checkout -b my-awesome-changes
git commit -m 'Short, useful description of my changes'
git push
Open a pull-request
Open https://github.com/openzipkin/openzipkin.github.io. You should see a bar above the list of files that says you've recently pushed to your branch, with a green button on the right to open a pull request. Click it; add text to text fields and click buttons as appropriate. See https://help.github.com/articles/using-pull-requests/ for detailed instructions.
When you come back to the project later, you'll want to make sure you have all the recent changes downloaded before making any further changes. Note: the following commands throw away any and all changes you have locally. If that's not desired, refer to the documentation of your git client.
git checkout master
git fetch upstream
git reset --hard upstream/master
git push
You'll also want to make sure you have all the required Ruby packages, at exactly the required versions:
bundle
You are now ready to start a new branch and add more awesome to the documentation.