Content Creation Guide

Warning

This page no longer applies for the summer.

This page describes the workflow for creating content for the Creative Computing Cookbook project.

See here for a minimal example. Switch to "Code" view (or download) to get the markdown code.

Please clone or download the repository and edit locally; don't edit directly on GitHub.

Where to create

The current setup is that there are 2 categories, builds and foundations; each page needs to belong to either one. (It is possible for me to specify more categories as needed.) You can see the categories in the src directory.

File name

Lower-cased version of the title with spaces replaced with hi-fens. It could be shortened while remaining readable.

Front matter

At the front of each markdown file is the front matter.

---
title: 'Servo Motor'
tags: ['test2', 'test3']
shortDesc: 'An interactive art installation'
related: ['Corporate in Red']
thumbnail: '/images/servo.png'
meta:
  desc:
    "A servo motor is like a tiny robot motor that can turn to a specific position. Here's how you can program it in Arduino!"
---

How to specify an "array"

• Empty array: []
• Array with one item: ['Item']
• Array with two items: ['Item 1', 'Item 2']

so on so forth.

title

Title of the page, in proper casing. This will be displayed on the top of the page.

tags

An array of tags. Each tag should be in proper casing. Note that Builds and Foundations tags are implied from the directory and thus should not be specified again. This is used for the filters on the home page.

shortDesc

Added April 18: A short description to be shown in card items (home, "related pages", section, etc.), under the page title. It should be short, preferably less than 5 words or so.

related

An array of titles of related pages, which is displayed at the bottom. This can be empty. Note that each item must exactly match the title property of the front matter of the pages you want to link to.

thumbnail

A path to an image (gif is an image, mp4 is not). This is displayed under the title in the page, and as part of the page's card item on other pages (home, "related pages" section, etc.) This can be either:

• A path relative to /src/ if you choose to upload the image onto the repository, or
• Any arbitrary URL that links to an image, as long as it is accessible to the public (put your URL in your browser's incognito mode to check).

Edited May 6: This is mandatory and cannot be left empty!

meta

desc can just be a one-line summary of the page. It is not displayed on the page itself, instead it will be shown when someone shares the page on social media. This is optional.

Content

Use Markdown wherever possible. Also see the Markdown Reference. You can also experiment with the text in Slack or Discord.

Some components that I have specified are:

Collapsible

<collapsible title="Collapsible title (Markdown not allowed)">
Collapsible content (Markdown allowed)
</collapsible>

Step

A simple two-column component intended to illustrate a step in a procedure.

If you want image on the left side (see thumbnail for information on image path):

<step img="Path to image">
Text for the right side (Markdown allowed)
</step>

If you want text on the left side instead:

<step>
<div slot="left">Text for the left side (Markdown allowed)</div>
Text for the right side (Markdown allowed)
</step>

Inline code

Same as most Markdown setups:

`inline code`

Looks like inline code.

There is no highlighting. Use that if you want to refer to a variable or a line of code inside standard text.

Code blocks

In most Markdown setups (like Discord) you can specify a language in a code block, like this:

```arduino
#include "arduino/Arduino.h"

int main(){
  init(); //Don't forget this!
  pinMode(13,OUTPUT);
  while(1) {
    digitalWrite(13,HIGH);
    delay(50);
    digitalWrite(13,LOW);
    delay(1700);
  }
}
```

and the code will be highlighted as Arduino code, as specified on top.

There are some extra options here:

• If a forward slash is added after the specified language (eg. arduino/), then line numbers will be added before each line.
• If some range of line numbers is added after the slash (eg. arduino/5-10), then on top of the line numbers, the specified lines will be highlighted in yellow.

Updated April 11: if the code contains any statement that contains angle brackets (like import <Servo.h>) then you must use

<syntax-highlight language="arduino">
code here...
</syntax-highlight>

The extra options above can be specified in the language property.

Parsons (optional)

Added April 21st.

Note : This component will not be required for every markdown page.

The Parsons Problems component allows you to create interactive code rearrangement exercises where learners must place code blocks in the correct order.

Basic Usage:

<script>
    var initial = 
        `// Your original code here...
         // For example: 
        void setup() {
            pinMode(LED_BUILTIN, OUTPUT);
        }
        void loop() {
            digitalWrite(LED_BUILTIN, HIGH);
            delay(1000);
            digitalWrite(LED_BUILTIN, LOW);
            delay(1000);
        }`;
</script>
<parsons></parsons>

The component will automatically:

1. Parse your code in logical blocks
2. Shuffle the blocks
3. Present them as an interactive drag-and-drop interface

Arduino-Trinket split

Added April 18.

<arduino-trinket-split>
    <div slot="arduino">
    Arduino content here...
    </div>
    <div slot="trinket">
    Trinket content here...
    </div>
</arduino-trinket-split>

Only shows the relevant section depending on the value of the toggle above. You could use multiple of them on the same page, and things that are shared across the two should be outside of this component.

Upload your changes

If you are familiar with Git, try to group your recent changes in one commit. The current workflow is to push to your fork and then ask me to merge them; this workflow is not ideal and certainly will be changed in the future.

If you are not familiar with Git, you should learn (it is pretty much a prerequisite for any serious computer science work :) you can play with Oh My Git!, I've heard it's a good intro to Git)... Jokes aside, here's what you can do:

• Navigate to either the builds or foundations folder;
• Add file => Upload files;
• Drag all your new & edited markdown files in that specific folder into the box;
• Describe your changes and commit.

Check

Wait a few minutes for me to manually merge your changes, then go to https://creativecomputingcookbook.github.io/cwp-11ty/. Your page should be in the prescribed category.

Don't hesitate to talk to me if anything is not working as expected, I can point you to the right direction.

ASIDE: how to convert mp4 to gif

1. https://ezgif.com/video-to-gif
2. After uploading, set end time to 60, size to 540xAUTO, and frame rate to 5. Hit convert.
3. Press "Frames" and remove the title card by hitting skip on all such frames (because it's rather pointless if it's used as thumbnail). Hit "Make a GIF!"
4. Press "Crop" and set the size to 4:3, then click & drag to select. Make sure the person is centered. The height can be the full height of the image. Hit crop.
5. Press "Optimize" and hit optimize.
6. Save.