layout | title |
---|---|
default |
About this site |
This site is mostly static HTML, generated by Jekyll from source on Github. You are free to fork and modify it for your own needs. It was originally based on Carl Boettiger's labnotebook sites and David Ketcheson's customization. Carl publishes the source for his site on Github as the labnotebook project and releases it all under CC0, so setting my site up was as easy as following his instructions, replacing the _posts directory, and making a few CSS customizations. I have customized the source code a little bit more to make it much easier for anyone to adapt this source code to other repos and sites (see detailed instructions in a later section).
To run the site on a local computer, you need to install Jekyll and
dependencies, run bundle install
then bundle exec jekyll serve
(see detailed instruction below and the issue of using baseurl for gh-pages subrepos).
You can generate the Publications page from a bibtex file using some code David Ketcheson wrote to generate HTML divs from Bibtex. It also makes use of jQuery and MixItUp for filtering and searching. Here, I am using the Jekyll-scholar with some customizations.
Please report any errors or other feedback to the Issue Tracker for this site, or in general for the Labnotebook on Carl's repo.
- CSS generated with twitter bootstrap
- Carl Boettiger's plugins for Mendeley, Github, Twitter and others
- Integrated with IPython/IJulia/Jupyter notebooks and MathJax
- Source code hosting on Github with automatic deployment using Travis-CI and Rake
- Improved "related posts" plugin from David Lynch
- Improved publication and citation support from Jekyll-scholar with some customizations
- Allow pulling BibTeX database of bibliography from an external repository using submodule for centralized bibliography management
I use Ubuntu 16.04 LTS OS to generate the static website from source code. Instructions on other operating systems should be similar. The first thing to do is to clone the remote repository files to your local computer by
git clone --recursive https://github.com/i2000s/i2000s.github.io.git
where the --recursive
option is to make sure submodules (if any) are pulled down completely.
If you run Jekyll sites for the first time, you may need to install Ruby v2.3.* (tested on v2.3.0 and v2.3.1) and the gem
development envirenment.
I was basically following this instruction on my Ubuntu,
except for the step of sourcing RVM which I used the following command line instead
source ~/.rvm/scripts/rvm
But you may find the source command works for you. An improvement on the source command line following the instruction in the link is to use
echo "source /etc/profile.d/rvm.sh" >> ~/.bash_profile
which will add the rvm path to the bash profile perminantly.
If the source is setup correctly, type rvm | head -n 1
should give rvm is a function
as the output according to this.
If you encounter any problem before the sourcing step, you should make sure whether the security key has been updated from the official Ruby site.
Or, if you find the problem is due to the certificate, you may want to check out this solution.
Otherwise, you can also install rvm from a third-party repo following this instruction on Ubuntu OS and follow the outputed command line instruction on sourcing the profile.
On Ubuntu 16.04, you can follow this instruction for updated information. I would recommend you to use rvm on Rails to configure a compatible Ruby version, which is employed on travis.CI. In the process of installing Ruby through rvm, if you encounter the permission denied error, you can try
rvmsudo rvm install 2.3.1
as an example.
Similarly, if gem install rails
or other gem install command lines fail, you can also try
rvmsudo gem install rails
or similar to help solve some gem/Ruby package installation errors by promoting permissions in rvm.
For other systems, here is the official guide for Ruby installation.
Besides, the library of gsl
and the pandoc
package are recommended to install for better support to the clarifier-reborn
and other plugins/scripts used in this site.
On Ubuntu, I use the following lines
sudo add-apt-repository -y ppa:marutter/c2d4u
sudo apt-get update
sudo apt-get install pandoc pandoc-citeproc
sudo apt-get install gsl-bin libgsl0-dev
On Windows OS, you may be able to follow this instruction to install Jekyll.
If you find some error related to Ruby Development Kit when you run bundle exec jekyll serve
or gem install ***
, you may find this experience helpful.
gsl
should be preinstalled in order to gem install rb-gsl
, where the step in the .travis.yml
configuration file about installing gsl-bin
step does not apply to Windows systems.
The Gemfile
and the configuration files _conf.yml
and .travis.yml
should include sufficient information on installing correct dependences.
Then for a routinely rendering, you only need to run the following command lines:
bundle install
bundle exec jekyll serve
Notice that, I have locked the Jekyll version to ~>3.1.6
.
If you want to use Jekyll version 2.5 or earlier, you may need to tweak the code a little bit.
If you encounter the missing credentials error for the twitter_feed
plugin, you may need to export environmental variables TWIT_KEY
, TWIT_SECRET
, TWIT_TOK
and TWIT_TOK_SECRET
before running the jekyll server. All the credentials of the Twitter plugin should be accessible from the TWitter account used for the site.
By default, the local build should be accessible at http://127.0.0.1:4000
on your internet browser.
Since Jekyll uses a very efficient way to control common information in fewer places, you can easily modify the source code of this website to generate your own website on GitHub and deploy to elsewhere. In fact, when the site was initially designed and modified especially to my end, it has always been a common goal to make it easy for the community to migrate this source code to other web hosts and adapt to various purposes. I encourage you to post an issue or make a pull request on this repo or the original labnotebook repo if you find a way to improve the general design. Only in this way, the network of people who have adapted this design to their sites can benefit most from the continuous improvement by the community who are following this body of code for open science and beyond. Below are the minimum changes you need to make to serve your own purpose of using the source code.
-
Fork this repo under your GitHub account, and then clone the repo to your local folder by
git clone --recursive YOURGITREPOREMOTE
. -
Change information defined in the
_config.yml
file for your case. There you will find definitions for your site, Github account and repo information, as well as your personal contact information. I will explain more advanced setting information below. -
Add encrypted information in the
.travis.yml
file. There you will find theenv/global
section where global variables are defined to automatically generate twitter timeline, github comment history and deploy the site as gh-pages on the Travis-CI server. You should remove all the original code starting withsecure
and replace with your own encrypted codes line by line in the.travis.yml
file or on the Travis-CI setting page. The recommended minimum global variables to be encrypted are: Github Token (variable nameGH_TOKEN
), git commit author name (GIT_NAME
), git commit author email (GIT_EMAIL
); if you want to generate a Twitter message line on your site using thetwitter_feed.rb
plugin, you will also need to encrypt Twitter key (TWIT_KEY
), secret (TWIT_SECRET
), token (TWIT_TOK
), token secret (TWIT_TOK_SECRET
). Before you commit this step, make sure you have ativated the Travis-CI module for your Github repo. You can then generate the encrypted variables by installing travis while on your local repo directory with commandgem install travis
and using the following command line formattravis encrypt GIT_NAME="Xiaodong Qi"
. You should replace the variable name and value with the real cases as bash commands one after one. Notice that when the variable value has a space inside, you need to use a pair of quotation marks as the example I gave--otherwise no need to use quotation marks in most cases; if you have special characters that bash command doesn't like, you need to escape those characters. The last command line should generate a long string of random characters which you should be able to add to theenv/global
section of the.travis.yml
file in the format of- secure Your_Encrypt_Random_bits
. You can certainly add more encrypt variables or define some non-sensitive variables as explicit/non-encrypted variables in a similar way, but the Github token has to be encrypted to pass the security check of Github. -
If you have different amount of social accounts or plugin items defined in the
_config.yml
file, you need to double modify the scripts appeared in the header and footer template under the_include
directory. Notice that, by using different set of social account info in the configure file, the default social media icons will link to the front page of those empty social network websites. To avoid these unwanted icons, you may want to delete/comment out those icon blocks in the footer templates and the index.html pages. Similarly, if you want to add new social media icons, you can modify the configure file and corresponding footers with a compatible icon image. On the top of this README file, there is an icon showing the compilation status of Travis-CI, you might want to modify the icon address to your case--pay attention to the username/organization name which is capital sensitive to Travis-CI. -
Check the
metadata.html
template defined under the_include
directory to make sure necessary information are shown correctly for you. This metadata is just for different search engines and robots to recognize your website in particular formats. I have used fields likeOtherName
to identify the author's local language name, as well as both Google analytics and Baidu analytics IDs for page visitor statistics. You can delete this field in theconfig.yml
and themetadata.html
files. Theanalytics.html
template in the_include
directory has the website visiting analytics scripts for Google and Baidu which you may need to delete one or add a new one according to your preference. The metadata file also defines the language information and keywords where you should most likely modify for your own version. Other information if you don't understand, leaving them alone should be fine in most cases.The publication and citation databases are defined in the
asset
directory as bibtex files with suffix.bib
, which you may want to replace with your own.
The rest is to delete or keep posts and pages to fit into your needs. Notice that you can use submodule and put references in a folder likeassets/bibliography/refs
to a centralized bibliography database. The information of the submodule is then recorded in the.gitsubmodules
file under the root direction of the repo. To use your own submodule, add the submodule bygit submodule add -b YOURBibliographyBRANCH https://YOURBibliographyRemoteAddress.git assets/bibliography/refs
. It might be also necessary to rungit submodule init
orgit submodule update
to pull your submodule files into the actual folder if it's empty. After that, you also need to update the bibliography address in the correspondingpandoc
bibliography extension configuration item of the_config.yml
file. One advantage of using the submodule feature of Git is that you can commit and push changes from this webpage repo to your bibliography repo on the specific branch and vice verse. Changes of the submodule can be committed in the corresponding submodule folder using Git the same as an independent git repo. When you want to pull changes from the centralized bibliography repo, you can usegit submodule update --remote
and the webpage repo will have the corresponding SHA reference recorded in the git configuration file. Make sure you always commit the submodule changes before committing to this webpage development repo (also regarded as the superproject).
I suggest to put this source code in a branch other than master
or gh-pages
in your Github repository, which you need to define in the _config.yml
file as the sourcebranch
.
The Travis-CI server will commit the generate website onto the master
or gh-pages
github branch depending on your case.
Once you have all the necessary configurations done, Travis-CI will be happily deploying your site on Github.
If you want the site to be deployed on a host other than Github, you may want to modify and run the publish.sh
bash script to synchronize your locally generated _site
folder or the master/gh-pages branch updated by Travis-CI to your target site host.
MIT license for the plugins (in the _plugins
directory of this repo) shown initially written by Carl Boettiger or Xiaodong Qi.
Creative Commons Attributions 3.0 Unported CC-BY license for the content originally created by David Ketcheson.
Creative Commons Attributions 4.0 CC-BY license for content other than plugins originally written by Xiaodong Qi and all the other unspecified cases.
If a license is clarified at a much specified scope, that specified license should apply to the scope it covers.
You can find the full editing history of each file.
Credits should be given appropriately to the origination and the initial author at less and all following contributors if situation permits.
For instance, you can cite or attribute posts/works originally from this site/repository as:
Xiaodong Qi ("Page publication date"), "Page Title", Lab Notebook, http://i2000s.github.io
with appropriate page title and publication date as indicated. Greycite is an excellent online tool that can generate the citation information for any particular page given it's URL.