publishing a static site - INFO-664 notebooks

For this session, we will combine Jekyll and Github Pages to deploy your project into a website that others can access on the internet.

For this session, we will use Github Pages to deploy your project into a website that others can access on the internet.

What is Github Pages?¶

A hosting service by Github that lets you create static sites on the web. It takes HTML, CSS, and JavaScript files from a GitHub repository, and publishes them as a website.

What are static sites?¶

Websites that are generated once (usually by a program like Python or Ruby), then pushed to the server to be hosted in its already-generated or “static” state
This static site uses a software called jekyll, written in Ruby.

Github pages has built-in support for some kinds of Jekyll sites, which means that you can create one completely through Github.com. This is a massive benefit, because virtually all open source web authoring platforms require you to download and install software via the command line.

For those of you more familiar with the command line, you’d have a lot more options of different Jekyll themes to choose from, and a lot more control generally over the way your site is created. That being said, it is a higher barrier to entry and requires you to install software like git and jekyll (along with its dependencies, like ruby) over the command line. how to set up Jekyll on Github Pages

how to set up Jekyll on Github Pages¶

1) choose a theme and fork it!¶

Choose a theme you like from this page: https://github.com/pages-themes

Fork the theme by going to the github repository for that theme, and on the top right, press “fork”.

When you are prompted, be sure to change the name of the respository to something relevant to your project.

2) open the web editor, edit your index.md file¶

Open the code editor by pressing the period (.) button on your Keyboard. You’ll see a new interface appear which lets you edit the files in your repo.

First, edit your README.md file, which should be in the root (first level) folder of the repository. Copy and paste your current README.md file to this file, replacing what is currently there.

Second, edit your index.md file. This file is written in markdown, and offers a handy key for markdown formatting. The top section (sandwiched by hyphens) is layout information for the page. Do not change these first three lines).

You can read a whole lot more about markdown formatting here: https://www.markdownguide.org/cheat-sheet/

Want to create new page? Create a new file for your page called PAGE-NAME.md, replacing PAGE-NAME with a meaningful filename for the page.

Add the following frontmatter to the top of the file, replacing PAGE-TITLE with the page’s title and URL-PATH with a path you want for the page’s URL. For example, if the base URL of your site is https://octocat.github.io and your URL-PATH is about/contact, your page will be located at https://octocat.github.io/about/contact.

layout: page
title: "PAGE-TITLE"
permalink: /URL-PATH

Below the frontmatter, add content for your page.

3) commit and push your changes¶

Once you’re done editing the markdown file, go to the little “source” tab on the left. It looks like three dots connected by lines. Here, on the lefthand sidebar, you’ll see a list of all the changes you’ve made, and a blank text box above them. In that blank box, write a short message summarizing your changes, like “edited the index.md file”. Then, press the “commit & push” button.

4) configure Github pages on your repo settings¶

Back on your regular repository page (you will need to open up a new tab and navigate to your repo on github), go to the “Settings” tab at the top. Then, scroll down to the “Pages” tab on the left sidebar.

Then, on the main section of the page, go to the Branch heading. From the first dropdown, select “Master” or “Main,” and select “root” (if not already selected). Finally, click save.

Congratulations!

Your website will be visible in a few minutes at the URL:

your_username.github.io/your_repo_name