What is the best way to use directory URLs (e.g. mywebsite.com/about/) instead of direct links to HTML pages (mywebsite.com/about.html)

[jozilla]

Description

I was wondering what is the recommended way to render subpages in a Quarto website to directory URLs like mywebsite.com/about/ and mywebsite.com/blog/my-first-post/ instead of linking to specific HTML pages (like mywebsite.com/about.html and mywebsite.com/blog/my-first-post.html).

The Quarto tutorial suggests creating a .qmd page for every page on your website like about.qmd. However, this results in the URL mywebsite.com/about.html

I know that you can create a directory for every subpage (like /about/) and then add an index.qmd file in that directory. That seems to work, and Quarto also automatically links to the URLs with those subdirectories for items in a listing (rather than directly to the index.html page in that subdirectory). However, one drawback is that almost every file in your Quarto website project is now called index.qmd, making it a little tricky to differentiate them in a text editor.

I'm fine with doing it this way, but I just wanted to verify if that's the recommended practice, or if there's another way of doing this, perhaps an option to never directly expose .html files?

Thanks!

[mcanouil]

The only other option is to use aliases, see https://quarto.org/docs/websites/website-navigation.html#redirects.

However, one drawback is that almost every file in your Quarto website project is now called index.qmd, making it a little tricky to differentiate them in a text editor.

Wanting mywebsite.com/about (or mywebsite.com/about/) like URL means having index.html everywhere, i.e., mywebsite.com/about is actually mywebsite.com/about/index.html.
This is not something specific to Quarto.

[jozilla]

Thanks, but I'm not sure I fully agree. While you are right that it's not specific to Quarto if you're talking about plain HTML (you would also need an index.html in that directory), but it doesn't mean the Markdown content files have to follow that exact structure. Many static site generators allow you to write a file like about.md file and generate that content in the published website as /about/index.html.

An example of this is Hugo. From the documentation:

This structure:

Results in:

As you can see here, les-miserables.md gets converted to les-miserables/index.html. I think this would be a super useful feature to have in Quarto as a one-line configuration option, perhaps something optional in the _quarto.yml configuration file. It makes it much easier to manage the website.

An alias could do the same thing, but this is such a common behaviour that I feel it's inefficient to have to specify an alias for every single Markdown file.

[mcanouil]

I am closing this as you apparently opened an issue regarding this (in the wrong repository which got transferred).

• Add project configuration option to allow pagename.md to be published to /pagename/index.html #6467

[jozilla]

OK, thanks! Sorry for using the wrong repository, I assumed quarto-cli was only for the command-line tool.

[mcanouil]

That is the case, but your feature request about structure is about Quarto CLI, since it's the tool building it.