Editing Guide

Understanding URLs

All books and chapters follow a simple naming convention:

http://edtechbooks.org/[book short name]/[chapter short name]

For example, http://edtechbooks.org/k12edtech/technology_integration would go to the technology_integration chapter in the k12edtech book.

Short Names

Each book and chapter has a short name that must be URL-friendly. This means that should not use spaces or any special characters. Underscores “_” should be used in place of spaces for chapters but not for books. For example, a short name for the book “K-12 Educational Technology” might be “k12edtech”, while a short name for the chapter “Technology Integration” might be “tech_integration.”

Editing a Chapter

If you have access to edit a chapter, you should see pencil button at the top-right of the page while you are viewing it. If you do not see this button, you need to make sure that you are logged in and verify with the super admin that you have necessary permission to edit the page.

Uploading Images

Currently, only the super admin can upload images. Once images are uploaded, they may be embedded by including a relative link to its url as follows: ../content_images/[book short name]/[name of image file]

Author images and book cover images will be embedded automatically once the super admin adds them to the file structure.

Styling Chapter Contents

For an example that uses most of the guidelines below correctly, please consult http://edtechbooks.org/lidtfoundations/proper_way

Cover Images

All cover images should have dimensions equivalent to 5.5” x 8.5”.

Minimal Markup

As a general rule, there should be very little markup in the source of a chapter. When you look at the source, you should only see the following tags and attributes:

 

and higher

 

 

or or

 

And an occasional or as long as it is in the middle of a paragraph and not used for an entire heading.

If you are copying from another web source (such as PressBooks), paste directly into the TinyMCE WYSIWYG editor, because this will strip many of the unwanted tags for you.

Headings

Headings in the chapter should start at the H2 level. No H1 tags are allowed.

Also, do not use ALL CAPS in headings. We can convert all headings to all caps with the CSS styles, but we cannot convert them back. So, by not making them ALL CAPS you make it easier for formatting down the road.

Images

Images should not have width, height, style or other attributes so that they can be responsive to the size and style of the page. They should only have a href and class attribute.

Classes

Images should all use one of the following class attributes:

Img-fluid

This is used for banner-type images that should fill the whole page. If a banner image will need a caption, use the Tools > Banner Img feature.

pull-left or pull-right

These are used for images that the text should wrap around.

Captions

To capture an image, add a “caption” attribute as follows:

”XXX”

The system will automatically convert this to a figcaption tag and format it properly.

Lists

Lists are okay (

      ,
).

Callouts

Callouts are boxed content on the page that can be created by using the Tools > Callout Div feature. Callouts require an H3 heading and paragraphs or lists for content. This creates a

element with a class of

callout.

Multiple H3s

H3s are used as colored-background headings inside callouts. As such, they have rounded borders at the top. If you use multiple H3s in a single callout, you should add the “no-border-radius” class tag to subsequent H3s to make them flat on the top.

Colored Callouts

By default, callouts use a gray background. In addition to the callout class, you may add one of the following color classes to the callout’s

tag as follows:

good

Gives a green background.

bad

Gives a red background.

objectives

Gives a blue background.

exercises

Gives a purple background.

info

Gives a light-blue background.

Tables

Tables should not be used for layout, because this will break the page’s responsiveness. Tables should only be used for data. To style the table, give it a table class called “table.” Additionally, tables should have all of the following tags in the provided structure:

 

 

[header info here]

[additional header rows]

 

 

[table data here]

[additional data rows]

 

 

Custom Elements

A few custom elements are allowed. These are created by going to Tools > [Custom Element]. Existing custom elements include the following:

YouTube Video

Type the YouTube video’s id (not the entire url) into the popup to create an embedded image and link. If the YouTube video does not give you a valid thumbnail, this is because it is an old YouTube video that does not have a high-resolution thumbnail. To change this, click on the YouTube image and click the “Image” button in the editor. Then, change the filename from maxresdefault.jpg to hqdefault.jpg.

Quizlet

Type in the Quizlet’s id (not the entire url) to the popup and choose the Quizlet type to create an iframe of the Quizlet.

Practice Quizzes

You can add practice quizzes by inserting an order list

    element and giving it the class “practice_quiz”. Make each item in the list a different option. Bold the correct answer, and watch the magic. For example: