Publish Website

Publishing vitess.io Web Site

Overview

Our website vitess.io are static HTML pages which are generated by Jekyll from Markdown files located in the doc/ directory.

The generated files will be put in the docs/ directory (note the extra s). GitHub serves the website from this directory off the master branch.

TL;DR

To preview site locally

  • Run:

    ./vitess.io/publish-site.sh
    
  • Site should be live at localhost:4000

To publish the site

  • Make sure your doc and site changes have been committed to your branch and your branch is clean.
  • Run:

    ./vitess.io/publish-site.sh
    
  • Sanity check the diffs.

    • git diff HEAD~
  • Create a pull request for your branch and let somebody review it.

  • Merge the pull request into the master branch.

Details

Directory Structure

We have three main directories:

  • doc/ - original content
  • docs/ - generated website actually served at http://vitess.io/
  • vitess.io/ - all relevant files for the website e.g.
    • Jekyll configuration
    • images e.g. our logo
    • CSS
    • Navigation menu
    • boiler plate markdown files which include the actual content from the doc/ directory (example)

The boiler plate markdown files have multiple purposes:

Changing Content

To modify our website, you need to:

  • change the underlying Markdown files in the doc/ directory
  • re-generate the static pages (see publish-site.sh above)
  • merge your changes into the master branch e.g. as pull request

Linking pages

Always use the {% link ... %} template tag to link other pages.

Note that you have to refer to the .md file of the page. Example:

[GitHub Workflow page]({% link contributing/github-workflow.md %})

Adding new Pages

If you want to add a new page, you must also:

When you add a new section to the menu, please create a new directory below vitess.io/. For example, the "Contributing" section is served out of vitess.io/contributing/.

The main file in the section should have index.md as its boiler plate counter part. Example: doc/Contributing.md is included by vitess.io/contributing/index.md and therefore served as http://vitess.io/contributing/.

Make sure that you use {% link ... %} to generate the URLs. See existing entries for examples.

Orphaned doc/ Markdown Files

There are several files in doc/ which are currently not visible on http://vitess.io.

Examples:

This is fine and accepted. Users can still view them on GitHub.com.

Note that these files should include images using the full path e.g. in LifeOfAQuery.md:

![](https://raw.githubusercontent.com/youtube/vitess/master/doc/life_of_a_query.png)

Otherwise GitHub cannot find and show the images.

Jekyll Install Instructions

This section describes how to install Jekyll to generate the website.

The Easy Way

  • Install Docker.
  • Run the ./vitess.io/preview-site.sh and ./vitess.io/publish-site.sh commands as shown above.

The Hard Way

  • On Ubuntu, you need a non-root Ruby install so gem packages can be installed correctly.
    • Install rbenv.
    • Close and re-open your shell to complete the installation.
    • Install ruby-build plugin for rbenv.
    • Use rbenv to build a recent version of Ruby.
    • rbenv install 2.2.3
    • You may need to install extra dependencies. The build output should tell you which packages. For example: sudo apt-get install -y libreadline-dev
    • Set the new Ruby as the system-wide default.
      • rbenv global 2.2.3
      • rbenv rehash
  • Install bundler.
    • gem install bundler
  • Install "nodejs" as JavaScript runtime.
    • sudo apt-get install nodejs
    • In Ubuntu, the binary is unfortunately renamed from "node" to "nodejs". We work-around this by creating a "node" symlink on a directory which is early in the PATH list: ln -s /usr/bin/nodejs $HOME/.rbenv/bin/node
  • Add --docker=false to the commands above.