Skip to content

GitHub Pages links break under a project subpath

Fix GitHub Pages links that work on localhost but fail under a repository path. Trace Jekyll baseurl, asset URLs, and canonicals in the deployed HTML.

By Crawlito · 5 min read

In short

  • A GitHub Pages project can live below a repository path on its public host.
  • Jekyll’s relative_url prepends the configured baseurl and absolute_url includes the host as well.
  • Public navigation, assets, and canonical links need verification on a nested production page.
On this page

When GitHub Pages opens your homepage but article links jump to the wrong site root, check the path where the project is actually published. Configure Jekyll’s url for the public origin and baseurl for the project path, then generate links using the appropriate URL filters. Test a nested page at the deployed address because a local server running at the origin root can hide this error. Jekyll configuration options

Identify which site owns the hostname and path

A user or organization site and a project site can share a host. On a default public project site, the repository name ordinarily appears in the path. A custom domain on the account site can also be inherited by project sites, which can keep their project paths. A project with its own custom domain can have a different public root. The Pages settings and the actual deployed URL tell you which arrangement is in use. GitHub’s custom domain examples

Imagine the project home is https://example.org/field-notes/. The intended article is https://example.org/field-notes/guides/sampling/. A menu anchor with href="/guides/sampling/" points to the root of example.org and loses the project prefix. A browser resolves that link correctly according to its syntax even though it breaks the publisher's intended route. Inspect the full destination shown when you hover or copy the link.

A relative link such as guides/sampling/ can work on the project homepage and fail higher or lower in the tree. Open the same shared navigation from an article several levels deep. A working header on the homepage alone cannot establish that the underlying link generation is correct. Keep one nested article, one image, one feed, and the section homepage in your sample.

Configure URL generation for this publication

For the example above, the effective Jekyll configuration might include the following values. A project actually hosted at the root uses an empty base path. Verify the configuration seen by the production build, since a deployment workflow may pass flags or set values differently from your local preview.

yaml
url: "https://example.org"
baseurl: "/field-notes"

Generate a shared navigation link from a site-relative source path. Jekyll's relative_url filter prepends the configured base path, and absolute_url generates a full address with the origin and base path. These filters are useful for different consumers. A normal internal navigation link can carry a path. A canonical or a feed entry is much easier to inspect and reuse when it identifies the complete public address. Jekyll Liquid URL filters

html
<a href="{{ '/guides/sampling/' | relative_url }}">Field sampling guide</a>
<link rel="canonical" href="{{ page.url | absolute_url }}">

Check the input to the filter. A path that already includes /field-notes/ can acquire the prefix twice. A template that concatenates site.baseurl manually and then passes the result through relative_url creates the same problem. Pick one owner for the prefix in each URL and inspect the generated HTML to confirm the outcome. Update the layout or include that all articles share before hand-editing individual links.

Inspect the production output for each kind of URL

Make a list of the paths from a generated page and label their purpose. Navigation, stylesheet URLs, image sources, social previews, feeds, and canonicals can come from different templates or plugins. One broken stylesheet may make a successful page look empty. A canonical pointing to the wrong root might leave the page visually intact while directing consumers elsewhere.

Failure on the deployed siteWhat to inspect
Links leave the project for the account siteRoot-relative links with no project prefix
URLs contain the repository name twiceA manually prepended path plus a Jekyll URL filter
Deep article works but its diagrams disappearRelative image paths resolved under the article directory
Feed links use localhostBuild configuration or environment supplying the absolute origin

Fetch a sample page directly and inspect the bytes from production. For a broken asset, request that asset too and read its status and type. A customized 404 page can return a pretty HTML document where an image was expected. Opening the page from the browser's cache can hide the problem on a developer machine. The internal link debugging guide provides a way to classify and reproduce individual failures.

Test a custom domain change without losing the project prefix

If you move only the account site to a custom domain, check the resulting URL for each public project before changing every configuration to use the domain root. GitHub documents an inherited domain case where a project remains under its repository path. If you move a project to its own custom host, verify its root and all public paths there. A domain change and a path change are separate decisions and may happen in different releases.

Build or preview with a subpath that reproduces production and open both a homepage link and a deeply nested page. Compare the expected final URL, title, asset, canonical, and return link. Use the canonical guide to investigate a healthy-looking page whose metadata still uses the old host. Check generated sitemap and feed entries against the same paths. A crawler arriving through a feed bypasses the navigation you just repaired.

After deployment, share the exact working article URL in a fresh session and check navigation back to the project. Retain a test for ordinary absolute external links as well. A broad string replacement intended to fix local paths can accidentally prepend your project path to documentation hosted elsewhere. The website migration guide covers recovery for URLs that people already bookmarked or linked.

Audit a copied Markdown link inside an article

Jekyll can generate correct navigation while a manually written guide still contains an absolute path copied from a local preview. Open an article that links to a diagram, the next chapter, and a downloadable sample. In the built HTML identify the exact values in the anchor and image attributes. A theme-level fix applies to links generated by the theme. It cannot automatically reinterpret every literal path an author pasted into Markdown.

Build a representative article using the publishing workflow and open it from the production project prefix. Follow each of the three links. Where authors need to insert site-owned paths, use the project's existing documented method for generating or resolving them. If the Markdown collection supports Liquid processing, test that the expected filter actually runs there. A page can display literal braces when content passes through a different pipeline from the theme.

Keep external references outside this repair. A link to a vendor guide should remain directly on the vendor's domain. A root-relative navigation link that intentionally goes to the account's main website can also be correct. Distinguishing these intentions avoids turning a useful link to the main organization into a broken link inside the project.

Frequently asked questions

Should baseurl contain the full host?

Jekyll documents the origin and base path as different configuration values. Use the public path portion for baseurl and use url for the origin.

Why does only the first page look correct?

The first document can load directly even when shared links or assets target a different root. Test the same navigation from a nested page to expose path resolution errors.

Do these Liquid filters work in every static site generator?

They are Jekyll filters. If a different generator builds the repository, find its equivalent base path and absolute URL settings and verify the actual generated output.

Check a deployed guide

Run the free page check on a nested GitHub Pages article. Use its final public address and compare the internal destinations and canonical with the project's configured root.

Filed under Platform guides. Topics: github-pages, internal-links, canonical, troubleshooting