Google Git
Sign in
apache / incubator-retired-zipkin-website / refs/heads/master
commitaeb7587abba68db58716e1ac16d3f02b92b60c31[log] [tgz]
authorZoltan Nagy <abesto0@gmail.com>Tue Jul 30 09:24:14 2019 +0100
committerZoltan Nagy <abesto0@gmail.com>Tue Jul 30 09:24:14 2019 +0100
treec7520bf5c8740c1b0785634afdca31ff87242e27
parent6cbcf04cbe8fac9be8c73f816d265511f03dd835 [diff]
Right, that is not how Jekyll works
1 file changed
tree: c7520bf5c8740c1b0785634afdca31ff87242e27
  1. .circleci/
  2. _data/
  3. _includes/
  4. _layouts/
  5. _sass/
  6. generate_thrift_v1_docs/
  7. graphs/
  8. pages/
  9. public/
  10. zipkin-api
  11. .editorconfig
  12. .gitignore
  13. .gitmodules
  14. _config.yml
  15. docker-compose.yml
  16. Gemfile
  17. Gemfile.lock
  18. google869265c574186afd.html
  19. index.md
  20. Jenkinsfile
  21. LICENSE
  22. quickstart.sh
  23. README.md
README.md

zipkin-website

This repository contains the source code for the Zipkin web site https://zipkin.apache.org/. It's the organization page for Apache Zipkin (incubating) projects, 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.1.

Contributing

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.

If you've done this kind of thing before

  1. Fork, branch, clone
  2. bundle
  3. jekyll serve
  4. Make changes, commit, push
  5. Open a pull-request

Preparing your environment

  1. Install Ruby

    The official documentation at https://www.ruby-lang.org/en/documentation/installation/ describes the procedure for all major operating systems.

  2. 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.

  3. Clone the repository

     git clone https://github.com/apache/incubator-zipkin-website.git

  4. 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 incubator-zipkin-website
 bundle

  5. 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.

     jekyll serve

Finding your way around the repository

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)
  • 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.

Some finer points

There are a few things to keep an eye out for while making changes to the site.

  • For links to work correctly both locally, on forks, and in production, we need to include {{ 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 here
  • A link to each page appears in the side-bar. The links are ordered based on a custom value weight 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. * This is implemented by custom logic for in _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.

Creating a pull-request

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 apache/incubator-zipkin-website, and so published for the betterment of all. This section describes the steps for getting there, assuming you've followed the instructions so far.

  1. Fork this repository

    Go to apache/incubator-zipkin-website, and click the “Fork” button. Or just click here.

  2. Tell git about your fork

    We're going to call your fork origin, and the original apache 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/incubator-zipkin-website
 git fetch upstream

  3. 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

  4. Open a pull-request

    Open https://github.com/apache/incubator-zipkin-website. 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.

Pulling changes

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.