| layout | title |
|---|---|
page |
About this site |
- Site source on Github: cboettig/labnotebook.
- Please report errors or give feedback.
- Colors and syntax highlighting with Solarized
- Crisp equations rendered in Mathjax
- Reproducible code execution with knitr
- CSS based on twitter bootstrap
- Scalable css icons from FontAwesome
- Static site generation with Jekyll
- Markdown parsing with pandoc
- Twitter, Mendeley & Github custom plugins
- Carbon-neutral site hosting by Dreamhost
- Source code hosting on Github
- Uptime monitoring from my.pingdom.com; see status report
- CDN from cloudflare
The lab notebook is written and maintained in plain text (UTF-8) using markdown. All files are kept in a version managed repository system using git, which provides unique SHA hashes to protect against corruption. Synchronized backups of the git repository are maintained on both local and remote servers (RAID 6) to protect against hardware failures, as well as on the public international software repository, Github github.com/cboettig. Version history preserves a time-line of changes and protects against user error. Archival copies of notebook entries shall be published annually to figshare where they will be assigned DOIs and preserved by the CLOCKSS geopolitically distributed 12 node global archive.
This site is built by Jekyll, a static site generator which creates html pages from markdown files. Here are the instructions for building the site from source, based on my Ubuntu 12.04 platform. Feel free to adapt this configuration to your own needs.
Clone the site source-code from github:
git clone https://github.com/cboettig/labnotebook.gitInstall Ruby version >= 1.9
sudo apt-get install ruby1.9.1-fullMake sure the latest version is selected
sudo update-alternatives --config ruby
sudo update-alternatives --config gemInstall Jekyll and the dependencies needed for a few plugins.
sudo gem install jekyll feedzirra nokogiri twitter octokit pandoc-ruby garb chronic json time In the root directory of the project, run jekyll --server, if successfull, after a few seconds the site should be available by pointing your browser to localhost:4000. The additional gems are required for various plugins; see below for more information. Due to these additional requirements, this site cannot be automatically rendered on Github's pages. Compile the site locally and copy the html files in _site to the gh-pages branch of a Github repository for Github-based hosting.
The site relies on following additional ruby gems (not available on the Jekyll copy provided on Github's gh-pages) to compile successfully.
- feedzirra -- Grab and format RSS feed information
- nokogiri -- parse HTML and XML
- twitter-- Ruby bindings to the Twitter API
- octokit -- Ruby bindings to the Github API
- pandoc-ruby -- Ruby implementation of pandoc markdown interpreter (an alternative to redcarpet2)
- garb -- Google API
- chronic -- parse timestamps
- json -- parse json
I have written a series of custom Jekyll plugins using these gems. See the header comments of each plugin for more details on their configuration and use. Most are written explicitly for my notebook and may require tweaking for general use. Plugins are frequently under development, see the plugin page for most recent plugins and versions.
Plugin Description
base_name.rb Liquid filter for a page to return its base filename. github_feed.rb Display Github user activity (based on their atom feed) git_modified.rb Obtain page's modification date from it's last commit to git google_analytics.rb Obtain the number of pageviews of a given URL (from Google Analytics) octokit.rb Display data such as issues or commits by repository, from Github API twitter_feed.rb Display a user's most recent tweets codecogs.rb Use codecogs to turn equations into images (useful for RSS readers that can't render mathjax) github_link.rb Link a page to its Github changelog history git_sha.rb Grab the SHA hash corresponding to the current page version mendeley_feed.rb Show articles recently added to a Mendeley group raw_content.rb Provide access to the unparsed (markdown) version of a page
Several of my custom plugins require authentication credentials to the relevant API, which are not included when forking this public repository, for obvious reasons. These credentials should be stored as secure YAML files in your home directory. See plugins for details (e.g. octokit, twitter_feed, google_analytics).
Plugins are provided in the site source, so cloning this repository will give you a copy of them. In addition to the plugins listed above, I am greatful to other Jekyll developers for the following plugins:
- pandoc (Markdown parser)
- redirects (page redirects)
- tag-cloud
- generate_searchindex Generate database for a fast stemming-based search algorithm (see javascript as well). Customized from Marran 2012. My current site search tool.
- jekyll-lunr-search Generate database for a high quality but slow javascript-based search.
Markdown is wonderful, but a huge headache due to it's many flavors. I began using redcarpet2 via the redcarpet2 plugin which powers Github-flavored markdown, but have exchanged this for Pandoc. Pandoc markdown relies on a logically consistent internal grammar (leave it to the philosphers to write mathematically rigorous parser), something the original and some adaptations seriously lack. On a pratical note, Pandoc is useful for it's wide support of conversion to other formats, including pdf and word docs for publication.
All original content is licensed by Carl Boettiger under the Creative Commons Zero license, CC0. This license is uniquely appropriate for data, code, and written content, and facilitates distribution & reuse. (Plugins are also provided under the MIT license). Please remember that attribution and citation are appreciated where appropriate as proper scholarly practice. (Newton, Darwin, and Shakespeare are similarly in the public domain, but you wouldn't plagiarize from them). Cite or attribute this work as:
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.