git clone https://github.com/dgmd/snippet.lovecd snippet.lovegit checkout gh-pagesjekyll serve- Navigate to
http://localhost:4000to see the site.
What follows is a brief outline of how to add a snippet. Please read through it in its entirety before creating a snippet, there are some subtleties in capturing a screencast and writing up your snippet to be aware of.
First: Create a new folder within /snippets; name it something short-but-summarizing, like css-positioning. Everything below is included within this folder:
background.png— a square PNG file. This file will be used as the background to represent your snippet on the homepage.screencast.mp4— anmp4file less than 100MB in sizecode.html— the entry point for the actual snippet (it may be the only file for the snippet). If you have multiple files to include in your snippet, please be sure to look at the required YAML front-matter forindex.md.extensions.md— A numbered list of suggested extensions, ordered by increasing complexity. Include any references which are uniquely pertinent to an extension here.readings.md— A selection of references, videos, or related readings covering the same topic as the snippet.index.md— An empty markdown file containing only YAML front-matter. The front-matter should define at least the following variables:titlesubtitlelayout: snippet-summarycategory: snippetscreencastshould betrueif there is a screencast to embed orfalseotherwisedemoDescriptionshould contain a short, one sentence description of how to use the demo/what it does.filesshould only be included if you have multiple files to include.filesshould be a YAML Collection of filenames (see Example 2.3 here)
When you record your screencast, you can do so using QuickTime Player:
- Open QuickTime Player, select
File > New Screen Recording - Make sure that the proper microphone is selected from the dropdown menu/arrow next to the red, record button.
- Select the region of your screen excluding the menu bar for recording.
- Record your screencast, keeping it to less than fifteen minutes.
- Use the
Edit > Trimcapacity to trim the screencast to just the time you need after ensuring it looks and sounds reasonable. - Save your screencast as
screencast.movfile. brew install ffmpegif you don't have it already- Convert the MOV file to an MP4 (unfortunately, the QuickTime
movfiles produced do not cooperate with Google Chrome) by running the commandffmpeg -i screencast.mov -acodec copy -vcodec copy converted-screencast.mp4to convert the file to an MP4. - Download Handbrake, open your
converted-screencast.mp4file, select the "Web-optimized" option, and use Handbrake to re-encode the MP4 and save it asscreencast.mp4. - Ensure
screencast.mp4is less than 100MB (it should be much less, ~25MB); GitHub doesn't permit larger files, and it's a pain to remove too-large files from a repository's history. - Place
screencast.mp4in your snippet folder.
Note that if you're testing this site locally, jekyll will choke on large movie files and refuse to serve them. This will present as a <video> tag failing to load, but throwing no error (i.e. the play button will be ghosted).
code.html is the snippet itself. For boring reasons, lines should be wrapped to ensure that they aren't longer than 80 characters.\
For multiline comments, this means that the comments need to be "hard-wrapped"—i.e. a newline character must be inserted at 80 characters. Fortunately, you don't need to do this by hand.
If you're using Sublime Text, you can follow these steps:
- Install the
Sublime-Wrap-Plusplugin via PackageControl. - Write your comments as your normally would (you'll notice that in the includion of
code.html, the multiline comments don't wrap). - After you're done with your comments, put your cursor in each comment and run
Wrap Lines(you can do this viaCmd+Shift+P > Wrap Linesor via the default keyboard shortcut,Cmd+alt+q).
All the files you create ending in .md will be interpreted as GitHub Flavored Markdown
After you have added all of these files, please be sure to build and test the site locally by running jekyll serve from the top level of the directory and navigating to http://localhost:4000 to see that the site behaves as you expect.
After you've verified that it does, please package your snippet addition as a single commit and then git push them to preview them on the live site.
If you find an issue with a snippet, please email us and file an issue.