Quick Start Getting Started

From zero to a live government website in just a few commands. Follow our streamlined setup process to build your Section 508 compliant, USWDS-powered website.

Start Setup →

Get your federally compliant website up and running in 5 minutes

Quick Setup: If you're already familiar with Node.js and npm, jump directly to the Quick Start section below.

Prerequisites

Before you begin, ensure you have:

JavaScript runtime for building

node --version

Version control system

git --version

VS Code recommended

code --version

Quick Start

Create from Template

Visit our GitHub repository and click the green "Use this template" button to create your own copy.

Clone Your Repository

git clone https://github.com/YOUR-USERNAME/YOUR-REPO.git
cd YOUR-REPO

Install Dependencies
```
npm install
```
Start Development Server
```
npm start
```
Your site is now running at http://localhost:8080

git clone https://github.com/williamzujkowski/uswds-11ty-template.git my-website
cd my-website
rm -rf .git
git init
npm install
npm start

Visit http://localhost:8080 to see your site!

Download the template ZIP file
Extract to your desired location
Open terminal in the extracted folder
Run: npm install
Start: npm start

Your First Changes

Edit the homepage: Open src/index.md in your editor
Change the title: Update the hero heading to your agency name
Save the file: Your browser will auto-refresh with changes
Success! You've just edited your first page

Pro tip: Keep your browser and editor side-by-side to see changes instantly!

Essential Configuration

1. Update Site Information

Edit src/_data/site.json:

{
  "title": "Your Agency Name",
  "description": "Brief description of your agency",
  "url": "https://your-domain.gov",
  "author": "Your Agency",
  "email": "contact@your-agency.gov"
}

Also in src/_data/site.json:

{
  "navigation": {
    "primary": [
      { "text": "Home", "href": "/" },
      { "text": "About", "href": "/about/" },
      { "text": "Services", "href": "/services/" },
      { "text": "Contact", "href": "/contact/" }
    ]
  }
}

3. Create Your First Page

Create src/pages/about.md:

---
layout: layouts/page.njk
title: About Us
permalink: /about/
---

# About Our Agency

Your content here...

Available Commands

Development commands for building and testing your site
Command	Description	When to Use
`npm start`	Start development server with live reload	Daily development work
`npm run build`	Create production-ready build	Before deployment
`npm run deploy`	Deploy to GitHub Pages	Publishing updates
`npm run test:a11y`	Run accessibility tests	Before commits
`npm run lint:js`	Check JavaScript code quality	During development
`npm run format`	Auto-format code with Prettier	Before commits

Project Structure

your-website/
├── src/                    # All source files
│   ├── _data/             # Global data (site.json)
│   ├── _includes/         # Templates and layouts
│   ├── _styles/           # SCSS stylesheets
│   ├── assets/            # Images, fonts, JS
│   └── pages/             # Your content pages
├── _site/                 # Built site (git-ignored)
├── eleventy.config.js     # 11ty configuration
└── package.json           # Dependencies & scripts

Deployment Options

Perfect for public agency sites. Automatic deployment with included GitHub Actions.

Push to GitHub
Enable Pages in Settings
Site deploys automatically

npm run deploy

Official government hosting platform with FedRAMP authorization and compliance.

Apply for account
Connect repository
Configure build settings

Common Tasks

touch src/pages/services.md

Then add front matter to the file:

--- layout: layouts/page.njk title: Our Services permalink: /services/ ---

Your content goes here…

Edit src/_styles/_custom.scss:

$theme-color-primary: #0f4c81;
.my-component {

background: color(‘primary-lighter’);

padding: units(2);

}

All USWDS components are available. Example alert:

<div class="usa-alert usa-alert--info">
  <div class="usa-alert__body">
    <h4 class="usa-alert__heading">Information</h4>
    <p class="usa-alert__text">Your message here.</p>
  </div>
</div>

View all components →

Place image in src/assets/img/
Reference in markdown: ![Alt text]({{ '/assets/img/image.jpg' | url }})
Or in HTML: <img src="{{ '/assets/img/image.jpg' | url }}" alt="Description">

Troubleshooting

Common Issues & Quick Fixes

Installation Fails

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Port Already in Use

lsof -ti:8080
npx @11ty/eleventy --serve --port=3000

Changes Not Showing

Hard refresh browser (Ctrl+Shift+R)
Restart dev server
Check terminal for errors

Build Errors

Check Node version: node --version
Update dependencies: npm update
Enable debug: DEBUG=Eleventy* npm start

Next Steps

Browse all available USWDS components with live examples.

See complete example websites built with this template.

Learn accessibility, security, and performance guidelines.

Get Help

Support Resources

GitHub Issues: Report bugs or request features
USWDS Community: Join discussions
Documentation: Official USWDS docs

Ready to build something amazing?

View Demo Sites →

View on GitHub | CC0 License (Public Domain)

Quick Start Getting Started

Prerequisites

Node.js 18+

Git

Code Editor

Quick Start

Create from Template

Clone Your Repository

Install Dependencies

Start Development Server

Your First Changes

🎯 Try It Now

Essential Configuration

1. Update Site Information

2. Customize Navigation

3. Create Your First Page

Available Commands

Project Structure

Deployment Options

GitHub Pages (Free)

Cloud.gov / Federalist

Common Tasks

Troubleshooting

Common Issues & Quick Fixes

Installation Fails

Port Already in Use

Changes Not Showing

Build Errors

Next Steps

Explore Components

View Demo Sites

Best Practices

Get Help

Support Resources

Quick Start Getting Started

Prerequisites #

Node.js 18+

Git

Code Editor

Quick Start #

Method 1: Use as GitHub Template (Recommended)

Create from Template

Clone Your Repository

Install Dependencies

Start Development Server

Method 2: Direct Clone

Method 3: Download ZIP

Your First Changes #

🎯 Try It Now

Essential Configuration #

1. Update Site Information #

2. Customize Navigation #

3. Create Your First Page #

Available Commands #

Project Structure #

Deployment Options #

GitHub Pages (Free)

Cloud.gov / Federalist

Common Tasks #

Adding a New Page

Customizing Styles

Using USWDS Components

Adding Images

Troubleshooting #

Common Issues & Quick Fixes

Installation Fails

Port Already in Use

Changes Not Showing

Build Errors

Next Steps #

Explore Components

View Demo Sites

Best Practices

Get Help #

Support Resources

Prerequisites

Quick Start

Your First Changes

Essential Configuration

1. Update Site Information

2. Customize Navigation

3. Create Your First Page

Available Commands

Project Structure

Deployment Options

Common Tasks

Troubleshooting

Next Steps

Get Help