From 2869aea16ae9d8c1d00436af018b90dc63df09c2 Mon Sep 17 00:00:00 2001 From: Sesh Sadasivam Date: Sun, 15 Dec 2019 13:37:50 -0800 Subject: [PATCH] Refocus README on Jekyll Usage 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. --- README.md | 121 ++++------------------------ docs/USAGE_ADVANCED.md | 178 +++++++++++++++++++++++++++++++++++++++++ docs/USAGE_JEKYLL.md | 109 ------------------------- 3 files changed, 193 insertions(+), 215 deletions(-) create mode 100644 docs/USAGE_ADVANCED.md delete mode 100644 docs/USAGE_JEKYLL.md diff --git a/README.md b/README.md index 76f3cd91..645e86ea 100644 --- a/README.md +++ b/README.md @@ -2,46 +2,21 @@ [![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 --- @@ -49,87 +24,21 @@ _Pro tip: If you're trying to find inspiration for your project spec, check out --- ``` -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 -
- -
+ ```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 - - - - - ``` +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 - - ``` +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 - - - - - - - - My long project spec - - -
- -

My long project spec

- ... -

Setup

-

Installing Python

- ... -

Grading

- ... -
- - - -``` - -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/). diff --git a/docs/USAGE_ADVANCED.md b/docs/USAGE_ADVANCED.md new file mode 100644 index 00000000..fd420c0f --- /dev/null +++ b/docs/USAGE_ADVANCED.md @@ -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 +

This heading appears in the sidebar

+ +

Spam spam spam.

+ +

+ This heading does NOT appear in the sidebar +

+ +

Spam spam spam.

+ ``` + +### 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 +
+ +
+ ``` + +3. Add the following lines at the top of your file, just after the opening `head` tag: + + ```html + + + + + ``` + +4. Add the following line at the bottom of the file, just before the closing `body` tag: + + ```html + + ``` + +Your final HTML file will probably look something like this: + +```html + + + + + + + + My long project spec + + +
+ +

My long project spec

+ ... +

Setup

+

Installing Python

+ ... +

Grading

+ ... +
+ + + +``` + +That's it! The page should now display with Primer Spec styling. diff --git a/docs/USAGE_JEKYLL.md b/docs/USAGE_JEKYLL.md deleted file mode 100644 index 7fc97f7c..00000000 --- a/docs/USAGE_JEKYLL.md +++ /dev/null @@ -1,109 +0,0 @@ -# Usage with Jekyll - -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-github-pages-locally) - - [Part 1: Create the dependency files](#local-setup-part-1-create-the-dependency-files) - - [Part 2: Install the dependencies](#local-setup-part-2-install-the-dependencies) -- [Customizing Jekyll](#customizing-jekyll) - - -## Previewing GitHub Pages locally -If you'd like to preview your site on your computer do the following. - -### Local Setup Part 1: Create the dependency files - -1. Create a file named `Gemfile` in your project root directory. Add this to the file: - - ```ruby - 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? - ``` - -2. Create a `.gitignore` file in your GitHub Pages 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 - ``` - -### Local Setup Part 2: Install the dependencies - -1. 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. - - ```console - $ ruby --version - ruby 2.6.1p33 (2019-01-30 revision 66950) [x86_64-darwin18] - $ gem install bundler - ``` - -2. Install the dependencies. - - ```console - $ pwd - /seshrs/demo-project - $ bundle install - ``` - -3. 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 - ``` - -## Customizing Jekyll - -### Configuration variables - -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] -``` - -### Stylesheet - -If you'd like to add your own custom styles: - -1. Create a file called `/assets/css/style.scss` in your site -2. Add the following content to the top of the file, exactly as shown: - ```scss - --- - --- - - @import "{{ site.theme }}"; - ``` -3. 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: - -1. [Copy the original template](https://github.com/pages-themes/primer/blob/master/_layouts/default.html) from the theme's repository
(*Pro-tip: click "raw" to make copying easier*) -2. Create a file called `/_layouts/default.html` in your site -3. Paste the default layout content copied in the first step -4. Customize the layout as you'd like