Table of Contents
Want to help? Here's how.
About this site
Following is information about how the site operates. Instructions on how to get the site running locally on your computer can be found in the
Git and GitHub
People working on more sophisticated aspects of the site (new features, bug fixes, etc.) are expected to have at least some familiarity with version control, GitHub's key functionality, and using feature branches to work locally.
If you are looking for a place to get started learning about Git and contributing to an Open Source project, Egghead.io offers a great introductory course.
To submit updates and changes to The A11Y Project, you will first need to Fork the repository.
Forking will create a copy of the repository on your GitHub account. This will allow you to make changes on your copy and suggest incorporating them into The A11Y Project's repository in the form of a Pull Request.
If you do not plan on working on The A11Y Project for an extended period of time you can delete your Fork of the repository after your Pull Request has been merged without endangering our copy.
Tatiana Mac has a great beginner's guide to Eleventy, if you are looking for a good introduction.
Any changes you save will cause the local version of the site to recompile. The browser tab that has your local instance of the site will automatically refresh, allowing you to preview your edits.
main is the production branch. This is the live website.
If you have a feature request, we suggest first filing an Issue to discuss it (please read how to report an issue first). Once that feature has been approved you can start coding! Create a new feature branch from
main, and name it something that references the feature you'll be working on. For example a feature to increase the site's type size could be:
A list of all active branches is available.
This site uses specific kinds of files to help run the site efficiently. Eleventy will take these files and compile them into HTML, CSS, and other browser-friendly code.
Please make all edits in these files, and not the compiled code. If you edit the compiled code it will be overwritten the next time any file is saved and all your hard work will be lost!
Some of the main files this site uses are:
Markdown is a lightweight markup language that makes writing easier. We use it mainly to organize our blog posts. It uses
.md files and compiles into HTML.
.njk files and compiles into HTML.
Syntactically Awesome Style Sheets (Sass) is an extension of the CSS language that adds many helpful features. Using it helps keep our site's visual presentation consistent. It uses
.scss files and compiles into CSS.
YAML Ain't Markup Language (YAML) is a human-readable markup language that is good for writing structured data. This structured data is used specifically for posts and Eleventy page templates.
In the spirit of Open Source, The A11Y Project tries to only promote content that is free, or has a low barrier to entry. We're not too keen on partnership deals or promotions.
Content style guide
The A11Y Project has a Content Style Guide to help our content have a consistent voice and tone. Please take a moment to familiarize yourself with it.
Have an idea for a post? We'd love to know what you want to contribute!
- Search to make sure someone hasn't claimed the post already.
- Claim a post by starting a new Issue with "Post: Your title" as the Issue title. This will help us keep track of who is working on what. The final, published title can be different from the Issue name.
We also have a list of posts we'd love to see written!
Posts are written using Markdown, using a special formatting technique called front matter. Eleventy uses front matter information to create things like author attribution, categories, and page layout.
To get started writing a post, create a feature branch and create a new Markdown file in the
posts directory. The Markdown's file name should reflect the intended publishing date and the title of the post. For example, a post about accessible typography may have a filename along the lines of
Copying an existing post, then updating its filename and front matter to match your post can be an easy way to help ensure everything is formatted properly.
If you would like to write an post but do not feel comfortable working in Markdown or with GitHub, please contact us at email@example.com and we can work something out.
Once you are satisfied with your post's content, submit a Pull Request so it can be reviewed. Reviews will be conducted using GitHub's review tools. Project maintainers may request additional updates for clarification or technical accuracy.
Be sure to also add yourself to
authors.json so you can get credit for your work!
Once both the project maintainers and author are satisfied with the post, it will be merged by a project maintainer and published automatically. We will also notify you that publication has occured.
Did you create or find a great accessibility-related resource that you think other people would find useful? Add it to the Resources file under the appropriate category.
Please be sure to include the resource's title, description, and a URL where it can be accessed.
Acceptance of resource content suggestions are weighed on the quality of the actual content, the accessibility of the site it is hosted on, the organization's status in the industry, and the organization's mission.
The A11Y Project used to list webinars, regional events, and meetups. We no longer support this feature. If you are interested in finding an accessibility-related group near you, please check our Meetups section in Resources.
The A11Y Project used to list code patterns. We no longer support this feature. If you are interested in learning about accessible implimentations of common User Interface elements, please consult the WAI-ARIA Authoring Practices.
Promotions, partnership deals, and SEO scams
We are not interested in quid pro quo schemes to boost your site's SEO ranking. We are also not interested in backlink, partnership, and affiliate linking programs.
Project maintainers may elect to not accept your submission if they feel it is not in line with the site's goals. This will be handled on a case-by-case basis.
Submitting new features
New features typically represent significant changes to the website. We ask that before you begin work on adding functionality or features that you bring up your proposed changes as a GitHub Issue first.
This helps the site maintainers anticipate and plan for incorporating large-scale changes, and how they'll affect the website. It will also allow us to see how your proposed changes align with our roadmap, as well as discuss accessibility implications.
Have you noticed something inaccurate or inaccessible? You can help make it better!
- File an Issue.
- Preface your Issue title as an:
- Inaccuracy for incorrect or inaccurate information (e.g. "Inaccuracy: Visually hidden CSS missing property declaration").
- Inaccessibility for an accessibility issue (e.g. "Inaccessibility: Low contrast link color").
- Bug for site issues (e.g. "Bug: Link at archive not working").
Issues are not to be used for free accessibility help. Project maintainers may close reported Issues at their discretion.
Submitting Pull Requests
Creating a descriptive Issue and assigning it to yourself before you send your Pull Request will help get it accepted. Doing so will provide a better understanding of what your request entails and why it was made. It also helps to link the Issue to the Pull Request and vice-versa (eg. "This Pull Request addresses Issue 213").
Project maintainers may reject Pull Requests at their discretion.
When submitting your Pull Request, please include the text "closes" or "fixes" and then the issue number (e.g. "Fixes #101."). This will help us automatically close the issue upon merging the Pull Request.
Stale Issues and Pull Requests
Project maintainers will close Issues and Pull Requests if they become stale, leaving a note for the author as to why. This keeps our Issue tracker and code work clean and up-to-date, and helps project maintainers focus their attention where it is needed.
An Issue is considered to be in a "stale" state when any of the following conditions are met:
- The last comment was made over three months ago.
- There has been no activity since.
- Someone has attempted to address the Issue, no with no followup participation from the author.
Stale Pull Requests
A Pull Request (PR) is considered to be in a "stale" state when the following conditions are met:
- The last comment was made over three months ago.
- There has been no activity since.
- Someone has attempted to move the PR along with no followup from the author.
When updating posts, leave the original publish date and author as-is. Add the following to the front matter:
updated_by: editor_name last_updated: yyyy-mm-dd
By contributing your code and content, you agree to license your contribution under the terms of the APLv2.