The Primer Spec theme

Primer Spec is a Jekyll theme for GitHub Pages. You can preview the theme to see what it looks like, or even use it today.

Primer Spec is built on top of the wonderful Primer theme, and adds functionality useful for pages with a lot of content. This theme was primarily designed for hosting Project specifications for EECS courses at the University of Michigan.

Integrating with GitHub Pages

To use the Primer Spec theme:

Decide where to host your GitHub pages. See https://pages.github.com for guides.
Add your Markdown files. Note that files named README.md will be ignored by Jekyll when using a custom theme.
In your GitHub Pages directory, create a file named _config.yml. Add this to the file:
```
remote_theme: eecs485staff/primer-spec
plugins:
    - jekyll-remote-theme
```
Finally, to display a table of contents in the sidebar, add the following at the top of your MarkDown files:
```
---
layout: spec # Change to `default` if you prefer not to show the sidebar.
---
```

(Optional) To prevent a heading from appearing in the sidebar, add {: .primer-spec-toc-ignore } under the heading. For instance:

### This heading appears in the sidebar

Spam spam spam.

### This heading does NOT appear in the sidebar.
{: .primer-spec-toc-ignore }

Spam spam spam.

Previewing locally

If you'd like to preview your site on your computer do the following.

Local Setup Part 1: Create the dependency files

Create a file named Gemfile in your project root directory. Add this to the file:

source 'https://rubygems.org'

gem 'github-pages', group: :jekyll_plugins
gem 'jekyll-remote-theme'

# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]

# Performance-booster for watching directories on Windows
gem 'wdm', '~> 0.1.0' if Gem.win_platform?

Create a .gitignore file in your GitHub Pages directory with the following contents:

# This .gitignore file is for locally-rendered Jekyll sites.

# Locally rendered website
_site

# Other Jekyll files
.sass-cache
.jekyll-metadata

Local Setup Part 2: Install the dependencies

Ensure that you have a version of Ruby later than 2.1.0. If you're on a Mac, you may need to run brew install ruby first. You must also install bundler.
```
$ ruby --version
ruby 2.6.1p33 (2019-01-30 revision 66950) [x86_64-darwin18]
$ gem install bundler
```

Install the dependencies.

$ pwd
/seshrs/demo-project
$ bundle install

Run the Jekyll server to build the site and watch for changes. By default, the site is served at http://127.0.0.1:4000.
```
$ pwd
/seshrs/demo-project/docs
$ bundle exec jekyll serve
```

Customizing

Configuration variables

Primer Spec will respect the following variables, if set in your site's _config.yml:

title: [The title of your site]
description: [A short description of your site's purpose]

Additionally, you may choose to set the following optional variables:

google_analytics: [Your Google Analytics tracking ID]

Stylesheet

If you'd like to add your own custom styles:

Create a file called /assets/css/style.scss in your site
Add the following content to the top of the file, exactly as shown:
```
---
---

@import "{{ site.theme }}";
```
Add any custom CSS (or Sass, including imports) you'd like immediately after the @import line

Layouts

If you'd like to change the theme's HTML layout:

Copy the original template from the theme's repository
(Pro-tip: click "raw" to make copying easier)
Create a file called /_layouts/default.html in your site
Paste the default layout content copied in the first step
Customize the layout as you'd like

Contributing

Interested in contributing to Primer? We'd love your help. Primer is an open source project, built one contribution at a time by users like you. See the CONTRIBUTING file for further instructions on how to contribute.

Typical workflow

Fork the repository.
Clone your repository to a local directory.
Create a new branch with an appropriate name. (git checkout -b feature/my-feature)
Bootstrap your local environment.
Make some changes and create commits.
Push your branch to GitHub. (git push -u origin feature/my-feature)
Open a pull request from your branch to the EECS 485 repository. (For example, https://github.com/eecs485staff/primer-spec/compare/eecs485staff:master...pages-themes:master)

Bootstrap your local environment

Ensure that you have a version of Ruby later than 2.1.0. If you're on a Mac, you may need to run brew install ruby first.

Run script/bootstrap.

$ ruby --version
ruby 2.6.1p33 (2019-01-30 revision 66950) [x86_64-darwin18]
$ pwd
/seshrs/primer-spec
$ ./script/bootstrap

Run script/server to begin the Jekyll server. By default, the site is served at http://localhost:4000/. (It monitors changes you make to most theme files and automatically rebuilds the website.)

Running tests

The theme contains a minimal test suite, to ensure a site with the theme would build successfully. To run the tests, simply run script/cibuild. You'll need to run script/bootstrap one before the test script will work.

Modifications from Primer

Here are key changes made to the original Primer theme to add a sidebar:

Created _layouts/spec.html. This file is used to render MarkDown files with layout: spec at the top. The file is similar to _layouts/default.html, but adds the sidebar and references the JavaScript needed to render the table of contents.
Created _sass/spec/ with the SCSS files needed to display the sidebar. Also modified _sass/jekyll-theme-primer.scss to include these files.
Created assets/js/ with the necessary files to generate a table of contents.

Keeping this theme up-to-date with Primer

It's important to periodically check for changes from the original upstream theme (Primer).

Compare the two repositories to check for changes. This can be achieved by drafting a Pull Request.
If there are changes, check the scope of changes. (If there are changes to _layouts/default.html, they will have to be reflected in _layouts/spec.html also.)

bellakiminsun / primer-spec Goto Github PK

primer-spec's Introduction