zjweiss/primer-spec

A Jekyll theme for sites with content-heavy pages

Primer Spec

A website theme for long informative web pages.

Primer Spec is a Jekyll theme that makes long informative web pages (like project specifications!) 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, 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. See the User Showcase for inspiration.

Contents

• Usage
• User Showcase
• Contributing
• Acknowledgements

Usage

Primer Spec is a Jekyll theme, which means you can start using this theme with GitHub Pages right away!

1. Add your Markdown/HTML files to the Jekyll site. These are your "webpages".

2. Add Primer Spec to each "webpage" by inserting the following at the top of the file:

   ---
   layout: spec
   ---
   

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

   remote_theme: eecs485staff/primer-spec
   plugins:
     - jekyll-remote-theme
     - jekyll-optional-front-matter
     - jekyll-readme-index
     - jekyll-relative-links
     - jemoji
   kramdown:
     input: GFM
   readme_index:
     remove_originals: true
     with_frontmatter: true

4. Deploy your site with GitHub pages!

This repository hosts a Primer Spec site too! The original Markdown content is in index.md, and you can preview the page at https://eecs485staff.github.io/primer-spec/index.html.

Also see the Advanced Usage docs, they describe quite a few tricks including how to:

• Preview locally (especially if you aren't using GitHub Pages)
• Hide sections from the sidebar
• Add Callouts for important information
• Render math expressions with LaTeX
• Highlight lines in code blocks
• Render diagrams with Mermaid!
• Render a sitemap
• (And more!)

You may also want to read the MARKDOWN_TIPS, which has notes on how you can edit your specs to take best advantage of Primer Spec markdown features.

User Showcase

The Primer Spec theme is currently used by the following courses at the University of Michigan:

• EECS 280 (Programming and Intro Data Structures). Example EECS 280 Project 4: Web.
• EECS 285 (Practical Programming in Java). Example EECS 285 Project 3: Wheel of Fortune.
• EECS 485 (Web Systems). Example EECS 485 Project 4: Map Reduce.
• EECS 183 (Elementary Programming Concepts).
• EECS 370 (Introduction to Computer Organization).
• EECS 441 (Mobile App Development for Entrepreneurs).
• EECS 482 (Introduction to Operating Systems).

Students: Would you like to see your course use this theme for their project specifications? Let your course staff know about this theme!

Course staff: If you have questions about how to integrate this theme with your project release workflow, create a discussion, or email [email protected].

Contributing

Interested in contributing to Primer Spec? We'd love your help. See the CONTRIBUTING file for further instructions on how to contribute. Also see the Dev Onboarding file for notes on how the theme works.

For maintenance and release instructions, see Maintenance & Release section of the CONTRIBUTING file.

Acknowledgements

Primer Spec is maintained by Sesh Sadasivam (@seshrs) along with the EECS 485 Staff (@eecs485staff). Bella Kim (@bellakiminsun) contributed to the design, and designed the subthemes.