---
title: "Local rendering and publishing to subpath-based sites"
description: >
  How to render projects locally
vignette: >
  %\VignetteIndexEntry{Render locally}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

## Publishing to project sites and other subpath-based hosting

GitHub Pages supports [two common types of sites](https://docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-pages#types-of-github-pages-sites):

- **User sites**, published at  
  `https://username.github.io/`
- **Project sites**, published at  
  `https://username.github.io/repository-name/`

GitHub Pages **project sites** are a very common way to publish Quarto books and websites. 
However, they require one extra step when working with multilingual projects.
The same issue can also occur on other hosting platforms where a site is published under a subpath rather than at the root of the domain.

### Rendering locally vs. final website URLs

When you render a multilingual project **locally** (for example, by running `babelquarto::render_book()` or `babelquarto::render_website()` in RStudio IDE or Positron IDE), `{babelquarto}` temporarily removes the site URL. 
This makes local previewing easier, because the site does not yet live at a real web address.
Because of this, links between languages may be written in a form that works locally but does **not** work once the site is published under a subpath, such as a GitHub Pages **project site**.
As a result, a multilingual site can look correct during local preview but have broken language links after deployment.

### How to avoid broken language links on subpath-based sites

If your site is served under a subpath (including GitHub Pages project sites), `{babelquarto}` must know the final website address when the site is rendered.
You can do this in one of two ways.

#### Option 1: Render the site using GitHub Actions (CI)

You can let GitHub build the site automatically. 
In this case, you provide the final website address using the `BABELQUARTO_CI_URL` environment variable.
This approach is recommended for users who are comfortable setting up GitHub Actions. 
See `vignette("render-with-ci")` for details.

#### Option 2: Specify the site URL when rendering locally

If you prefer to build the site on your own computer, you can pass the site’s URL directly when rendering, even if it is already listed in `_quarto.yml`:

```r
babelquarto::render_book(
  site_url = "https://username.github.io/repository-name/"
)
```

This ensures that absolute URLs including the repository subpath are generated, and that multilingual navigation works correctly after deployment.

### Summary

- Local renders are designed for previewing and may not include the final website URL.
- Sites served under a subpath (including GitHub Pages project sites) require the final site URL to be known at render time.
- To publish a multilingual project correctly to a site served under a subpath, you must either:
  - render the site using GitHub Actions, or
  - provide the site URL when rendering locally.
- Without one of these steps, multilingual navigation may break after deployment.
