Index Naming Conventions

Here we look at a simple yaml value that allows one to define the name of an output file. This is useful with quarto document listings were each post is contained in a separate directory and one wants to create an index.html file but one doesn’t want dozens of index.qmd files spread across directories.

how-to
quarto
Author

Nathan Craig

Published

March 11, 2024

Modified

March 21, 2024

When using sub-directories with Quarto listing pages, I know of two possible URL’s:

Long URL: http://domain.name/listing-dir/post-subdir/filename.html

File: project-home/listing-dir/post-subdir/filename.qmd

Short URL: http://domain.name/listing-dir/post-subdir/

File: project-home/listing-dir/post-subdir/index.qmd

By making the post’s .qmd file name index.qmd one gets the shorter URL. The Quarto Tip-a-Day website post on listing pages says:

“If building a course website, you can make use of the listings feature and bundle each lesson in a folder. Then the, index.qmd file in that folder can be the landing page for the lesson and other files (slides, exercises, instructor notes, etc) can live in the lesson folder as well but not get processed as individual listing items.”

Another post on listing pages makes a similar note about file names. It is nice to have the shorter URL’s. Having post components located in a single containing directory works well and is a good way to develop content in a more or less modular way. The directory can be built stand alone, placed within the website, add some YAML, and there it goes. The content can be developed and moved around as needed.

I’ve tried it this way, it works, but I’ve run into the same issue that @charliejhadley mentions below. I often wind up with tons of index.qmd files open and it is hard to tell which is which.

Post by [@charliejhadley](https://twitter.com/charliejhadley/status/1537787931049578497?s=20&t=e089-ispLwxkk5QeKj8rDA).

Post by [@charliejhadley](https://twitter.com/charliejhadley/status/1537787931049578497?s=20&t=e089-ispLwxkk5QeKj8rDA).

Last evening, I can’t even remember what, but I stumbled on output-file and output-ext and realized these can be applied to listing pages so that files in the subdirectories don’t all have to be called index.qmd but can be whateveryouwant.qmd. If it weren’t for some smart people also having issues with index.qmd files I’d feel like this is something I should have understood much earlier.

With output-file and output-ext no more index.qmd issues.

With some yaml you can have your short URL and your sane file name. I have no idea if doing this messes with listing feeds (🤷‍♂️).

2024-03-20 Edit: All systems go.

This method is working just fine, I’m switching all blog posts over to it.

Citation

BibTeX citation:
@online{craig2024,
  author = {Craig, Nathan},
  title = {Index {Naming} {Conventions}},
  date = {2024-03-11},
  url = {https://ncraig.netlify.app/posts/2024-03-11-index-naming/index.html},
  langid = {en}
}
For attribution, please cite this work as:
Craig, Nathan. 2024. “Index Naming Conventions.” March 11, 2024. https://ncraig.netlify.app/posts/2024-03-11-index-naming/index.html.