Skip to content

Getting Started

Jump to bottom
deepakness edited this page Feb 8, 2026 · 2 revisions

Getting Started

Prerequisites

  • Node.js 18 or later

Installation

  1. Create your repository — Click "Use this template" on the PutOut repo, or fork it.

  2. Clone it locally:

    git clone https://github.com/<username>/<repository>.git
cd <repository>

  3. Install dependencies:

    npm install

Development Server

Start the dev server with live reload:

npm run start

This opens a local server at http://localhost:8080/. Whenever you save a file — a chapter, a template, or a configuration change — the site automatically rebuilds and your browser refreshes to show the latest version.

Production Build

Generate the full static site (HTML + CSS + PDF/EPUB):

npm run build

Output goes to dist/.

What Happens During Build

When you run npm run build, three things happen in sequence:

  1. Site pages are generated — Your Markdown chapters and templates are turned into HTML pages
  2. Styles are built — The CSS is compiled and minified for fast loading
  3. PDF and EPUB are created — If enabled, your chapters are combined into downloadable book files in the dist/ folder

Build Commands

Command What it does
npm run start Dev server with live reload
npm run build Full production build (site + styles + PDF/EPUB)
npm run build:eleventy Build only the site pages
npm run build:tailwind Build only the CSS (minified)
npm run build:formats Generate PDF and EPUB files only

Project Structure

src/
├── _data/
│   ├── site.js            # Central configuration
│   ├── accentColors.js    # 8 color palettes
│   └── fonts.js           # Google Fonts URL builder
├── _includes/
│   ├── base.njk           # Root HTML layout
│   ├── homepage.njk       # Homepage layout
│   ├── chapter.njk        # Chapter page layout
│   ├── chapterCard.njk    # Chapter card component
│   └── tracking.njk       # Analytics snippet (empty by default)
├── chapters/
│   ├── 01-chapter-one.md
│   ├── 02-chapter-two.md
│   └── _chapter-template.md  # Starter template (excluded from build)
├── scripts/
│   └── navigation.js      # Client-side interactions
├── styles/
│   └── tailwind.css        # Tailwind entry point
├── index.njk              # Homepage
├── 404.njk                # Custom error page
├── robots.njk             # robots.txt template
└── sitemap.njk            # XML sitemap template
scripts/
└── generate-formats.js    # PDF/EPUB generation script
.eleventy.js               # Eleventy configuration
tailwind.config.js         # Tailwind configuration
netlify.toml               # Netlify deployment config

Troubleshooting

Port 8080 already in use

If you see an error about port 8080 being busy, another process is using it. Either stop that process or close the other terminal running a dev server, then try npm run start again.

Styles not updating

If you change templates and the styling looks wrong or unchanged, stop the dev server (Ctrl+C) and restart it with npm run start. The Tailwind CSS rebuild sometimes needs a fresh start to pick up new class names.

Fonts not loading

After changing fonts in site.js, restart the dev server. The Google Fonts URL is generated at build time, so a restart is needed for new fonts to take effect.

Changes to site.js not appearing

site.js is read when the build starts. After editing it, restart the dev server (Ctrl+C, then npm run start) for changes to take effect.

Next Steps

PutOut Wiki

Clone this wiki locally