Local rendering and publishing to subpath-based sites

Publishing to project sites and other subpath-based hosting

GitHub Pages supports two common types of 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.

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:

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.