`margin-header`, `body-header`, etc. should document they allow HTML

[mcanouil]

What would you like to do?

Report an issue on quarto.org

Description

The documentation about margin-header, body-header, etc. states that it only allows Markdown text or string, but The "subscribe" example shows the use of HTML file with raw HTML.

• https://quarto.org/docs/websites/website-blog.html#subscriptions

As pointed out by @cderv, Quarto is handling the HTML case here but does not state it does.

• quarto-cli/src/project/types/website/website-navigation-md.ts

  Lines 716 to 731 in 2a47994

  	function expandMarkdownFilePath(source: string, path: string): string {
  	const absPath = isAbsolute(path) ? path : join(dirname(source), path);
  	if (safeExistsSync(absPath)) {
  	const fileContents = Deno.readTextFileSync(absPath);
  	// If we are reading raw HTML, provide raw block indicator
  	const ext = extname(absPath);
  	if (ext === ".html") {
  	return "```{=html}\n" + fileContents + "\n```";
  	} else {
  	return fileContents;
  	}
  	} else {
  	return path;
  	}
  	}

This can lead to confusion about why some fields allow HTML while asking for Markdown but not all of them.

I initially updated the "subscribe" example (I did not know Quarto was adding the raw block at the time):

• fix: margin-header expects markdown quarto-web#1752

After some discussion, it might be better to actually document that these fields actually support HTML:

• https://quarto.org/docs/websites/website-tools.html#headers-footers
• https://quarto.org/docs/reference/projects/websites.html#section

[cscheid]

Documenting this is good, but better would be to find other instances of the same issue and make our behavior consistent.