A template repository to set up a HTML/CSS/JS/Markdown/USWDS/11ty website
This repository serves as a template for the CMS OSPO's static website stack:
- HTML/CSS/Javascript
- Markdown for content
- 11ty for Static Site Generation
- US Web Design System (USWDS)
- search.gov and Digital Analytics Program
This template is a fork from the 18F/guides repository. The repository documentation can be used as a resource: https://github.com/18F/guides?tab=readme-ov-file
Other applications of this template include:
- CMS OSPO metrics website and repository
- CMS OSPO ospo-guide website and repository
- CMS OSPO SHARE IT Act Landing Page and repository
A list of core team members responsible for the code and documentation in this repository can be found in COMMUNITY.md.
.
├── _data # Data directory
├── _includes # Contains various components
│ ├── home
│ ├── layouts
│ └── searchgov
├── assets # Static assets like images, CSS, and JavaScript
│ └── _common # Common assets used across all pages
│ ├── _img
│ │ └── favicons
│ ├── js
│ └── styles
│ └── overrides
├── config # Configurations to supplement website functionality
└── content. # Individual web page content lives here
├── basic_page
├── other
└── side_nav_page
The following guide is for members of the project team who have access to the repository as well as code contributors. The main difference between internal and external contributions is that external contributors will need to fork the project and will not be able to merge their own pull requests. For more information on contributing, see: CONTRIBUTING.md.
The site uses 11ty. Ensure that you have the latest version of Node installed.
To run the site locally:
- Clone this repo
- From the repo directory, run:
npm install npm run dev
- Open http://localhost:8080
We welcome contributions to be made to our resources. All are encouraged to suggest improvements that benefit the rest of the organization. To make a contribution to a document:
- Find markdown file with document contents located in
/content. - Make edits in a separate branch. Be sure to update
subnavfront matter if new sections are made. - Create a pull request with anyone in the OSPO team as reviewers as noted in COMMUNITY.md.
We use a GitHub workflow in place that performs a number of tests on every pull request:
- Automated accessbility test with
pa11y-ci - Code linting with
eslint - HTML validation with
html-validate - Internal link checking with
check-html-links
Additionally, we use prettier for code formatting.
This project follows trunk-based development, which means:
- Make small changes in short-lived feature branches and merge to
mainfrequently. - Be open to submitting multiple small pull requests for a single ticket (i.e. reference the same ticket across multiple pull requests).
- Treat each change you merge to
mainas immediately deployable to production. Do not merge changes that depend on subsequent changes you plan to make, even if you plan to make those changes shortly. - Ticket any unfinished or partially finished work.
- Tests should be written for changes introduced, and adhere to the text percentage threshold determined by the project.
This project uses continuous deployment using Github Actions which is configured in the ./github/workflows directory.
Pull-requests are merged to main and the changes are immediately deployed to the production environment.
The Open Source Team at CMS is taking a community-first and open source approach to the product development of this tool. We believe government software should be made in the open and be built and licensed such that anyone can download the code, run it themselves without paying money to third parties or using proprietary software, and use it as they will.
We know that we can learn from a wide variety of communities, including those who will use or will be impacted by the tool, who are experts in technology, or who have experience with similar technologies deployed in other spaces. We are dedicated to creating forums for continuous conversation and feedback to help shape the design and development of the tool.
We also recognize capacity building as a key part of involving a diverse open source community. We are doing our best to use accessible language, provide technical and process documents, and offer support to community members with a wide variety of backgrounds and skillsets.
Principles and guidelines for participating in our open source community are can be found in COMMUNITY.md. Please read them before joining or starting a conversation in this repo or one of the channels listed below. All community members and participants are expected to adhere to the community guidelines and code of conduct when participating in community spaces including: code repositories, communication channels and venues, and events.
If you have ideas for how we can improve or add to our capacity building efforts and methods for welcoming people into our community, please let us know at opensource@cms.hhs.gov. If you would like to comment on the tool itself, please let us know by filing an issue on our GitHub repository.
We adhere to the CMS Open Source Policy. If you have any questions, just shoot us an email.
Submit a vulnerability: Vulnerability reports can be submitted through Bugcrowd. Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days.
For more information about our Security, Vulnerability, and Responsible Disclosure Policies, see SECURITY.md.
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication as indicated in LICENSE.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request or issue, you are agreeing to comply with this waiver of copyright interest.