The above title becomes the tutorials first header so an introduction to the tutorial page should be given here before any more headers are created.
In this tutorial we will discuss best practices for creating Make School tutorials. We'll cover:
Curriculum development tools
Pacing the content
See the structure of this repository for the general tutorial structure. Each tutorial contains:
tutorial.yaml, contains metadata for the tutorial
Folders for each tutorial page
title (56 characters maximum): a slug for the tutorial will be generated from title. The title must be unique from all other Make School tutorials.
cover: local file reference to cover image name -- displayed when viewed from /tutorials and at the top of each tutorial page. Should always be named cover.png and placed at the root of the tutorial. Do not change this.
teaser_text (150 characters maximum): displayed when viewed from /tutorials.
Tutorial page folder structure
Each folder represents a tutorial page and should contain the page content.md and an assets folder containing any assets the page needs.
Naming tutorial page folders
The folders should be named with the format P[page-number]-Page-Slug where:
[page-number] is a double digit number from 00 through 99 representing the page order
Page-Slug matches the slug defined in the tutorial page's content.md
Each page's content is defined using Markdown in content.md. The top of content.md has the format:
Page Title becomes the first header and is used in the tutorial's table of contents
page-slug is a unique (to the tutorial) slug representing the page's title
... is the actual content of the tutorial page
All local assets (png, gif, zip, mov, mp4, etc) for a pages should be inside the assets folder. Give assets meaningful names and avoid using spaces. Be careful with asset sizes! Short screencasts can be local but host large videos on Youtube or S3.
This are generated by the website importer. They should not be modified or copied from other repositories.
Curriculum development tools
You should use Atom for writing markdown. Once installed, add the ms-markdown-preview package. Contact Dion if you do not have access to this repository.
This will allow you to see how your tutorial will look on the website without having to import it. Always check the preview before pushing changes to a tutorial!
Use # to create new headers.
# This is an h1 header, use to partition page into steps## This is an h2 sub-header### This is an h3 sub-header#### This is an h4 sub-header
Each h1 header creates a "Mark Complete" button for content between it and next h1 header. Make sure there is a full "step" of content for each h1 header.
Italics can be done with underscores. Use italics for the name of applications and introducing new concepts.
Bold can be done with asterisks. Use bold for names of buttons.
Bold-italics can be done with asterisks arpund underscores.
Strikethrough can be done with two tildes.
Inline code references (file names, class names, function names, etc) can be made with back-ticks, code blocks are discussed below.
Relative links to files in the same works on makeschool.com but the links will not do anything when clicked from ms-markdown-preview.
Images syntax is similar to links and will work with most image types (including gif). Images should be located in the page's assets folder and referenced locally. This syntax transforms into an HTML image tag.
Make sure that every image has both alt and title text defined. Both are important for SEO. Alt text is displayed when a user is has images disabled. Title text is displayed when a user hovers over the image.
Other embedded assets
The renderer has overhauled the image syntax for embedding MP4 videos, YouTube videos, and PDF files.
The following syntax will embed a YouTube video into the tutorial. The video must be embeddable (see video's settings on YouTube).
The following syntax will embed an MP4/MOV video with controls. Videos can be referenced with URLs or relative links if they are included in the repository. This works great with short screencasts made with QuickTime.
The following syntax will embed a PDF for viewing in-line. PDFs can be referenced with URLs or relative links if they are included in the repository.
An iOS Development Summer Course
Design, code and launch your own app. Locations in San Francisco and Asia