Skip to content

Commit

Permalink
Refocus README on Jekyll Usage
Browse files Browse the repository at this point in the history 
Since we recommend most users to use Primer Spec with Jekyll, this commit moves the plugin-related instructions to the 'advanced usage' doc.
This commit also includes a change to the suggested Gemfile code to resolve #29.
  • Loading branch information
@seshrs
seshrs committed Dec 15, 2019
1 parent 58881e1 commit 2869aea
Show file tree
Hide file tree
Showing 3 changed files with 193 additions and 215 deletions.
121 changes: 15 additions & 106 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,134 +2,43 @@

[![Build Status](https://travis-ci.com/eecs485staff/primer-spec.svg?branch=master)](https://travis-ci.com/eecs485staff/primer-spec)

*Primer Spec is a Jekyll (and HTML) theme that makes long informative web pages easier to read. In addition to aesthetic styling, the theme generates a table of contents displayed in a sidebar. You can [preview the theme to see what it looks like](http://eecs485staff.github.io/primer-spec), or even [use it today](#usage).*
*Primer Spec is a Jekyll theme that makes long informative web pages easier to read. In addition to aesthetic styling, the theme generates a table of contents displayed in a sidebar. You can [preview the theme to see what it looks like](http://eecs485staff.github.io/primer-spec), or even [use it today](#usage).*

Primer Spec is built on top of the wonderful [Primer theme](https://github.com/pages-themes/primer), 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. (Here are [some](https://eecs485staff.github.io/p1-insta485-static/) [examples](https://eecs280staff.github.io/p1-stats/).)
Primer Spec is built on top of the wonderful [Primer theme](https://github.com/pages-themes/primer), 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. See the [User Showcase](#user-showcase) for inspiration.

## Contents
- [Usage](#usage)
- [Using with Jekyll + MarkDown](#using-with-jekyll--markdown)
- [Using the HTML JavaScript plugin](#using-the-html-javascript-plugin)
- [Users](#users)
- [User Showcase](#user-showcase)
- [Contributing](#contributing)

## Usage
There are two ways to quickly get started using this theme. First, answer this question:
Primer Spec is a Jekyll theme, which means you can start using this theme with [GitHub Pages](https://pages.github.com) right away!

*Do you want to store your long webpage as MarkDown or as HTML?*
1. Add your Markdown/HTML files to the Jekyll site. These are your "webpages".

- *MarkDown*:
Use the Jekyll theme, probably coupled with GitHub/GitLab pages. Jekyll converts your MarkDown files into HTML, and has some other great features to host a website. See [Using with Jekyll](#using-with-jekyll--markdown).

- *HTML*:
Use the plugin script. Simply add a couple of lines to your plain HTML webpage and watch it magically transform in your browser! See [Using the plugin](#using-the-html-javascript-plugin).


### Using with Jekyll + MarkDown
*If you plan to use GitHub Pages, see https://pages.github.com for guides.*

Follow these steps to add MarkDown files that use the Primer Spec theme.

1. Add your Markdown files. Note that files named README.md will be ignored by Jekyll when using a custom theme.
_Pro tip: If you're trying to find inspiration for your project spec, check out our demo spec! Preview it at https://eecs485staff.github.io/primer-spec/ and see its source file [index.md](index.md)._

2. If it doesn't already exist, create a file `_config.yml` in your site's root directory. Add this content to the file:

```yml
remote_theme: eecs485staff/primer-spec
plugins:
- jekyll-remote-theme
```
3. To add the Primer Spec theme to a MarkDown file, add the following at the top of the file:
2. Add Primer Spec to each "webpage" by inserting the following at the top of the file:

```yml
---
layout: spec
---
```

4. (Skip this step if you are using GitHub Pages.) Add the following to your Gemfile:

```ruby
gem "jekyll-remote-theme"
```

5. (Optional) To prevent a heading from appearing in the sidebar, add `{: .primer-spec-toc-ignore }` under the heading. For instance:
3. If it doesn't already exist, create a file `_config.yml` in your site's root directory. Add this content to the file:

```markdown
### This heading appears in the sidebar
Spam spam spam.
### This heading does NOT appear in the sidebar.
{: .primer-spec-toc-ignore }
Spam spam spam.
```

6. If you're using GitHub pages, follow the steps in the [USAGE_JEKYLL file](docs/USAGE_JEKYLL.md#Previewing-GitHub-Pages-locally) to preview your website locally.


### Using the HTML JavaScript plugin
Follow these steps to add the plugin to your plain HTML webpage.

1. Make sure that all sections of your web page are marked by header tags (like `h1`, `h2`, etc.).

2. Place all your main content within a `div` with ID `primer-spec-plugin-main-content` and a dummy `onClick` event handler:

```html
<div id="primer-spec-plugin-main-content" onClick="return true;">
<!-- Your main content goes here. -->
</div>
```yml
remote_theme: eecs485staff/primer-spec
plugins:
- jekyll-remote-theme
```

3. Add the following lines at the top of your file, just after the opening `head` tag:

```html
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://eecs485staff.github.io/primer-spec/assets/css/primer-spec-base.css">
<link rel="preload" href="https://eecs485staff.github.io/primer-spec/assets/js/primer_spec_plugin.min.js" as="script" crossorigin>
```
4. Deploy your site with GitHub pages!

4. Add the following line at the bottom of the file, just before the closing `body` tag:
This repository hosts a Primer Spec site too! The original Markdown content is in [index.md](index.md), and the site is available at [https://eecs485staff.github.io/primer-spec/](https://eecs485staff.github.io/primer-spec/).

```html
<script src="https://eecs485staff.github.io/primer-spec/assets/js/primer_spec_plugin.min.js" crossorigin="anonymous"></script>
```
If you aren't using GitHub Pages, or if you'd like to preview your webpages locally, refer to the [Advanced Usage](docs/USAGE_ADVANCED.md) docs.

Your final HTML file will probably look something like this:

```html
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://eecs485staff.github.io/primer-spec/assets/css/primer-spec-base.css">
<link rel="preload" href="https://eecs485staff.github.io/primer-spec/assets/js/primer_spec_plugin.min.js" as="script" crossorigin>
<title>My long project spec</title>
</head>
<body>
<div id="primer-spec-plugin-main-content" onClick="return true;">
<!-- Main content goes in here. For example: -->
<h1 class="primer-spec-toc-ignore">My long project spec</h1>
...
<h2>Setup</h2>
<h3>Installing Python</h3>
...
<h2>Grading</h2>
...
</div>
<script src="https://eecs485staff.github.io/primer-spec/assets/js/primer_spec_plugin.min.js" crossorigin="anonymous"></script>
</body>
</html>
```

That's it! The page should now display with Primer Spec styling.

## Users
## User Showcase

The Primer Spec theme is currently used by the following courses at the University of Michigan:
- [EECS 280](https://eecs280staff.github.io/eecs280.org/) (Programming and Intro Data Structures). Example [EECS 280 Project 4: Web](https://eecs280staff.github.io/p4-web/).
Expand Down
178 changes: 178 additions & 0 deletions docs/USAGE_ADVANCED.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,178 @@
# Advanced Usage

See the [Primer Spec README](../README.md) for the main usage instructions. This page contains further instructions for more advanced workflows.

## Contents
- [Previewing locally](#previewing-locally)
- [Customizing Jekyll](#customizing-jekyll)
- [Hiding sections from the sidebar](#hiding-sections-from-the-sidebar)
- [Using without Jekyll](#using-without-jekyll)


## Previewing locally
If you'd like to preview your site on your computer (or if you aren't using GitHub Pages), do the following:

1. Follow steps 2 and 3 from the main [usage instructions](../README.md#usage).

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

```ruby
source 'https://rubygems.org'

gem 'jekyll-seo-tag'
gem 'jekyll-remote-theme'
gem 'jekyll-github-metadata'

# 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?
```

3. (Optional) Create a `.gitignore` file in your site directory with the following contents:

```gitignore
# This .gitignore file is for locally-rendered Jekyll sites.
# Locally rendered website
_site
# Other Jekyll files
.sass-cache
.jekyll-metadata
```

4. Ensure that you are using 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`.
```console
$ ruby --version
ruby 2.6.1p33 (2019-01-30 revision 66950) [x86_64-darwin18]
$ gem install bundler
```
5. Install the dependencies.
```console
$ pwd
/seshrs/demo-project
$ bundle install
```
6. 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.
```console
$ pwd
/seshrs/demo-project/docs
$ bundle exec jekyll serve
```
At this point, the HTML files with Primer Spec styling are available in the `_site` directory. (You may move them to a remote webserver if you wish.)
## Customizing Jekyll
Primer Spec will respect the following variables, if set in your site's `_config.yml`:

```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:

```yml
google_analytics: [Your Google Analytics tracking ID]
```

## Hiding sections from the sidebar

To prevent a heading from appearing in the sidebar, add the class `primer-spec-toc-ignore` to a header element.

In Markdown files, this can be achieved by inserting `{: .primer-spec-toc-ignore }` under the heading. For instance:

```markdown
### This heading appears in the sidebar
Spam spam spam.
### This heading does NOT appear in the sidebar
{: .primer-spec-toc-ignore }
Spam spam spam.
```

In HTML files, this can be achieved by adding a `class` attribute to the heading element. For instance:

```html
<h3>This heading appears in the sidebar</h3>
<p>Spam spam spam.</p>
<h3 class='primer-spec-toc-ignore'>
This heading does NOT appear in the sidebar
</h3>
<p>Spam spam spam.</p>
```

### Using without Jekyll
We recommend using Primer Spec with Jekyll because:
- You can store your content as Markdown. Jekyll converts Markdown files to HTML automatically.
- Jekyll applies much of the scaffolding needed for Primer Spec.

However, with some work, it is _possible_ to add Primer Spec styling to a plain HTML page:

1. Make sure that all sections of your web page are marked by header tags (like `h1`, `h2`, etc.).

2. Place all your main content within a `div` with ID `primer-spec-plugin-main-content` and a dummy `onClick` event handler:

```html
<div id="primer-spec-plugin-main-content" onClick="return true;">
<!-- Your main content goes here. -->
</div>
```

3. Add the following lines at the top of your file, just after the opening `head` tag:

```html
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://eecs485staff.github.io/primer-spec/assets/css/primer-spec-base.css">
<link rel="preload" href="https://eecs485staff.github.io/primer-spec/assets/js/primer_spec_plugin.min.js" as="script" crossorigin>
```

4. Add the following line at the bottom of the file, just before the closing `body` tag:

```html
<script src="https://eecs485staff.github.io/primer-spec/assets/js/primer_spec_plugin.min.js" crossorigin="anonymous"></script>
```

Your final HTML file will probably look something like this:

```html
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://eecs485staff.github.io/primer-spec/assets/css/primer-spec-base.css">
<link rel="preload" href="https://eecs485staff.github.io/primer-spec/assets/js/primer_spec_plugin.min.js" as="script" crossorigin>
<title>My long project spec</title>
</head>
<body>
<div id="primer-spec-plugin-main-content" onClick="return true;">
<!-- Main content goes in here. For example: -->
<h1 class="primer-spec-toc-ignore">My long project spec</h1>
...
<h2>Setup</h2>
<h3>Installing Python</h3>
...
<h2>Grading</h2>
...
</div>
<script src="https://eecs485staff.github.io/primer-spec/assets/js/primer_spec_plugin.min.js" crossorigin="anonymous"></script>
</body>
</html>
```

That's it! The page should now display with Primer Spec styling.
Loading

0 comments on commit 2869aea

Please sign in to comment.