Introduction

The DAISY knowledge base uses a very simply structured HTML page that allows authors to focus on writing new pages. All the formatting and additional content, like the menu bars, is inserted dynamically by script.

This page provides a walk-thru of the process of starting a new page and submitting it for inclusion.

Where to Create

How you create a new page depends on what access you have to the knowledge base repository in GitHub.

Trusted contributors with write access to the repository may create a new branch to work in. When you finish your contribution, simply open a new pull request to have the branch merged.

For all other contributors, you will first need to create a GitHub account. You then have to fork a copy the knowledge base repository and then clone it to your desktop to work on. When you finish your contribution, you have to go to your forked repository in GitHub and open a pull request to have your changes added to the DAISY repository.

Page Template

The cleanest way to begin a new page for the knowledge base is with the blank template file located in the templates directory of this repository. This file contains the minimum markup necessary to write a page.

To begin creating a page, copy this template file to the most appropriate directory for the topic it will describe (e.g., a page describing an HTML markup technique would go in /publishing/docs/html) and give it a new short but meaningful file name.

Please avoid using spaces in file names. Use hyphens to join multiple terms.

Page Metadata

After copy and renaming the template file, open it in an HTML editing program. Before beginning to write the new page, make sure to configure the necessary metadata in the document header.

Page Title

The first item that must be set is the page title. Type the new title between the <title>...</title> tags.

Do not insert the page title in the body of the page. The title you put in the title tags will automatically be inserted in the rendered page.

Page Info

The next step is to set the context information for the page. Look for the following script tag in the page header:

<script>
var page_info = {
   'topic': '...',
   'description': '...',
   'appliesTo': ['EPUB3']
};
</script>

The topic field must be the uppercase name of the directory where you are creating the page. For example, if you are adding a new page to the html directory, you would set the field to:

'topic': 'HTML',

If you are creating a new subdirectory for your page(s), you will need to make an array of values for the topic. For example, pages in the html/dpub-aria directory include an array like this:

'topic': ['html', 'dpub-aria'],

The order of the array must match the order of the directories (i.e., parents before siblings). When your page is dynamically generated, this field provides the breadcrumb in the header (among other uses).

The description field provides a short description of the purpose of the page. It is transformed into a meta description tag for search engine optimization.

The appliesTo field is an array of values that identify which publishing technologies the page applies to. There are currently only three values that can be used with this field:

  • EPUB3
  • EPUB2
  • Audiobooks

For a technique that is valid in both EPUB 2 and 3, the field would be:

'appliesTo': ['EPUB3', 'EPUB2'],

Please list technologies by their relevance (e.g., list EPUB 3 before 2 because it is the current version of the standard).

If additional technologies are required, please make a request to have them added.

Page Content

After configuring the page metadata, the final step is to write the actual content of the page.

Knowledge Base pages are structured to get information to users as quickly as possible. As most users will not stop to read extensive descriptions, pages begin with a brief summary of the purpose of the page. The relevant techniques are listed next, followed by a set of examples of the techniques in action. Lengthier descriptions of the issues and links to related resources are included at the end of the page.

This section provides guidance on how to complete each these sections.

Note that contributed pages should follow the default template for consistency with the rest of the site. There are times when the explanation of an issue will not fit this structure but please check in advance before deviating from it. Contributions that are too anomalous may be rewritten or rejected.

Summary

The summary section should provide a brief recap of the key takeaway of the page. What is the key problem to be aware of, for example, or what technique must be followed. The summary should not be more than a sentence or two as it is meant to convey the key point as concisely as possible for users.

The "Explanation" section described below is where you elaborate on the problems and solutions.

Techniques

The techniques section is where you list the common measures to take to fix or avoid the issue covered by the page.

Each list item should explain a practice in simple language and include a link to the relevant WCAG Success Criteria, when applicable, in brackets at the end.

If there are specific WCAG techniques that users can follow, include these in a sub-list.

For example, a technique explaining to include alternative text could be structured like this:

<li>
   <p>Provide alternative text in the <code>alt</code> attribute
      if the image is not described in the surrounding text.
      <span class="wcag-level">[<a
         href="https://www.w3.org/TR/WCAG/#non-text-content">WCAG
           1.1.1</a>]</span></p>
   <ul>
      <li><a
              href="https://www.w3.org/WAI/WCAG21/Techniques/html/H37">Using
              alt attributes on img elements</a></li>
      …
   </ul>
</li>

Examples

Each page should provide users at least one example of how to implement the markup or feature in practice.

Examples are structured using HTML figure tags.

The first child element must be a figcaption. This element is further broken down into a title and description. The title goes in the div element with the class attribute value label. The description is written in one or more paragraphs after the title.

The following example shows a typical structuring of an example caption:

<figcaption>
   <div class="label">Example 1 — Complex Images</div>
   <p>This example uses the details element to …</p>
</figcaption>

The markup for the example goes inside of a pairing of pre and code elements.

<pre id="ex-01-src" class="prettyprint linenums"><code>…</code></pre>

Note that the id and class attributes are required. These are used to add syntax highlighting and line numbers to the generated example.

Frequently Asked Questions

The Frequently Asked Questions (FAQ) section is where you can address specific problems that are commonly encountered in a question-and-answer format. This approach is often easier for users to follow than reading an extended explanation. It also allows very specific problems to be addressed without overloading the more general explanation of the issue.

The FAQ is structured using an HTML definition list (the dl element). Use a dt element for each question and a dd element for each answer.

Explanation

The explanation section is where you describe in detail the practices and issues that users need to be aware of.

There are no specific requirements for the explanation beyond being as thorough as possible and using as simple language as possible. Readers of the knowledge base are not necessarily technology experts.

The explanation can be broken up into subsections if it helps to organize the information.

Other Sections

If additional sections are needed, they should be added after the explanation and before the final related links section.

Updating Indexes

When adding a new page, both the topical and site indexes also need to be updated to include a link to the page.

The topical index is located in the same folder as your page in the index.html file. This file includes a list of pages, typically in alphabetical order (although sometimes an overview or introductory page is listed first). Add a new entry in the list for your page.

The site index is located in the /docs directory. It is an aggregate of all the topical indexes, so you can copy the entry you just made into the document. The only change necessary is to add the path to the file to the link since the page is not in the same directory as this index.

Viewing Pages

If you open a new page in a browser by double-clicking on it from the file system you will only get the raw unstyled HTML.

There are two ways to view pages as they will appear on the site.

  1. The first is to load the page from a local web server (e.g., IIS or Apache) running on your computer. To view your file, you only need to ensure that the root of the repository is the root web site on the server. You can then load the page in any browser to see the dynamically rendered version. The URL for the content folders is typically http://localhost/publishing/docs/

  2. The second way is to commit the page to GitHub and view it online. Here, again, there are two approaches:

    1. If you have cloned the knowledge base to your local account, you can turn on GitHub pages to view the content. GitHub provides instructions on how to turn on pages. In this case, the URL for the content folders would be along these lines: https://youraccountname.github.io/kb/publishing/docs/

    2. You can view the page through a third-party content server like statically.io. In GitHub, you first would navigate to where the page is located (e.g., https://www.github.com/youraccountname/kb/publishing/docs/html/mynewpage.html). You then copy that URL and paste it into the conversion tool to get a new link you can use to view the page live.