The Data 8 Jekyll textbook
This repository holds a Jekyll-based version of the Data 8 textbook.
All textbook content is primarily stored in Jupyter notebooks in the
This can be converted to Jekyll-ready markdown and served on github pages.
How this repository is deployed to
The Data 8 textbook has a slightly more complex deploy process. This is because [GitHub doesn't work well for using a custom domain name for an organization's non-root repository](https://help.github.com/articles/custom-domain-redirects-for-github-pages-sites/ is why we have to do this in the first place).
So, here's how the textbook deploy works:
The textbook is deployed to
inferentialthinking.comfrom this the repository here:
You should not ever directly edit the inferentialthinking.github.io repository
Instead, updates to the textbook should be made at this repository (
When you make a change to this repository and push it to the
data-8/textbookgh-pages branch, these changes should automatically be copied to https://github.com/inferentialthinking/inferentialthinking.github.io.
This is done with CircleCI, and the configuration for this can be found
Building the textbook
Here are steps to get started building the textbook on your own machine:
Install the proper dependencies. You can do this by installing the Anaconda environment specified in
conda env create -f environment.yml
This will install some Python and Ruby packages that are needed to build the book.
Activate the conda environment in order to have access to these packages.
conda activate textbook
Initialize your Jekyll plugin. To get the proper Jekyll packages to build your book, run the following command:
Build the textbook by navigating to the root of the repository and running the following command:
nbconvertto turn the
.ipynbfiles into markdown that Jekyll can build
- Place images and the built markdown files into the
- Clean up formatting issues for displaying properly
- Generate the yaml for the site sidebar automatically
You can the push the changes to GitHub, which will automatically build a Jekyll site with your newly-created Markdown files.
To preview your built site using Jekyll on your computer, take the following steps:
Ensure that your notebooks have been converted to markdown:
Serve the site locally to see what it looks like:
This should open up a port on your computer with a live version of the textbook. It will
also generate the HTML version of your book in the
Update the interact links for your JupyterHub
If you'd like to serve this textbook using your own interact links, take the following steps:
- In the
_config.ymlfile, find the field called
- Modify the value so that it reflects your JupyterHub's URL.
- Push your changes to GitHub.
- That's it!
content/contains all course content in Jupyter notebook form
data/contains the CSV data files used in the course textbook
images/contains images referenced in the course
_data/toc.ymlcontains a yaml list of chapters / paths to your textbook files. For example, here is a sample for the first few pages:
- title: Data Science url: /chapters/01/what-is-data-science sections: - title: Introduction url: /chapters/01/1/intro subsections: - title: Computational Tools url: /chapters/01/1/1/computational-tools - title: Statistical Techniques url: /chapters/01/1/2/statistical-techniques - title: Why Data Science? url: /chapters/01/2/why-data-science - title: Plotting the Classics url: /chapters/01/3/Plotting_the_Classics
Auto-generated folders and files
_build/imagescontains images generated during the notebook conversion
_build/contain notebooks converted to markdown
_site/contains the HTML for the built site. It is created by Jekyll, and should only exist if you build the site locally
Repository configuration and build files
_config.ymlcontains all site configuration.
scripts/contains scripts to generate the textbook from the Jupyter notebooks
_sasscontains CSS for the textbook and website
environment.ymlcontains the environment needed to build and run the textbook