Deploy Astro from Git: Markdown and static routes

A notebook, small blog or documentation website can become HTML files before anyone visits it. Astro builds content from Markdown and components, letting you publish the static output without keeping a development server running.

This guide uses Cuaderno orbital, an original MIT-licensed example. Open its published home page and Markdown note. The example has original CSS and artwork; it does not include accounts, payments, an API or a database.

If your site has translations, check Astro routes and same-page language switching. The diagnostic uses a local example with equivalent pages; it does not demonstrate native multilingual delivery on Hostbrid.

Check that the project is static

Read astro.config.mjs and the scripts in package.json. This example declares output: 'static', has no server adapter and runs astro build through its build script. It generates the files required by each route.

Astro can also render pages on demand. SSR, sessions, actions and live endpoints require an adapter and a compatible runtime. This recipe verifies static output only. Do not remove backend features to make an application appear compatible; read which hosting an AI-built website needs and the official output reference.

Write a Markdown note

The example keeps its note at src/pages/notas/primera-noche.md. Its frontmatter contains a title, description and the layout shared with the home page. The content becomes HTML during the build; the home page discovers notes with import.meta.glob and displays their titles and links.

Start by editing the existing note, keeping its title, description and layout fields. Another .md file in that folder creates another page and lets the list discover it on the next build. Review the list’s editorial text as you expand the notebook. The Astro Markdown documentation explains how these pages differ from content collections with a schema.

Editing a file on your computer does not update the published website. Save the change in Git and run a new build through your project’s workflow.

Build with reproducible versions

Fork or copy the repository and retain its licence. Include package.json, package-lock.json, astro.config.mjs, src and public; exclude node_modules and private keys.

The example pins Astro 7.3.7. The official installation guide requires Node 22.12.0 or later and does not support odd-numbered versions. Our local test used Node 22.23.3, recorded in .nvmrc. Hostbrid’s preset is named node22; that name does not identify an exact patch version.

npm ci
npm run build

Look for dist/index.html, dist/notas/primera-noche/index.html and dist/orbital.svg. In this small build, Astro includes CSS inside the HTML files: a separate CSS folder is not required to show that styles were applied. npm run dev and npm run preview are local tools.

Set the public URL before building

In this example, the configuration reads PUBLIC_SITE_URL to set site. It contains a public URL, never a password. The verified deployment used:

PUBLIC_SITE_URL=https://hostbrid-astro-demo.hostbrid.dev npm run build

Use your own final URL for your copy, rather than the demo’s domain. In Projects, set this variable before building. When absent, the example uses https://example.invalid and adds noindex: a safeguard for local testing, not a setting for an indexable public website. Check canonical and robots after changing it.

This variable does not configure DNS, and not every Astro repository reads it automatically. The example targets a domain root; deploying below a subpath requires adapting base, links and assets, then testing them again.

Choose the Astro preset in Projects

Follow the Projects documentation to connect Git and review its permissions. The standalone example repository used:

A monorepo needs the subfolder containing package.json and the configuration. Publish the output of dist, not the source code. These build and output settings match the official deployment guide.

Test real routes after deployment

Enter /notas/primera-noche/ directly in the browser and reload. Astro has already generated its HTML: this example needs neither a .hostbrid-spa marker nor a fallback to the home page. A route that was not generated should return 404, as should a missing asset.

Verified on 8 October 2026: commit e3bdd60 was built and published through Projects. The home page, note and image returned 200, with hashes matching the artifact and both hosting replicas. Chrome checked both routes at 390 and 1280 px, including CSS, image, links and navigation, with no overflow or POST requests. Canonical URLs used the real domain; those responses contained neither a noindex meta tag nor an X-Robots-Tag header. Missing routes and assets returned 404. This does not prove search engine indexing.

The test used our own project and a manual build. It does not verify customer signup, customer OAuth or automatic publishing on push. It also does not demonstrate Astro SSR or external services. Visit Projects and current plans to choose capacity for your account and application.