You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The easiest way to build the site locally is by using the [`nox` command line tool](https://nox.thea.codes/). 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.
21
14
22
-
Install `bundler`, and use it to install the dependencies to build the website:
15
+
To build and preview the site locally, follow these steps:
This will install the needed dependencies in a virtual environment using [the `conda` package manager](https://docs.conda.io/en/latest/).
36
+
37
+
**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.
36
38
37
-
Edit the various parts, the `liveserve` option should automatically rebuild and
38
-
refresh the pages when changes occur.
39
+
**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.
39
40
40
41
To stop serving the website, press **`Ctrl`**-`C` in your terminal
41
42
42
-
Enjoy.
43
+
### Build the site manually
43
44
44
-
# What is where
45
+
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`](Gemfile)).
45
46
46
-
Most pages are located at the place where their URL is, nothing fancy. Headers
47
-
and footer are in `_includes/head.html`, `_includes/header.html`,
48
-
`_includes/footer.html`.
47
+
Follow these steps:
49
48
50
-
The **navbar** is in `_data/nav.yml` and looks like that:
49
+
1.**Install Jekyll**. You have two options:
50
+
-[Follow the Jekyll installation instructions](https://jekyllrb.com/docs/#instructions). These steps will guide you through installing Ruby and Jekyll locally.
51
+
- Use [the anaconda distribution](https://conda.io) and [conda-forge](https://conda-forge.org/).
Finally install Jekyll and Bundler, which will let you install the site's dependencies:
60
+
61
+
```console
62
+
$ gem install jekyll bundler
63
+
```
64
+
2. **Install the site's build dependencies**. These are specified in [`Gemfile`](Gemfile).
65
+
66
+
```console
67
+
$ bundle install
68
+
```
69
+
70
+
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.
71
+
72
+
3.**Build the site locally**.
73
+
74
+
```console
75
+
$ bundle exec jekyll serve liveserve
76
+
```
64
77
65
-
which means, insert in order the following links into the navbar:
78
+
This will build the site's HTML and open a server at `localhost:4000` for you to preview the site.
66
79
67
-
- Link to `Home` page, guess the url by yourself.
68
-
- link to `Install` page, the url is...
69
-
- Link to `About`, guess the url by yourself,
70
-
- ... etc.
71
80
72
-
The navbar will automatically target `_blank` pages where the url is explicit,
73
-
and mark the correct link as the "current" one.
81
+
## Where the site is hosted
74
82
75
-
# How do I create a new page?
83
+
The site is automatically built with [Netlify](https://netlify.com), a hosting service for static websites. When any changes are merged into the `master` branch, Netlify will automatically build them and update the website at [jupyter.org](https://jupyter.org).
84
+
85
+
## Preview changes in a Pull Request
86
+
87
+
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.
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`.
96
+
97
+
## Create a new page
76
98
77
99
Create `my_page.html` (will have url `https://jupyter.org/my_page.html`)
78
100
or `my_page/index.html` (will have url `https://jupyter.org/my_page/`), start with the following:
@@ -90,19 +112,32 @@ You cannot do it yet with .md file, but you will be able soon.
90
112
91
113
Add commit (and don't forget to add to `_data/nav.yml`).
92
114
93
-
#Continuous integration testing on Travis
115
+
## Site quirks and tips
94
116
95
-
Travis will run and test:
117
+
### SCSS variables
96
118
97
-
- jekyll build
98
-
- html-proofer
99
-
- csslint
119
+
Shortcuts with colors and other common variables can be found in `_sass/settings`. They can be used in SCSS files.
100
120
101
-
# Previewing a Pull Request
121
+
```scss
122
+
@import"settings/colors"
102
123
103
-
Netlify is used to provide a link to a rendered website with the changes proposed
104
-
in a PR. This convenience helps reviewers see how the change would look
105
-
before it is deployed in production.
124
+
a {
125
+
color: $orange;
126
+
}
127
+
```
106
128
107
-
The link is found in the GitHub PR status box. In the **deploy/netlify** section,
108
-
click on the `Details` link.
129
+
### Lazy loading of images
130
+
131
+
The Jupyter website uses [lazy loading of images](https://web.dev/browser-level-image-lazy-loading/). 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".
132
+
133
+
Add lazy loading to an image by adding a `loading="lazy"` configuration to the `<img>` element. For example:
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:
0 commit comments