## Introduction

Codio Guides is a powerful authoring tool creating rich tutorial and instructional content as well as assessments. Here are a few of the key features.

### Where is it?

You can launch the content authoring from

• The button at the top of the file tree as shown below

## Project, course assignment or book?

Before you start to author content you should be aware of the three different places you can create content using guides. Let's look at each of the three ways to create content and why you might choose each one.

### Projects

A project is simply a standalone Codio box. It may or may not have guides content. Projects are to be found in the Projects page on the main Codio dashboard.

You would want to choose a project as the place to create your content if you have individual, ad hoc assignments or examples that do not constitute more extensive coursework or are not part of a larger series of associated projects.

A project can be assigned to a course at any time. All the students in that course will then be able to access that project and its content.

There are drawbacks to using projects to assign to students. If you have related projects and the number of projects grows, it can be hard to quickly find a project you want to assign to a course. There is also no way to arrange your projects into chronological order. Courses and books offer excellent solutions to this organizational problem.

### Assignments

An assignment is essentially the same as a project. The only difference is that your project assignments are located in the courses area in the main Codio dashboard and accessible to other teachers who can edit the item and to students in the course. Assignments are very easy to locate as they are tidily organized within the course module they belong to. You can also arrange your assignments within a course module.

You would typically use an assignment if either of the following apply.

• You have a logically related series of projects that you want to assign to a student that form a course module.
• You have a collection of assessments relate to a course that are used for homework, lab assessments, projects etc.

A course allows you to subdivide your course into modules and then chronologically arrange your assignments within your modules. When you create a course, you have to create at least one module. A module does nothing special other than contain assignments and are simply a nice way to group your assignments.

There is one minor drawback to project based assignments that you should be aware of. If students are working with a project assignment and want to look at tutorial content that is contained in another assignment, they have to switch assignments. This can take several seconds and can be irritating during a revision phase when they want to frequently switch assignments. For this reason, we created the book, which we will look at next.

### Book assignments

A book is intended to replicate a hard-copy book. It contains a lot of content, often an entire course of content. Let's look at the case of a course called Introduction to Java. If this was a regular book, it might contain 500 pages. If you used project assignments to create this content, you might end up with a very large number of assignments, say 50. As we mentioned above, when students are revising and want to randomly move between different assignments to review content, the can get frustrated by the time it takes to switch assignments.

A book addresses this issue by offering sophisticated table to contents management with nested chapters and sections. As a result, you can put all of your content into a single book, with a single box running in the background.

However, faculty will still often want to teach a course based on a book. To do this, you use a course but rather than creating a project assignment, you create a book based assignment. This allows you to point to any parts of a book for that assignment.

### Book or project assignment?

It can still be a little confusing whether you should use a book based assignment or a project assignment, so here are some typical use cases.

• Project assignments - use when you have a collection of assessments with no or minimal tutorial content. Best used for homework or lab type assessments. If a student is not going to regularly switch assignments in a single session.

• Book assignments - use for tutorial content, examples and non-critical assessments.

Note that you can mix both book and project assignments in a course.

## Author and student views

The experience when authoring differs from that of a student. Students are not able to view the authoring tools. When they start a assignment or project, if there is content present, it will automatically be shown. The author can also specify whether the student is able to close the content or not.

If you are an author, you will often want to view the content as a student will see it.

### Editing

Only an author is able to edit the content. Students and users with read-only rights will not be able to. Click here for details on page editing.

### Preview

You can press the preview button in the top right area of the edit pane. This will switch to preview mode. You can then switch back to editor mode by pressing the Editor button.

You can also start the preview mode from the Tools->Guide->Play.

Finally, there is also a button at the top of the file tree that launches the content.

To simplify the educational process for students, the top menu can be customized to remove options from students that they cannot override.

Please note that only students will see this. Teachers previewing the assignment will not see the customization. If you wish to check this, the test student accounts can be used

Through a .codio-menu file, a teacher can specify what menu items should be hidden. Example:

{
"Logo": false, // hides the Codio logo
"Codio": false, // hides the Codio menu dropdown
"Project": {
"Permissions": false // hides the Permissions option in the Project menu dropdown
},
"Help": false, // hides the Help menu dropdown
"Run": false, // hides the Run menu dropdown
"Preview": false, // hides the Preview menu dropdown
"Debugger": false, // hides the Debugger menu dropdown
"Status": false // hides the Status icon, user Avatar, user name and exit button
}


Be aware that if setting Status=false, students will need to use the 'Back to Dashboard' button shown on the last page of the guides to return to their dashboard area

Menu items that the student will see:

Students will not see the .codio-menu file to be able to edit/change it.

### Player Options

When the content is rendered to a student, various options can be controlled

• The Collapse table of contents button allows the user to collapse the content pane to provide larger working area if required. This option will not show if the page layout is One Pane
• Navigation Buttons allows the user to navigate forward/backward in the guide.
• Settings allows the user to view the assignment as a teacher (e.g. show solution information hidden to students) change the Theme (light/dyslexic), Mark as Complete, change the font size, reset both the theme and fonts, to restore the current files (see below) and to access Code Comments. See Dyslexia Support section
• Show/Hide Section List Hamburger Icon allows the user to show/hide the section list.

#### Restore current files

The Restore Current Files feature is a great way to reset/restore any files on that page to its initial state after hacking sample code around. Files can be restored from the menu as shown below.

Once you are in the Codio IDE, you are able to create and manage content. There are two ways to access the Codio Guide.

• Press then right arrow at the top of the file tree.

• From the menu, select Tools->Guide->Edit.

### Editing page content and actions

Please refer to the following pages for details in how to edit page content and control page actions.

• Page Editing for details on how to edit a pages content using markdown or HTML, hiding folders and other actions.
• Settings and page actions : Opening and closing files, panel configuration and other settings

### Editing content

The image below highlights the main components of the editing page.

To open and close the table of contents, press the Hamburger Icon at the top right. From here you can add and organize content.

### Chapters, sections and pages

A guide is comprised of pages organized into chapters and sections. A chapter is a top level item only. Sections can be placed at any location and nested to any depth.

You can add a new chapter, section or page by

### Adding content to a chapter or section

By default, chapters and sections are passive and do not have page content assigned to them. However, you can add content by right-clicking the item and then selecting Add content from the menu.

If you want to reverse the procedure, you right click and select Remove content.

### Multiple selection

You can multi-select pages as follows

• Select an item then shift+click on a latter item to select all pages between the two items. This only works for items at the same level.
• Use ctrl+click (PC/Linux) or cmd+click (Mac) to multi select individual pages.

### Drag and Drop

It is very important to understand how drag and drop works within a table of contents as it is very powerful but can be confusing if you don’t understand that drop process. Drag and drop works with individual or multiple selected pages.

What is unusual about our drag and drop support is that the destination folder location is determined by where you drop.

• If you drop in the top portion of the target item, the selection will be dropped above it at the same level.
• If you drop in middle portion of the target item, the selection will be dropped within it if the target is a section.
• If you drop in the lower portion of the target item, the selection will be dropped below the target at the same level.

## Page editing overview

To create new content or to edit existing content, go to the Tools->Guide->Edit menu option.

Use the layout modes to switch between editor, preview, and split view modes.

When in preview mode, you can quickly switch back to editor mode by selecting the Editor button:

Video: Editing Existing Guides Content

### Anatomy of the content editor

Below is a screenshot of the editor with the main components highlighted.

### Editor settings

#### Page

• Layout allows you to specify the panel layout you want to choose for this section,
• Show Folders allows you to define specific folders in your project that you wish to be visible when the current section is displayed,
• Close Tabs allows you to close all tabs open from previous section,
• Set Section as Chapter allows you to set the section as a chapter in your content,
• Teacher Only allows you to show content that only teachers are able to see.
• Content Type allows you to write your content in either Markdown or HTML

#### Open Tabs

This allows you to specify:

• which files you want to automatically open when the current section is displayed,
• Preview (including external websites),
• Open a Terminal window (including running a terminal command),
• which lines (if any) you wish to highlight within each file.

#### Assessments

This allows you to set up assessments.

#### Media

This allows you to play audio files within your project.

#### Global

• Scripts allows you to point to one or more .js files in your project (usually you would have this somewhere within the .guides folder) that is run when the page is shown. This is especially useful when interacting with a button in a page of content.
• Theme allows you to select the default theme for people viewing the content. We currently have a light theme and will be adding a dark theme shortly. Dyslexic users can also choose a special theme from the Settings drop down in the content player.
• Lexicon Topic if you use this option, an icon will appear in the toolbar that will load the Lexikon window with the selected topic automatically selected. Students can still access the Lexicon from the Tools>Lexicon menu (unless of course you are restricting the top menu available to them)
• Suppress page numbering allows you to suppress the section page numbers when in Play Mode.
• Hide Menu allows you to hide the main Codio menu items in the IDE (Codio/Project/File/Edit etc) when the assignment is run in a course.
• Allow guide to be closed allows students to be able to close the content. It can be restarted by selecting the Start icon in the file tree:

• Use mark as completed see Student submission options for more information
• Collapsed on start starts the assignment with the guides pane collapsed. Students can show the content clicking on the hamburger icon on the right
• Hide Section List hides the sections list in your content for the students.
• Hide Back to Dashboard button hides this button that would otherwise show on the last page of the guides.
• Protect Layout prevents students from closing files in tabs.

## Authoring guidelines

Here are some guidelines for creating good quality content.

### Markdown

The best way to author content is using markdown. It is extremely easy to write content that renders very nicely and without having to fiddle with HTML. You can embed HTML snippets into a markdown as well where you need full control.

We have a Cheat Sheet project that you can use to see the full capabilities. To copy this starter pack into your own account, please click here. You should select the Use Pack option to create the project.

### Courses and Books

We strongly recommend that when you are creating content at scale then you have a thorough understanding of the differences between projects, course assignments and books before starting.

### Media assets

When creating a book or 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 as available from those platforms.
• Web based media such as Google Doc documents can be embedded using regular HTML embed tags as available from those platforms.

### Callout blocks

Our markdown supports the use of special callout blocks. These provide icons and highlighted backgrounds for various concepts such as : Important, Info, Challenge, Topic, Definition, Meetups, Headline, Hackathon, Create, Calendar, Growth Hack, Debugging, Cross Discipline and more.

Please refer to the Callout section of the Books Cheat Sheet. If you have not done so already, copy this starter pack into your own account. You should select the Use Pack option to create the project.

### Don't make pages too long

Again, this depends on your intended audience but try to keep each page reasonably brief. If the topic is a long one, you may want to break it up into several pages. This prevents lots of scrolling and allows students to digest information in manageable chunks.

### Hidden folders

Your content will often want to show code samples. Codio's recommended approach is to put each set of code samples into a dedicated folder. Then, using the page settings, you can specify this folder with the consequence that all non-specified folders are hidden from view in the file tree (if you choose to show it).

The benefit of hiding folders is that the student is not distracted by folders and files that are not relevant to the topic you are explaining.

### Assessments

Codio offers a range of manually and auto-graded assessments. When used as a part of content, assessments are a very important way of giving students challenges and exercises that help internalize what they have been learning.

When used in a course situation, assessments are extremely helpful to the teacher as all assessment results are fed automatically through to the teacher course dashboard, allowing them to monitor students' progress across a Course.

Many of Codio's assessment types (code tests, multiple choice questions, text, fill in the blank and list-based) are auto-graded, saving teachers considerable amounts of time and can also offer students instant feedback on the correct answers.

You can also use the free-text assessment type for answers that require a typed answer that can be manually graded by faculty. The free text type also support Latex, so math questions can be answered and graded.

Assessments you create can be saved in your own library for use in other assignments. See here for more information on this. We also have an extensive library of assessments that you are free to use as you wish. See here for more details

### Layouts

The editor lets you create different panel layouts for your guide content and the layout can change from section to section.

## Markdown content editing

### Cheat Sheet

Please refer to the Callout section of the Cheat Sheet. If you have not done so already, copy this starter pack into your own account. You should select the Use Pack option to create the project.

Content can be written in

• HTML allowing more detailed control but requiring more time; described on the next page.

When you are in edit mode, you can select a section by

• selecting a section from the section list

### Renaming the Section

You can rename your section by clicking on the section title in the header area.

### Markdown

For those of you not familiar with Markdown, it is an extremely easy way of writing content without having to worry about HTML.

When in Play Mode or as you preview, your content is rendered as students will see it. You can also override the default CSS styling if you wish. Go to Tools->Guide->Add Custom CSS

'Reset Custom CSS' will restore the default CSS styling

Here is a summary of the Markdown formatting codes

To display a header or title, you can use the # character at the start of the line. The more # characters you add, the smaller the font.

# Big title
## Smaller title
# Even smaller title
## etc.


### Bold and Italic

To create bold or italic text, you use ** and * either side of the respective words.

I want to say that **this is really important**, you know
I *really* like chocolate


### Bullet Lists

To create a list of bullet points, you start the line with a -

- Bullet 1
- Bullet 2
- Bullet 3
- etc


### Numbered Lists

To create a numbered list, you start the line with a 1. The numbers are automatically calculated for you.

1. Item 1
1. Item 2
1. Item 3
1. etc


### Code Blocks

If you want to show some code, styled with the courier font, in a box and with syntax highlighting applied you surround your code block with three backticks . For example, the following javascript snippet

var i;
for(i = 0; i < 10; i++) {
document.write(i);
}


is written with the first line as

js

then your code, and the last line as



Note that you can specify a language type after the top 3 back ticks. Entering python after the backticks would apply syntax highlighting for python. Many languages are supported. See a full list of supported languages here. You should search for your language and then use the alias shown.

The Code block also includes a 'copy to clipboard' button to allow students to easily copy the code to their clipboard where you may want them to run this code in the assignment

### Code Segments

If you want to insert a piece of code inline with the rest of your text, then you use a single  (backtick) character either side of the text. For example,

We can define a variable var x; if we like

... is written in markdown as

We can define a variable var x; if we like

### Indented Lists

If you want to indent a list, then indent just 2 spaces and it will indent.

  - Bullet 1
- Bullet 2
- Bullet 3
- etc


### Callout Blocks

If you want to show a callout block a number of options are available and others can be easily added if required

• important
• info
• warning
• topic
• definition
• challenge
• guidance
• meetup
• hackathon
• create
• calendar
• growthhack
• xdiscipline
• debugging

e.g.

|||info
# My Title

Some text

|||


The Guidance callout block is only visible in play mode to designated teachers within a course. It is not visible for students.

We describe these in this section.

### HTML

You can include HTML tags

### Latex / MathJax

Latex is supported using MathJax. For example

When $a \ne 0$ there are two solutions to $(ax^2 + bx + c = 0)$ and they are $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$

and for multiple lines we do the following

$$y=x^2 y=\frac{x^2}{x+1}$$


### Display mode Latex expressions

You can also render one more more lines of Latex expressions in a more prominent format as shown below.

$$y=x^2 \sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$$


### Latex Resources

Google is often your friend when it comes to discovering Latex syntax. However, here are two very useful references that will accelerate things for you.

#### Mathjax

Here is a list of Latex commands supported by Mathjax.

#### Stack Exchange

Here is a page on Math StackExchange that has an excellent overview of Mathjax/Latex syntax as well as explaining general concepts.