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 notebooks/ folder. 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.

So, here's how the textbook deploy works:

Building the textbook

Here are steps to get started building the textbook on your own machine:

  1. Install the proper dependencies. You can do this by installing the Anaconda environment specified in environment.yml:

    conda env create -f environment.yml

    This will install some Python and Ruby packages that are needed to build the book.

  2. Activate the conda environment in order to have access to these packages.

    conda activate textbook
  3. Initialize your Jekyll plugin. To get the proper Jekyll packages to build your book, run the following command:

    make install
  4. Build the textbook by navigating to the root of the repository and running the following command:

    make book

This will:

  • Run nbconvert to turn the .ipynb files into markdown that Jekyll can build
  • Place images and the built markdown files into the _build folder
  • 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:

  1. Ensure that Jekyll and Ruby are installed. See the Jekyll docs for information on this. As well as the GitHub gh-pages documentation for more information on how Jekyll and GitHub interact.
  2. Ensure that your notebooks have been converted to markdown:

    make book
  3. Serve the site locally to see what it looks like:

    make serve

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 _site/ folder.

If you'd like to serve this textbook using your own interact links, take the following steps:

  1. In the _config.yml file, find the field called hub_url.
  2. Modify the value so that it reflects your JupyterHub's URL.
  3. Push your changes to GitHub.
  4. That's it!

Relevant files

Course materials

  • 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.yml contains 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
      - title: Introduction
        url: /chapters/01/1/intro
        - 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/images contains 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.yml contains all site configuration.
  • scripts/ contains scripts to generate the textbook from the Jupyter notebooks
  • _sass contains CSS for the textbook and website
  • environment.yml contains the environment needed to build and run the textbook

results matching ""

    No results matching ""