Skip to content

Latest commit

 

History

History
311 lines (226 loc) · 9.28 KB

USAGE_ADVANCED.md

File metadata and controls

311 lines (226 loc) · 9.28 KB
Raw

Advanced Usage

See the Primer Spec README for the main usage instructions. This page contains further instructions for more advanced workflows.

Contents

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.

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

    source 'https://rubygems.org'

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

# The following plugins are enabled on GitHub Pages without a _config.yml.
gem 'jekyll-optional-front-matter'
gem 'jekyll-readme-index'
gem 'jekyll-relative-links'
gem 'jekyll-default-layout'
gem 'kramdown-parser-gfm'

# GitHub Pages doesn't support jekyll 4.0 yet
gem 'jekyll', '<4.0'

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

    # 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.

    $ ruby --version
ruby 2.6.1p33 (2019-01-30 revision 66950) [x86_64-darwin18]
$ gem install bundler

  5. Install the dependencies.

    $ 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.

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

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]

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:

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

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

Page configuration options

The following configuration options can be specified in the "front-matter" of your page, in the same place that you specify the page's layout. For instance, to disable the Primer Spec sidebar and render LaTeX expressions, modify your page to look like this:

---
layout: spec

# Disable the Sidebar completely
disableSidebar: true
# Render LaTeX expressions
latex: true
---
...your webpage's MarkDown/HTML content...

Primer Spec supports the following page configuration options:

disableSidebar: Boolean

Disable the the sidebar completely. (The Table of Contents will also not be generated.) Defaults to false.

Example page: http://eecs485staff.github.io/primer-spec/disable-sidebar.html

hideSidebarOnLoad: Boolean

Prevent the sidebar (with table of contents) from appearing when a user loads the page. Defaults to false.

Example page: http://eecs485staff.github.io/primer-spec/hide-sidebar-on-load.html

latex: Boolean

Render Mathematical expressions using LaTeX syntax and rendering. Defaults to false.

LaTeX can be rendered inline or as separate blocks. Here is an example of a MarkDown file with LaTeX typesetting:

---
layout: spec
latex: true
---

LaTeX can be inlined ($$ \forall x \in R $$) or as a separate math block.

$$
-b \pm \sqrt{b^2 - 4ac} \over 2a
$$

For a full list of supported LaTeX commands, see the MathJax docs.

NOTE: LaTeX rendering only supports MarkDown that was parsed using the GFM Kramdown parser. See the Usage instructions for the correct contents for _config.yml.

Site configuration options

The following configuration options can be specified in the _config.yml file of your site, under the primerSpec key. For instance, to always hide the Primer Spec sidebar when users visit your page, modify your page to look like this:

# REQUIRED configuration options, as specified in the Primer Spec README
remote_theme: eecs485staff/primer-spec
plugins:
  - jekyll-remote-theme
  - jekyll-optional-front-matter
  - jekyll-readme-index
  - jekyll-relative-links
  - jekyll-default-layout
kramdown:
  input: GFM
readme_index:
  remove_originals: true
  with_frontmatter: true

# OPTIONAL site configuration options
primerSpec:
  defaultSubthemeName: modern
  # Other site configuration options can go here too.

Primer Spec supports the following site configuration options:

defaultSubthemeName: String

Specify the default subtheme name. This subtheme will be applied for first-time site visitors. Defaults to default.

defaultSubthemeMode: String

Specify the default subtheme mode. This subtheme will be applied for first-time site visitors. Defaults to system.

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:

    <div id="primer-spec-plugin-main-content">
  <!-- Your main content goes here. -->
</div>

  3. Add the following lines at the top of your file, just after the opening head tag. Replace <version> with the appropriate version in the assets/ directory.

    <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/<version>/css/primer-spec-base.css"
/>
<script
  src="https://eecs485staff.github.io/primer-spec/assets/<version>/js/primer_spec_plugin.min.js"
  crossorigin="anonymous"
  defer
></script>

  4. Add the following lines at the top of the body tag.

    <div id="primer-spec-top"></div>
<div id="primer-spec-app-container" onclick="return true;"></div>

Your final HTML file will probably look something like this:

<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/<version>/css/primer-spec-base.css"
    />
    <script
      src="https://eecs485staff.github.io/primer-spec/assets/<version>/js/primer_spec_plugin.min.js"
      crossorigin="anonymous"
      defer
    ></script>

    <title>My long project spec</title>
  </head>
  <body>
    <div id="primer-spec-top"></div>
    <div id="primer-spec-app-container"></div>
    <div id="primer-spec-plugin-main-content">
      <!-- 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>
  </body>
</html>

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