Getting Started

1. Install Itsy

On an Apple Silicon Mac or x86-64 Linux computer, open a terminal and run:

curl -fsSL https://itsykit.dev/install.sh | bash

The installer configures PATH for Bash and Zsh. Open a new terminal when it finishes, then continue below. To keep using this terminal, run the optional PATH command printed by the installer. There is no Go, Node, or database to set up.

2. Create a site

Itsy creates a project folder with a homepage, a shared layout, and the styles you need to get started. Run these commands to create the bookshop project, move into its folder, and start the local development server:

itsy new little-bookshop
cd little-bookshop
itsy dev

When prompted, enter Little Bookshop as the site name and skip the optional admin email. Open the Website URL printed in the terminal to see your new site. Leave this terminal running while you work; it serves the pages and watches for changes.

3. Write the homepage

Open the project folder in your text editor. The site/ folder holds the public pages and assets, and index.html is your homepage. Replace its contents with:

<section class="container py-xl">
  <h1>Little Bookshop</h1>
  <p>Good books, a quiet corner, and time to browse.</p>
  <a href="/visit">Plan your visit</a>
</section>

Save the file and look at your browser. Itsy reloads the page with your new content inside the site's header and footer. Those shared pieces come from the layout, so your page only needs the HTML for its own content.

4. Add a second page

Adding a page is as simple as adding another HTML file. Create site/visit.html alongside your homepage:

<section class="container py-xl">
  <h1>Visit the bookshop</h1>
  <p>Find your next read at our little shop.</p>
  <a href="/">Back to the homepage</a>
</section>

Follow Plan your visit to see it. The filename creates the URL: site/visit.html becomes /visit.

Replace site/_navigation.html with links to both pages:

<a href="/">Home</a>
<a href="/visit">Visit</a>

5. Change the shared layout

site/main.layout.html supplies the shared HTML document, including the header and footer. Its {slot} marks where each page's content goes. A change to the layout appears on every page that uses it.

In that file, add this line just before </header>:

<p class="container py-xs">Independent books. Curious readers.</p>

Save and check Home and Visit. Both now show the same line above their content.

6. Reuse a partial

A partial is a small piece of HTML you can include wherever you need it. Opening hours are a useful example: they belong on both pages, but you should only have to update them once.

Create site/_hours.html:

<p>Open Tuesday to Saturday, 10am to 6pm.</p>

Add this inside the section on both pages:

{render hours}

The hours now appear in both places. Edit the partial to change them together. Its underscore keeps it private; the render instruction leaves off the underscore and extension.

7. Make it yours

Inside the existing @layer styles block in site/css/global.css, add:

h1 {
  color: var(--brand-1);
}

Both headings now use the theme's primary color. Change colors and fonts in site/css/theme.css as you develop the design. Your pages share these styles, so you can give the whole site a new feel without editing each page. The CSS and icons guide explains the included styles and utility classes.

8. Check your work

In a second terminal, open the project folder and run:

itsy status

You should see two valid public pages. Check the links in your browser, then press Ctrl-C in the dev terminal when you're finished. Run itsy dev whenever you want to work on the site again.