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:
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
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
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:
- Incorrect answer
- Correct answer