Skip to content

eecs485staff/primer-spec

Repository files navigation

Primer Spec logo Primer Spec logo

Primer Spec

A website theme for long informative web pages.

cibuild Nightly Preview

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 live preview

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

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:

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:

And at Tufts University:

  • CS 105 (Programming Languages).

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 seshrs@umich.edu.

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.