This is a simple Jekyll site that has everything you should need to get started building a GitHub website.
Use this repository, or duplicate it for your next project and run:
$ script/bootstrap
$ script/server
Never run a Jekyll site on your GitHub laptop? Run through these steps:
- Install Strap
- Steps are in the github/github docs
- This preps your computer by installing the proper tooling and security options.
- Setup Ruby
- Install rbenv via Homebrew:
brew install rbenv
. - Download a version of Ruby via rbenv (e.g.,
rbenv install 2.2.3
). See https://gorails.com/setup/osx/10.11-el-capitan. - Make it the global version of Ruby with
rbenv global 2.2.3
, or the local version withrbenv local 2.2.3
.
- Install rbenv via Homebrew:
- Install Jekyll and other gems with
gem install bundler sass jekyll rouge
- Profit!
-
A very basic Jekyll scaffolding to build from as you require additional layouts, includes, data files, and pages.
-
Primer, our front-end framework, and all its packages. You can read documentation here. Include what you need within the
style.scss
file at the root of the repository. -
GitHub's icons, Octicons.
If you'd like to add your own custom styles, add them to style.scss
, located at the root of the repository. We prefer adding new Sass files to the _sass
directory to stay organized, but you can also add styles to right to style.scss
.
If you'd like to change the theme's HTML layout, modify or duplicate the _layouts/default.html
as needed. Whatever you name the file in _layouts
is how you'll refer to it from your pages and posts as you create them.
For example, if you created a page.html
layout for an About page, the top of your about.md
file would require:
---
layout: page
title: about
---
*Page content here...*
Jekyll layouts can also be nested. If you love everything about the default.html
layout and want to add more structure within it, create a new layout and add the appropriate front matter at the top:
---
layout: default
---
*Additional layout HTML here...*
If you need a private, internal-only staging instance for your project, you have two options that make use of secondary repos on https://GHE.io.
For super simple sites that make no use of custom Jekyll plugins (e.g., our Octicons plugin), you can add a new Git remote and push your changes there.
git add remote staging https://ghe.io/user/repo
git push staging gh-pages
From there, your Jekyll project will be built on GHE.io's Pages instance and available at https://pages.ghe.io/user/repo
. You may use any user (your own, github
, etc) and repo you wish.
For more complex projects, a build and publish script, script/stage
, is needed. This is helpful for when you have a custom baseurl
or non-whitelisted Jekyll plugins. Before using it, this script must be customized.
Option | Default value | Description |
---|---|---|
account |
github |
Doesn't need replacing, but it is customizable. This refers to the user or organization account on GHE.io. |
repo |
your-staging-repo |
Needs replacing before using. This is the name of the staging repository in the account . |
When you're all set, open Terminal to give the script permission to run:
chmod 0755 script/stage
Then, execute the script:
script/stage
This will compile your Jekyll site, create a temporary Git repository on the fly, and then push that to your GHE.io repository. Within a couple minutes, your site will be staged https://pages.ghe.io/{account}/{your-staging-repo}
.
Need multiple staging repositories? Create your additional repositories under the same user or org account, then specify the repository name in Termimal:
script/stage staging2
- If you need help with web design, content, or structure, you can reach out to anyone on the @github/web-design team.
- If you need help with CSS or brand, you can talk to anyone on the @github/design-systems team.