Relative paths

Quartos try to wrangle file paths into valid URLs, but sometimes they need help.

Spaces and Cases

Links in the <nav> menu use page filenames as labels. To avoid problems with whitespace and/or capitalization in file names, consider these alternatives:

spaces: Use underscores instead of spaces in file and folder names.; Quarto scripts automatically replace each _ with a space in <nav> labels.
cases: Use lowercase file and folder names.; Use CSS text-transform in stylesheets to capitalize <nav> labels.

Quarto scripts do not enforce these rules. Break them if you want to.

Relative URLs

Quartos use relative URLs to avoid problems when previewing pages from local files. Links which work locally should still work when you upload your site - but test them to be sure!

Here are some example links from this page's <nav> menu:

../index.html
../about.html
../boxes/can/be/nested.html
../cat_pics/octocats.html

Each <nav> also has one link to itself which is a blank anchor.

Quoted URLs

Quartos quote any prohibited characters in file paths whenever they:

build a <nav> menu
generate <script> tags
generate <img> tags in an #icons section
generate <link> tags in a <head> element

Quartos do not modify links in page <main> elements.

pages.txt

Quartos find pages recursively, then lexsort them and move index.html to the front of the queue. If you don't like the result, you can find and sort pages yourself:

Create a pages.txt file in the ready folder.
On each line, type the path from the ready folder to a page.
Any blank lines and leading/trailing whitespace will be ignored.
Sort pages in whatever order you want. Quartos will respect it.

In this example, about.html will be the last link in each <nav> menu:

index.html
boxes/can/be/nested.html
cat_pics/octocats.html
about.html

Sites will build slightly faster if pages.txt exists.