Authoring Guidelines

The following are guidelines for authoring content in Guides.

Style your content using Markdown

You can style your content using Markdown, a simple formatting language that is easier to use than HTML. You can embed HTML snippets in Guide content if you need a feature that is unavailable in Markdown.

Load the Demo Guides and Assessments project to learn more about authoring with Guides

Demo Guides and Assessments is an example project you can use as a tutorial to learn more about creating Guides. If you do not see it in the My Projects tab of your Navigation Pane, you can load it using the instructions below.

  1. Click the Starter Packs area in your Navigation Pane.

  2. Search for Demo Guides and Assessments.

  3. Click Use Pack and then Create to install it to your Codio account.

Using Media assets in your Guides

When creating a guide, you will often be working with images, video and other media. We recommend the following.

  • Images should be placed in the .guides/img folder. You can create sub-folders for organizational purposes.

  • Videos should be hosted on a 3rd party platform such as YouTube or Vimeo. You can embed these using regular HTML embed tags provided by those platforms.

  • Web based media such as Google Doc documents can be embedded using regular HTML embed tags provided by those platforms.

Use callout blocks to highlight important information

Callout blocks provide icons and highlighted backgrounds for various categories such as : Important, Info, Challenge, Topic, Definition, Meetups, Headline, Hackathon, Create, Calendar, Growth Hack, Debugging, Cross Discipline and more.

Refer to the Callout section of the Demo Guides and Assessments project loaded to your My Projects area, if not loaded see instructions above.

Don’t make pages too long

If the topic is a long one, consider breaking it up into several pages. This avoids the need for lots of scrolling and allows students to access information in manageable chunks.

Use hidden folders to organize your code samples

You can place code samples for each page in separate directories and then you can show only the relevant folders for a specific page.

Click here for more details on folder hiding.

Assessments may be used to test student knowledge

Codio offers a range of manually and auto-graded assessments. When used in content, assessments provide students with challenges and exercises that help reinforce what they have learned.

When used in a course, assessments provide teachers with a way to monitor student progress across a course using the teacher course dashboard.

Many of Codio’s assessment types (code tests, multiple choice questions, text, fill in the blank and list-based) are auto-graded, saving teachers time and offering students instant feedback on the correctness of their answers.

You can also use the free-text assessment type for answers that require a typed answer that will be manually graded by faculty. Free text assessments support Latex, and can be used to respond to math questions and graded.

You can save your assessments in a library for use in other assignments. See here for more information on this. Codio provides an extensive library of assessments you can use or modify. See here for more details

Use panel layouts to organize your instructional materials

The editor lets you create different panel layouts for each page of your guide content.

Click here for more information on panel layouts.