Writing and Editing Pages

Requirements

Files and Directories

Music Theory 21c is comprised of the following files and file directories:

• css: this folder contains main.css, which contains font and layout information for all pages on the site.
• font: this folder contains a copy of the webfont Bravura, which contains musical symbols, and the FontAwesome symbol set, which contains icons and other useful pictographs.
• glossary.html: this is Music Theory 21c's glossary, which is referred to throughout the text.
• index.html: this is the Music Theory 21c main page, containing the introduction and table of contents.
• js: this folder contains all the JavaScript files used by Music Theory 21c, including main.js, which provides necessary functionality for all pages, and inators, which contains interactive figures and tools used throughout the text.
• text: this folder contains most of the actual HTML pages which comprise Music Theory 21c.

Within the text directory, each unit in the text of Music Theory 21c is represented by an HTML file xyz.html, and a folder xyz. The HTML file provides an introduction and table of contents for the unit. The folder contains the following files and directories:

• xyz01.html, xyz02.html, etc.: these are the individual pages containing the content for each topic.
• images: this directory contains any graphics included on the pages.
• exercises: this directory contains materials for student exercises included at the end of each page. Files in this directory are organized into folders by extension, such as docx or txt.
• Supporting files directory: other directories — brf, m4a, mxl and pdf — contain music, sound, and other documents referred to by figures in the text.

Page Structure

Pages in Music Theory 21c use specific HTML elements and structures to provide consistency throughout the site. A set of templates is available in the tem directory, each of which provide comments describing the different elements of the page.

<div>
    <h1>Writing and Editing Pages</h1>
    <p>...</p>
    <div>
        <h2>Requirements</h2>
        <div>
            <h3>Necessary Skills</h3>
            <p>...</p>
        </div>
        <div>
            <h3>Necessary Tools</h3>
            <p>...</p>
        </div>
    </div>
    <div>
        <h2>Files and Directories</h2>
        <p>...</p>
    </div>
    <div>
        <h2>Page Structure</h2>
        <p>...</p>
        <div>
            <h3>Text Hierarchy</h3>
            <p>...</p>
        </div>
        
        ...
        
    </div>
</div>

Text Formatting

Music Theory 21c includes several formatting shortcuts to ensure consistency and legibility and to allow writers to focus on content over design.

Figures

The templates in the tem directory include example code for including different types of figures, including photographs, diagrams, audio, video, and interactive elements, placed as chapter heading images, images inline with the text, and as sidebars.

Writer/developers are encouraged to consider the following when including figures:

• All material included in Music Theory 21c must be compatible with Music Theory 21c's overall license, CC BY-NC-SA 4.0. All material not created by the writer/developer should include an attribution and license, even if the material is in the public domain.
• Figures can reference material hosted on other servers which do not fall under Music Theory 21c's overall license; for example, a figure may include an embedded YouTube video containing copyrighted media. In this case, writer/developers should strive to link to official, creator-sponsored versions whenever possible.
• Material referenced on other servers should be limited to audio and video files on popular hosting sites like YouTube and Vimeo. Still images should not be linked externally.
• PNG format is preferred for photographs and other bitmapped graphics, and writer/developers should use the largest and highest-resolution files available.
• SVG should be used for diagrams, musical examples, and similar graphics.
• When designing diagrams and musical examples:
• Diagrams and musical examples should be designed with primarily black figures against a transparent background, which will be displayed as white on the page. Color can and should be used to highlight elements, categorize elements, or provide other context. Shading, gradients and drop shadows should be avoided in favor of solid, distinct graphic elements.
• Diagrams and musical examples should be designed to be clear and legible by readers who have colorblindness.
• In most cases, musical scores written in staff notation should be typeset using a music notation program and saved as an SVG file. Within the score, text such as staff names, tempo markings, lyrics and other annotations should be set in Fira Sans Condensed Medium, and musical directions such as "cresc." and "pizz." should be set in Crimson Text roman or italic, as appropriate.
• When appropriate, a second version of each graphic file should be included for use in web browsers set to dark mode. These images should be linked in the <img> tag using the data-dark-src parameter.
• For diagrams, dark mode versions should be designed with primarily white figures and text against a transparent background which will be displayed as dark charcoal, #333333. Highlight colors may be replaced with brighter versions to improve legibility.
• Dark mode versions of musical examples in staff notation should be set as black figures against a background of silver, #bbbbbb.
• It is not necessary to provide dark mode version of photographs; if a data-dark-src parameter is not included, the file referenced by the src parameter will be used in both light and dark mode.
• All <img> tags must include an <alt> tag with a screenreader-compatible description of the image. These should be brief descriptions of the pertinent elements of the image. For musical examples, the <alt> tag should include a brief, general description of the passage. Accidentals must be spelled out: "F sharp" and "B flat" instead of "F#" and "Bb".
• The <figure> tag should include the data-filename parameter indicating the chapter and figure number. If this parameter is present, buttons can be added to the figure using the following tags:
• <div class="audio button"></div> adds a button which plays a corresponding M4A audio file placed in the m4a directory.
• <div class="braille button"></div> adds a button which links to a BRF braille music notation file placed in the brf directory.
• <div class="musicxml button"></div> adds a button which links to a Music XML notation file placed in the mxl directory.
• <div class="youtube button" data-url="[embed url]"></div> adds a button which plays a YouTube video in a pop-up player. To find a video's embed URL, click on a video's "Share" link, choose "Embed", and extract the URL from the code provided.
• <div class="spotify button" data-url="[embed url]"></div> adds a button which plays a Spotify track in a pop-up player. To find a track's embed URL, click on the three dots for a track in the Spotify player and choose "Share" > "Embed Track". Note that at this time, embedded Spotify tracks only allow users to play a short sample of the complete track.
• <div class="apple button" data-url="[embed url]"></div> adds a button which plays an Apple Music track in a pop-up player. To find a traack's embed URL, click on the three dots for a track in the Music app and choose "Share" > "Copy Embed Code". Note that at this time, embedded Apple Music tracks only allow users to play a short sample of the complete track.
• For more information on creating and including interactive figures, see Interactive Figures.

Lyrics and Notated Excerpts

Because Music Theory 21c is released under a Creative Commons license, care should be taken to avoid including any copyrighted material; linking to copyrighted material on a separate server owned or sanctioned by the copyright owner should be done instead.

In some cases, figures provide analysis of copyrighted music or lyrics by including an excerpt of the notated music, printed lyrics, or both. While the following does not constitute legal advice, the original authors feel that including these transcriptions of short excerpts meet the standards of Fair Use as prescribed by US Copyright Law:

• The purpose and character of the use in Music Theory 21c is for non-commercial educational purposes, providing respectful analysis or commentary about the work.
• The format of the copyrighted work — musical performance — is not reused or redistributed, only notated elements of excerpts of the work.
• Only small portions of complete works are used.
• The effect of the use upon the potential market for the works is negligible; in fact, potential customers are provided links to the original material on major streaming services.