ally.js

JavaScript library to help modern web applications with accessibility concerns by making accessibility simpler

# Documentation infrastructure

The documentation is authored in markdown in the docs directory. We're using markdown-it (but staying close to Github Flavored Markdown) to convert the markdown to HTML. markdownlint is there to lint the files, its configuration is maintained in build/markdownlint.js, see the Rules.

The idea is to create a documentation that can be read on github and on the generated website.

If this is your first contact with ally.js, make sure to run npm run init after cloning the repository. This will run npm install, npm run clean, npm run build and npm run build:website to make sure your local copy is ready.

# Building the website

The doc source are converted to HTML by metalsmith, the scripts and configuration are maintained in the build/metalsmith directory.

The website is comprised of 3 elements, the markdown sources, data tables and some legacy files from ./tests.

# lint the markdown
npm run lint:md

# build the library (to `./dist`)
npm run build

# generate website (to `./web`)
npm run build:website

# generate only the markdown files
npm run build:docs

# generate only the data tables
npm run build:data-tables

# generate only the legacy files
npm run build:legacy

The commands lint:md and build:website are also executed by npm run lint and npm run build.

Before you build the website using npm run build:website you need to have run npm run build before, in order for the library components to be available to the website build. You don't need to build the library every time you build the website, which is why this step is disconnected. If you ran npm run init after cloning the repository, everything is taken care of already.

If you're new to metalsmith, have a look at simple static site demo and getting to know metalsmith.

We use the following plugins:

The website's autosuggest-based search is powered by Algolia. As part of npm run build:website the index files web/algolia.*.json are generated, which can be uploaded using npm run publish:algolia.

# Authoring documentation

The public API provided by ally.js needs to be explained in docs/api. As every component has its source file, it has an accompanying markdown file for documentation. ally.js contains components that are not meant to be used directly, thus do not have to be documented in detail.

Anything you document should be written in a way that caters to an audience that may not know very much about accessibility. If bigger picture explanations are required, consider writing a tutorial instead of cramming it into the API docs.

# Embedding examples and Demos

Using markdown-it-container the documentation accepts @@@ fenced markdown blocks to embed jsbin.com hosted code examples.

@@@example /api/path/to/name.example.html
### title of example
@@@

The example block's first headline's text is automatically replaced by the example document's title. Additional content (like notes, warnings) may be provided in the example block. The example file is referenced by its absolute path from the perspective of the docs directory.

An example document is named ${slug}.example.html (for multiple ${slug}.example-2.html) and placed in the same directory as the referencing document. So for docs/api/element/disabled.md the example file would be docs/api/element/disabled.example.html.

Example documents must follow the following general structure.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>ally.js ${example_title} Example</title>
  <link rel="jsbin" href="">
  <style id="example-css">
    ${example_style}
  </style>
</head>
<body>

<article id="example-introduction">
  <h1>Accessible ${example_title} Tutorial</h1>
  <p>${example_description}</p>
</article>

<div id="example-html">
  <main>
    ${example_markup}
  </main>
</div>

<script src="https://cdn.jsdelivr.net/ally.js/1.3.0/ally.min.js"></script>

<script id="example-js">
  ${example_script}
</script>

</body>
</html>

The command npm run publish:jsbin uses jsbin-sync to find all example*.html files and upload them to JSBin.com. This can only be executed by Rod, as we're using his personal JSBin pro account for this. New examples will have their empty <link rel="jsbin" href=""> element updated to the URL returned by JSBin, but this is the only change applied to source files. Contents of #example-js and #example-css go into the bin's JavaScript and CSS sections, respecively. The bin's HTML section contains the HTML document, without the <script id="example-js">, <style id="example-css"> and <link rel="jsbin"> elements.

# Notes and warnings

Using markdown-it-container the documentation accepts ::: fenced markdown blocks to highlight certain bits. In API pages (layout: doc-api.html) the section ## Notes can be used to collect multiple highlights:

## Notes

:::note
I'm informing you of something you SHOULD know
:::

:::warning
I'm informing you of something you MUST know (because it's not obvious)
:::

:::tip
I'm informing you of a best practice
:::

:::help
I'm informing you of something you can contribute to this project
:::

Got a better Idea to solve this? file an issue!

# Definitions

Using markdown-it-deflist the documentation allows MarkdownExtra-style definition lists:

Term 1
: Explanation 1

Term 2
: Explanation 2

# API classifications

API documents must declare their traits, which is done via the tags property in the front matter section of the document:

---
layout: template.html
tags: option-argument, service, svg
---

# Headline

The tags to be used for classification are:

argument-options
To declare the module belongs to the family of components expecting a single options argument.
argument-list
To declare the module expects plain arguments, not the single options argument pattern.
service
To declare the module belongs to the family of Service components.
global-service
To declare the module belongs to the family of Global Service components.
data
To declare the module provides data, not functionality.
internal
To declare the module is intended for internal use only.
browser-fix
To declare the module's only intention is to counter a specific browser quirk.
content-document
To declare the module resolves <object> and <iframe> elements to their content documents.
shadow-dom
To declare special support for ShadowDOM.
svg
To declare special support for SVG.

# API changes

In addition to the less specific CHANGELOG.md, API documents must declare specific changes in detail:

## Changes

* `v1.2.3` introduced the option `gustav`
* `v1.3.0` removed the option `otto`
* Since `v1.6.0` the function returns coffee instead of tea

Since the exact release version a change will be included in is not necessarily known during development, the placeholder v#master should be used.

The version notation may be extended to also contain addition +v1.0.0 / removal -v1.0.0 / change ~v1.0.0 should this become necessary. The website builder may replace the code elements by links to the change log.