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.
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.qmdfile 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.
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.
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 (🤷♂️).
Citation
@online{craig2024,
author = {Craig, Nathan},
title = {Index {Naming} {Conventions}},
date = {2024-03-11},
url = {https://nmc.quarto.pub/nmc/posts/2024-03-11-index-naming/index.html},
langid = {en},
abstract = {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.}
}