A tutorial to host your Static Site on Netlify

Netlify can build a static site from a Git repository and publish the generated files to its global delivery network.

The usual workflow is simple: connect a repository, tell Netlify how to build the site, and push to your production branch. Netlify creates a new atomic deploy for every successful build.

This works with plain HTML and static site generators such as Astro, Hugo, Eleventy, and many others.

What you need to deploy

Before configuring Netlify, identify two things:

• the command that builds your site
• the directory produced by that command

For example, an Astro project normally runs:

npm run build

and writes the site to dist/.

A Hugo project normally runs:

hugo

and writes the site to public/.

Do not guess these values. Run the production build locally and check your framework’s deployment documentation.

Deploy from a Git repository

In Netlify, create a project from an existing repository and authorize the Git provider.

Select the production branch, build command, and publish directory. Netlify supports repositories hosted by GitHub, GitLab, Bitbucket, and Azure DevOps.

After the repository is connected:

• a push to the production branch can create a production deploy
• a pull or merge request creates a Deploy Preview by default
• selected non-production branches can create branch deploys

The Netlify deploy overview explains the difference between production deploys, Deploy Previews, branch deploys, and immutable deploy permalinks.

Keep build configuration in the repository

Add a netlify.toml file at the repository root:

[build]
command = "npm run build"
publish = "dist"

Configuration in netlify.toml overrides conflicting build settings in the Netlify UI. Keeping these values in the repository makes the build easier to review and reproduce.

You can also configure redirects, headers, deploy contexts, functions, and build plugins in this file.

See the file-based configuration reference for the current options.

Do not put secrets in netlify.toml. Store them as environment variables through the Netlify UI or CLI and give them only the scopes and deploy contexts they need.

Preview pull requests

When you open a pull request against a deployed branch, Netlify can build the proposed commit and publish it at a temporary URL such as:

https://deploy-preview-42--example-site.netlify.app

The preview lets people test a change before it reaches production. Netlify reports its status back to the pull request.

Preview URLs may be accessible to anyone who has the link unless you configure deploy protection. Do not assume a preview is private, and do not expose production secrets to preview builds.

Read the Deploy Previews documentation for access controls and configuration.

Deploy with the Netlify CLI

The Git workflow is not the only option. You can build locally and upload a directory with Netlify CLI.

Install the CLI in the project:

npm install --save-dev netlify-cli

Log in and link the local project:

npx netlify login
npx netlify link

Create a draft deploy:

npm run build
npx netlify deploy --no-build --dir=dist

The command returns a preview URL. After checking it, publish the same local output to production:

npx netlify deploy --prod --no-build --dir=dist

Use netlify init when you want the CLI to create or configure a new Netlify project and its continuous-deployment connection. Use netlify link when the Netlify project already exists.

The Netlify CLI guide documents both workflows.

Test Netlify behavior locally

Run:

npx netlify dev

Netlify Dev starts your framework’s development server and emulates Netlify features such as redirects, environment variables, and functions.

For a closer check of the production build configuration, use:

npx netlify build

Always run your normal project tests too. Local emulation helps, but the final deploy log remains the source of truth for Netlify’s build environment.

Add a custom domain and HTTPS

You can use a netlify.app subdomain or attach a domain you own.

Netlify shows the DNS records or nameserver changes required for the domain. Once the records resolve correctly, Netlify can provision and renew a TLS certificate for HTTPS.

DNS changes can take time to propagate. Keep the old site available until you have verified both the apex domain and any www hostname you intend to serve.

Use Netlify’s domain setup guide for the current records and HTTPS workflow.

What else can a static site use?

Netlify can add platform features around static files, including:

• redirects and custom headers
• form handling
• serverless functions
• edge functions
• deploy notifications and previews

Add only what the project needs. A site made entirely of static files has a small attack surface and a simple deployment model.

For server-side endpoints, continue with the Netlify Functions tutorial.

Related posts about services: