revbayes.github.io

This is the repository for the RevBayes website.

Setting up this repo locally

The static version of this site is stored on branch master, while the source files are stored on branch source.

First, you should clone the source branch

git clone https://github.com/revbayes/revbayes.github.io

After first cloning this repository, you will be on the source branch. Then, you should clone the master branch into the _site directory.

cd revbayes.github.io
git clone -b master [email protected]:revbayes/revbayes.github.io.git _site

In order to build the site you will need jekyll, see instructions below to install.

Making changes to the site

When making changes to the site:

1. Start from the lastest version of the source branch with git checkout source ; git pull.
2. Create a new branch for your changes with git checkout -b <mybranchname>.
3. Commit your changes to the branch.
4. Push the changes to github using git push --set-upstream origin <mybranchname>.
5. Open a pull request (PR) for the branch on github at https://github.com/revbayes/revbayes.github.io
6. After the pull request is merged to the source branch on github, move back to the source branch locally with git checkout source and fetch the latest version with git pull.
7. Now you can run the deploy.sh script to update the master branch.

Pull requests for the website do not currently require review, so you can merge them yourself if checks pass. These checks help to prevent the tutorials from breaking.

Setting up jekyll

In order to build the site you will need to install jekyll.

To install jekyll and bundler (or update them):

gem install jekyll bundler

If you get a permission error, you can install the jekyll and bundler gems in your home folder using:

export GEM_HOME=~/.gem
gem install jekyll bundler

NOTE: You may get errors here that you need to update ruby to install these gems.

If you are having trouble on MacOS with system ruby being out of date, you can install ruby via homebrew with brew install ruby. Then you need to add the homebrew version of ruby to your path by adding:

export PATH="/usr/local/Cellar/ruby/2.7.1_2/bin/:$PATH"

to your .bash_profile file. Then restart your terminal or source .bash_profile.

Next, move into the revbayes.github.io repo directory, and install required gems via:

bundle install

Now, you should be able to build and serve the static HTML with:

bundle exec jekyll serve

To check the static HTML once the command finishes running, navigate to localhost:4000 on your browser.

The previous command will cause a full rebuild of the site each time a file is modified. This can sometimes take a long time. You can selectively regenerate only modified files using the --incremental option

bundle exec jekyll serve --incremental

This will reduce regeneration times substantially. However, keep in mind that if you add new files, or modify _config.yml or any plugins, you will need to do a non-incremental rebuild.

If you get the error "invalid byte sequence in US-ASCII", this seems to fix it:

export LC_CTYPE="en_US.UTF-8"
export LANG="en_US.UTF-8"

Setting up jekyll on Linux

For Debian/Ubuntu Linux, the system jekyll package seems not to work. If you have the system jekyll package installed:

sudo apt-get autoremove jekyll

Instead, you can install jekyll as a gem:

sudo apt-get install ruby-all-dev
export GEM_HOME=~/.gem
export PATH=${GEM_HOME}/bin:$PATH
gem install jekyll bundler

cd revbayes.github.io
bundle install

You may want to put the export lines into your ~/.profile or ~/.bash_profile.

Generated documentation for moves, functions, densities, types, etc.

The documentation functionality depends on _includes/help_index.html, home/documentation.md, _layouts/help.html and _plugins/help.rb.

Files under _site/documentation should be generated when bundle exec jekyll build is run. Normally this is run from deploy.sh.

You also need to have a file called help.yml in the _data/ directory. This file is generated by rb-help2yml.

If you run deploy.sh help, then the generated documentation will over-write the previous documentation during deployment. However, generated documentation will not be commited if you just run deploy.sh.