Jekyll Theme Primer Spec

Markdown Tips

Author: Sesh Sadasivam

Primer Spec is designed to magically provide useful features out-of-the-box with minimal configuration. However, Primer Spec (and Github-Flavored Markdown in general) provides several useful features that can enhance your project specs and make them more useful to students.

In this guide, I describe what I look for when I add Primer Spec to an existing project website. I also point out some lesser-known markdown features that might be useful for your website.

Callouts
Codeblocks
Images
Diagrams
Abbreviations
Keyboard shortcuts
Task Lists (Checklists)
Footnotes

Callouts

Docs: https://eecs485staff.github.io/primer-spec/demo/callouts.html

Look for places where your spec calls out a “pro-tip” or a “hint” — these can be made more prominent by embedding them inside a callout.

## Some section in your spec

Some paragraph text...

<div class="primer-spec-callout info" markdown="1">
**Hint:** Try looking up this documentation...
</div>

You will likely find yourself using the info callout most often. For asides, I like to use the neutral variant. I try to use warning and danger as infrequently as possible.

Codeblocks

Docs: https://eecs485staff.github.io/primer-spec/demo/enhanced-code-blocks.html

Code block titles

Look for code blocks in your spec that could use a “title”. For instance, if the code block represents content in a file, help your students understand the code block’s context by adding the filename as the title.

Create a file named `map.py` with the following content:

```python
def map(input_file, output_file):
  with open(input_file, "r") as input_stream, open(output_file, "w") as output_stream:
    for line in input_stream:
      output_stream.write(line)
```
{: data-title="map.py" }

Highlighting lines

Look for instructions in your spec that ask students to “add a line” to a code block, or “notice” some piece of code. To help make these lines of code stand out, specify which lines of the code block should be highlighted.

Notice how we use a `for` loop to iterate over the lines in the input file.

```python
def map(input_file, output_file):
  with open(input_file, "r") as input_stream, open(output_file, "w") as output_stream:
    for line in input_stream:
      output_stream.write(line)
```
{: data-highlight="3-4" }

The data-highlight attribute is a comma-separated list of line numbers to highlight. You can also use ranges, e.g. 1-3 or 1,3,5-7.

Console blocks (and `pycon`)

Wherever your spec instructs students to “run a command”, use a console block to display the command as well as its output.

Make sure you're using Python 3.8+.

```console
$ python3 --version
Python 3.8.0
```

When rendered, students can click the line number of the command to select just the command text — that way, it’s easy to copy!

The console block also accepts parameters that allow you to customize what counts as a “prompt”. For instance, you can mimic pycon support like this:

```console?lang=python&prompt=>>>,...
>>> from task import MapTask
>>> task = MapTask(
...   input_files=["file01", "file02"],
...   executable="map0.py", output_directory="output")
>>> task
MapTask(input_files=['file01', 'file02'], executable=map.py, output_directory=output)
```

Demo of pycon code block

>>> from task import MapTask
>>> task = MapTask(
...   input_files=["file01", "file02"],
...   executable="map0.py", output_directory="output")
>>> task
MapTask(input_files=['file01', 'file02'], executable=map.py, output_directory=output)

Images

Docs: https://eecs485staff.github.io/primer-spec/demo/images.html

When possible, try to add the class invert-colors-in-dark-mode to your image — Primer Spec will automatically convert your image into dark mode!

![This is my light mode image, but it auto-inverts in dark mode.](./my-image.png){: .invert-colors-in-dark-mode }

OR

<img
  src="./my-image.png"
  alt="This is my light mode image, but it auto-inverts in dark mode."
  class="invert-colors-in-dark-mode" />

If you want to create two different versions of your image, use the color-mode directives to only display images in a certain color-mode.

Diagrams

Try to use Excalidraw or Mermaid for creating diagrams. I strongly prefer Excalidraw for its versatility, but I think Mermaid works well when creating flow charts.

If you end up using Excalidraw, don’t forget to use the file extension .excalidraw.png or .excalidraw.svg. Primer Spec identifies these images and auto-optimizes them for dark mode.

Abbreviations

When you’re using an abbreviation in a spec and you’d like to help students recall its definition, it might make sense to display its expansion in a tooltip. Define abbrevations like this:

We will be using the <abbr title="Last In First Out (like a stack)">LIFO</abbr> while manipulating this array.

You can also define a global abbreviation anywhere in your markdown file — all occurrecnces of the abbreviation will show a tooltip. (Docs)

We'll be creating an HTML page. Then we'll use a static file server to serve the HTML file when someone visits our site.
example.

*[HTML]: Hyper Text Markup Language

Keyboard shortcuts

Keyboard shortcuts look visually distinct, akin to keys on a keyboard. Surround keyboard shortcuts with <kbd> and </kbd> tags.

To interrupt and abort a process, press <kbd>Ctrl+C</kbd>.

Task Lists (Checklists)

Task lists are lists of checkboxes (aka checklists). They’re a great way to help students keep track of their progress towards completing the spec. Primer Spec will even remember what boxes a student has checked so far!

I recommend including project checklists in the beginning or at the end of your spec. For instance:

## Submission checklist

- [ ] Implement the mapper in `map.py`.
- [ ] Implement the reducer in `reduce.py`.
- [ ] Upload your code to the autograder.

For a real-world example, check out EECS 280’s coding practices checklist: https://eecs280staff.github.io/p2-cv/#appendix-c-project-2-coding-practices-checklist

Footnotes

Docs: https://kramdown.gettalong.org/quickref.html#footnotes

I don’t personally use footnotes in specs, but I think they have their use-cases. A footnote consists of a usage (which looks like a citation reference number) and footnote text, which is included at the bottom of the page. For instance:

Kramdown lets you define footnotes[^kramdown-footnotes] that show up at the bottom of the page.

[^kramdown-footnotes]: This is the footnote text. It appears at the bottom of the page, even if it's defined in the middle of a markdown file.