Want to help? Here's how. Please be sure to check our Content Style Guide before contributing. Questions or concerns about contributing can be addressed in the site's Issue Tracker.
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 README.
The A11Y Project is an Open Source project. It uses Git and GitHub to handle publishing new content and features, as well as coordinating maintenance.
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.
This project uses Jekyll to convert project files into a website that a browser can read and display. You'll need to make sure you've run all the commands in our README to get Jekyll working.
Any changes you save will cause the local version of the site to recompile. You can then refresh the browser tab that has your local instance of the site open to preview your edits.
gh-pages 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 gh-pages, 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: increase-font-size.
A list of all active branches are available here.
This site uses specific kinds of files to help run the site efficiently. Jekyll 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 to organize our blog posts, as well as our main site pages. It uses .md 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's good for writing structured data. This structured data is used throughout the site as a way to keep information both consistent and human-readable. It uses .yml files.
As we are an Open Source project, 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.
The A11Y Project has a 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 an article? We'd love to know what you want to contribute!
- Search to make sure someone hasn't claimed the article already.
- Claim an article by starting a new Issue with "Article: 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 articles we'd love to see written.
Articles are written using Markdown, using a special formatting technique called front matter. Jekyll uses front matter information to create things like author attribution, categories, and page layout.
To get started writing an article, 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 article. For example, a post about accessible typography may have a filename along the lines of 2018-09-12-accessible-typography.md
Copying an existing post, then updating its filename and front matter to match your article can be an easy way to help ensure everything is formatted properly.
Once you are satisfied with your article'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.yml so you can get credit for your work!
Once both the project maintainers and author are satisfied with the article, it will be merged by a project maintainer and published automatically.
Have an accessibility-themed event you would like to promote? There are two ways you can get your event added to the project: Either create a new Issue, or edit the events.yml file directly and submit a Pull Request.
Events can either be Regional (in-person), or Webinars (online). You'll want to add the following information about your event:
- Event title.
- A brief description (2-3 sentences).
- Web address (URL) for more info.
- Event type (Regional or Webinar).
- Social Media Hashtag (if applicable).
- Date the event is occurring (yyyy-mm-dd).
- Physical address of event (if applicable).
- An optional link to a mapping service such as Google Maps that uses the supplied physical address.
If you'd like to submit a Pattern make sure to do the following:
- Make a CodePen (or use an equivalent service such as JSFiddle or JSBin). Please try not to use preprocessing libraries (Sass, Less, HAML, etc.) if at all possible—this helps keep the barrier for entry lower, as well as ensuring your code is future-proof.
- Submit your CodePen to our Issue Tracker with the name of your pattern as the title.
- Discuss community feedback. Please keep the feedback and discussion relevant to the pattern submitted. Submit new patterns as separate Issues, and discuss them in their respective threads.
- When feedback is concluded, the pattern will be added to the site by project maintainers.
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.
Project maintainers may elect to not accept your submitted content if they feel it is not in line with the site's goals. This will be handled on a case-by-case basis.
Have you noticed something inaccurate or inaccessible? You can help make it better!
- File an Issue.
- Preface your Issue title as an:
Inaccuracyfor incorrect or inaccurate information (e.g. "Inaccuracy: Visually hidden CSS missing property declaration").Inaccessibilityfor an accessibility issue (e.g. "Inaccessibility: Low contrast link color").Bugfor 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.
Creating a descriptive Issue and assigning it to yourself before you send your Pull Request will help get it accepted. It 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 XX").
Project maintainers may reject Pull Requests at their discretion.
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 six months ago.
- There has been no activity since.
- The question isn't open.
- Someone has attempted to address the Issue, no with no followup participation from the author.
A Pull Request (PR) is considered to be in a "stale" state when the following conditions are met:
- The last comment was made over six months ago.
- There has been no activity since.
- Someone has attempted to move the PR along with no followup from the author.
Labels allow the project maintainers to quickly sort filter and site Issues and Pull Requests. They will be added and removed as needed.
By contributing your code, you agree to license your contribution under the terms of the APLv2.