Jupyter's main website

This is the source to Jupyter.org.

Where the site is hosted

There are two ways that this site is built:

• Pull Request previews are built with Netlify, a hosting service for static websites. See the section below for more information.
• Hosting for jupyter.org is done via GitHub Pages. GitHub will automatically use Jekyll to build the HTML for this site and host it at jupyter.github.io, which connects with jupyter.org.

Preview changes in a Pull Request

Netlify will automatically build a preview of the website in an open Pull Request. To see this, click on the Show all checks button just above the comment box in the Pull Request window. Then click on the details link on the deploy/netlify row to see a preview of the built site.

Here's an image of this box on a GitHub PR page:

Site-wide announcement banner

The file _includes/banner.html controls an announcement banner that is shown at the top of jupyter.org and at the top of Jupyter documentation sites that subscribe to it (see below). At build time the content is embedded into every jupyter.org page and also published at https://jupyter.org/assets/banner.html for documentation sites.

• To show a banner: open a PR that puts a short HTML fragment in _includes/banner.html, for example:

  <p>
    <a href="https://example.org/survey" target="_blank" rel="noopener noreferrer">
      Take the short Jupyter User Survey
    </a> to give feedback on how to improve Jupyter.
  </p>
  

• To remove the banner: open a PR that empties _includes/banner.html (empty the file, but do not delete it — the site build references it).

Notes:

• Keep the fragment to plain content (text and links). Each site provides its own banner container and styling: jupyter.org styles it with the .global-banner component, and documentation sites style it with their theme's announcement banner.
• On jupyter.org the banner can be dismissed. A dismissal remembers a normalized text of the most recent dismissal, so publishing a banner with different text shows the banner again. Since the text is normalized, though, just changing an html link without changing the text will not show the banner again.

Subscribing a documentation site to the banner

Documentation sites using the pydata-sphinx-theme, which has an announcements feature, can subscribe by including the following code in their conf.py:

html_theme_options = {
    # Default: show the shared Jupyter announcement banner; content is managed
    # at https://github.com/jupyter/jupyter.github.io (assets/banner.html).
    "announcement": "https://jupyter.org/assets/banner.html",
}

Latest blog posts on the homepage

Under the jumbotron, the homepage shows the three newest posts from the Jupyter blog under a heading that links to the blog (_includes/blog-latest.html, configured by blog: in index.html's front matter). The posts are read in the browser from https://blog.jupyter.org/latest.json, a short list of the newest posts that the blog writes each time it is deployed.

Web analytics

We are using Plausible.io for web analytics. We are also experimenting with using the Scientific Python's hosted Plausible instance (see https://github.com/jupyter/jupyter.github.io/pull/902).

• Plausible metrics dashboard
• Scientific Python metrics dashboard

Build the site locally

See the sections below for a few ways to build the site locally.

The site is built with Jekyll, see the Jekyll website for how to customize the build process.

Build the site automatically with nox

The easiest way to build the site locally is by using the nox command line tool. This tool makes it easy to automate commands in a repository, and we have included a build command to quickly install the dependencies and build the site.

To build and preview the site locally, follow these steps:

1. Clone this repository.

   $ git clone https://github.com/jupyter/jupyter.github.io
   $ cd jupyter.github.io
   

2. Install nox

   $ pip install nox
   

3. Run the build command

   $ nox -s build-live
   

This will install the needed dependencies in a virtual environment using the conda package manager.

When the build is finished, go to localhost:4000. When Jekyll finishes building your site, it will open a port on your computer and serve the website there so that you may preview it.

You can make changes and watch the preview auto-update. When you make changes to the website, they will automatically be updated in your preview in the browser.

To stop serving the website, press Ctrl-C in your terminal

Build the site manually

To build the site manually, you'll need Ruby, Jekyll, and the packages that Jekyll uses to build the site (these are defined in Gemfile).

Follow these steps:

1. Install Jekyll. You have two options:

   • Follow the Jekyll installation instructions. These steps will guide you through installing Ruby and Jekyll locally.

   • Use the anaconda distribution and conda-forge.

     First install miniconda, then run the following command:

     $ conda install -c conda-forge ruby c-compiler compilers cxx-compiler
     

     Finally install Jekyll and Bundler, which will let you install the site's dependencies:

     $ gem install jekyll bundler
     

2. Install the site's build dependencies. These are specified in Gemfile.

   $ bundle install
   

   This step might take a few moments as it must download and install a number of local extensions. It will create a local file called Gemfile.lock. These are the "frozen" dependencies and their version numbers needed to build the site.

3. Build the site locally.

   $ bundle exec jekyll serve liveserve
   

   This will build the site's HTML and open a server at localhost:4000 for you to preview the site.

Structure of this website

Most pages are located at the place where their URL is, nothing fancy. Some are written in HTML. Others are written in Markdown. The homepage is in index.html. The about page is in about.md`.

Create a new page

Create my_page.html (will have url https://jupyter.org/my_page.html) or my_page/index.html (will have url https://jupyter.org/my_page/), start with the following:

---
layout: default
title: My Page
---

write some html here (consider you are already inside `<body></body>`)

You cannot do it yet with .md file, but you will be able soon.

Add commit (and don't forget to add to _data/nav.yml).

Site quirks and tips

SCSS variables

Shortcuts with colors and other common variables can be found in _sass/settings. They can be used in SCSS files.

@import "settings/colors"

a {
    color: $orange;
}

Minifying images

We recommend minifying images whenever adding them to this website. This helps keep the page load times of our website down. There are many minifying services out there, but the squoosh.app service is a lightweight and easy-to-use option.

Lazy loading of images

The Jupyter website uses lazy loading of images. In general, images that are "below the fold" (below the browser window on page load) for laptop-sized screen sizes are encouraged to be configured for "lazy loading".

Add lazy loading to an image by adding a loading="lazy" configuration to the <img> element. For example:

<img class="my-class" src="my/src.png" loading="lazy" />

For images that are "above the fold" (that will be seen by users immediately after page load), use "eager" loading to make sure they are loaded immediately. For example:

<img class="my-class" src="my/src.png" loading="eager" />

Automated quality checks

A workflow on GitHub Actions is run at every push and for every pull request to ensure basic integrity of the website:

• validating the structure of the HTML using Nu validator to ensure compliance with HTML standards
• checking linked URLs for errors (including expired certificates)
• running Lighthouse audits to ensure performance, accessibility, SEO optimization and best practices

If pre-defined quality targets are not met, the jobs will fail. Click on "Details" link for the failing job to see what caused the failure.

The detailed results will be available in the logs (which are only shown to users logged in on GitHub), including links to full Lighthouse reports on public temporary storage (the links will expire after 7 days).