# Installation

## Installation Guide

**Skill level:** Beginner · **Time:** 10 minutes

You need two things on your computer: **Node.js** (the program that runs the theme) and a **code editor** to open the files. If you have never used a terminal before, read [Tools You Need](/margo/beginner/tools-setup/) first.

### Requirements
- **Node.js** 22.23.4 or later (the version listed under `engines` in `package.json`)
- **npm**, which comes with Node.js. Margo ships a `package-lock.json`, so use npm rather than Yarn or pnpm
- A code editor. [VS Code](https://code.visualstudio.com/) is a good free choice; Margo recommends its Astro, TOML, and Tailwind CSS extensions when you open the folder

### Install Node.js
<Tabs>
  <TabItem label="Windows">

    Download the **LTS** installer from [nodejs.org](https://nodejs.org/en/download/) and run it. Then open **PowerShell** and check the version:

    ```bash
    node -v
    ```

  </TabItem>
  <TabItem label="macOS">

    Download the installer from [nodejs.org](https://nodejs.org/en/download/), or use Homebrew:

    ```bash
    brew install node
    node -v
    ```

  </TabItem>
  <TabItem label="Linux">

    Install Node.js with your package manager or the official installer, then check the version:

    ```bash
    node -v
    ```

  </TabItem>
</Tabs>

The result must be `v22.23.4` or higher.

### Run Margo On Your Computer
<Steps>

1. Unzip the download and move the theme folder to wherever you keep your projects. Open it in your code editor. It is the folder that contains `package.json` and `AGENTS.md`.

2. Open a terminal **inside that folder**. In VS Code, use **Terminal → New Terminal**.

3. Install the dependencies (only needed once, and again after updates):

   ```bash
   npm ci
   ```

   `npm ci` installs the exact versions listed in `package-lock.json`. `npm install` works too.

4. Start the development server:

   ```bash
   npm run dev
   ```

5. Open [http://localhost:4321/](http://localhost:4321/) in your browser.

</Steps>

`npm run dev` creates the settings file from `config.toml`, watches `config.toml` for changes, and starts the site.

Leave the terminal running while you work. When you save a file, including `src/config/config.toml`, the browser updates on its own. Press <kbd>Ctrl</kbd> + <kbd>C</kbd> in the terminal to stop the server.

<Aside type="note" title="When to restart npm run dev">
  `npm run dev` watches `config.toml`: when you save it, the terminal prints
  `[toml-watcher] ✓ Generated` and the page reloads. Restart the server
  (<kbd>Ctrl</kbd> + <kbd>C</kbd>, then `npm run dev`) after you change
  `trailingSlash` or anything under `[settings.multilingual]`, after you add a
  language, and after you change `src/config/fonts.json`: Astro reads those
  only when it starts.
</Aside>

**Port 4321 already in use?** Run `npm run dev -- --port 4322`.

### Build And Preview The Production Site
```bash
npm run build
npm run preview
```

`npm run build` writes the finished site to the `dist/` folder and builds the search index. `npm run preview` builds it again and serves it at [http://localhost:4321/](http://localhost:4321/), so you can test it exactly as visitors will see it. Site search only works on a built site, so test it with `npm run preview`.

On a fresh copy, the build prints two kinds of yellow warnings. Both are expected on your computer, and both tell you what to set before you deploy:

- `[site]`: the site URL is still the placeholder `https://example.com` ([Quick Start](/margo/getting-started/quick-start/), step 1).
- `[forms]`: a form still posts to a placeholder address ([Quick Start](/margo/getting-started/quick-start/), step 8).

### Every Script, In Plain Words
| Command                                 | What it does                                                                                       |
| --------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `npm run dev`                           | Starts the local site with live reload, and converts `config.toml` each time you save it           |
| `npm run build`                         | Builds the production site into `dist/`, builds the search index, and removes drafts from the sitemap. Warns while the site URL or a form address is still a placeholder |
| `npm run preview`                       | Builds, then serves the production site locally                                                    |
| `npm run astro-check`                   | Checks components and the content files that have a schema for mistakes. It doesn't check section files or the contact, FAQ, and pricing page files. Run it before you deploy |
| `npm run format`                        | Tidies the formatting of files in `src/`                                                           |
| `npm run generate-favicons`             | Creates every favicon size from `[site.favicon] image` in `config.toml`                            |
| `npm run generate-og-image`             | Redraws the shared social image (`[opengraph] image`) with your logo, tagline, and description. Run it after you change them |
| `npm run generate-multilingual-content` | Adds a language: it copies your default language's content, menu, and labels, and adds the language to `language.json`. See [Internationalization](/margo/customization/internationalization/) |
| `npm run remove-multilingual`           | Deletes every language except your default one, French and Arabic included. Read [Internationalization](/margo/customization/internationalization/) first |
| `npm run search-index`                  | Builds the site search index from `dist/`. `build` already runs it                                 |
| `npm run remove-draft-from-sitemap`     | Removes draft pages from the built sitemap. `build` already runs it                                |
| `npm run indexnow`                      | Tells Bing and other IndexNow search engines which pages changed. Needs `[seo.ai] indexNowKey` and a deployed site (see [Deployment](/margo/deployment/)) |
| `npm run deploy:cf`                     | Uploads `dist/` to Cloudflare Pages. Needs Wrangler installed first (see [Deployment](/margo/deployment/)) |
| `npm run toml:watch`                    | Turns `config.toml` into `.astro/config.generated.json`. `dev`, `build`, `astro-check`, `generate-og-image`, and `indexnow` already run it |

Next: [Quick Start](/margo/getting-started/quick-start/), to make the site yours in about 30 minutes.