fix: margin-header expects markdown

[mcanouil]

Update the documentation to reflect that the margin-header should reference a markdown file/text instead of an HTML file.

[cderv]

/deploy-preview

[github-actions]

📝 Preview Deployment

🔍 Full site preview: https://deploy-preview-1752.quarto.org

🔄 Modified Documents

• docs/websites/website-blog.qmd

[cderv]

Did you notice any issues with the feature or just documentation problem to you ?

I believe this was documenting using .html because it made more sense as the services to extract the subscription code would produce a .html file, and the content is supposed to be HTML only, with no markdown.

You're right that the documentation does not mention the raw html part,
but this is because this is handled internally in the code.

See https://github.com/quarto-dev/quarto-cli/blob/2a4799429cdfca4a055aa465bc56790d7ff0483f/src/project/types/website/website-navigation-md.ts#L716-L731

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 logic applies for all header / footer (margin, body, sidebar)

So passing a .html file directly to margin-header is supposed to work ok and content will be wrapped in raw html block.

So I don't think the documentation should be adapted here.

[cderv]

Did you notice any issues with the feature or just documentation problem to you ?

I believe this was documenting using .html because it made more sense as the services to extract the subscription code would produce a .html file, and the content is supposed to be HTML only, with no markdown.

You're right that the documentation does not mention the raw html part,
but this is because this is handled internally in the code.

See https://github.com/quarto-dev/quarto-cli/blob/2a4799429cdfca4a055aa465bc56790d7ff0483f/src/project/types/website/website-navigation-md.ts#L716-L731

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 logic applies for all header / footer (margin, body, sidebar)

So passing a .html file directly to margin-header is supposed to work ok and content will be wrapped in raw html block.

So I don't think the documentation should be adapted here.

[mcanouil]

Documentation issue which in some aspect is confusing with other part of Quarto such as listing.

The HTML file exception is to me more of a workaround from Quarto than a feature.

To me this exception should remain a fallback but the documentation should be consistent, that is "use markdown with raw code block for HTML" as it's advertised everywhere else.

[cderv]

Documentation issue which in some aspect is confusing with other part of Quarto such as listing.

It does not have the same code path as the listing, and there is no EJS templating here, so there will be a difference in documentation. Is this backed by a Github discussion or issue that shows the confusion?

The HTML file exception is to me more of a workaround from Quarto than a feature.

The way it is added and documented leads me to believe this is a feature by convenience for users. This margin header is to be extracted from a service that will write HTML. It seems convenient to save it as a .html file and insert it directly without having to modify the extension and add raw block syntax.

To me this exception should remain a fallback but the documentation should be consistent, that is "use markdown with raw code block for HTML" as it's advertised everywhere else.

I understand this. If it was a new config and new documentation, this would make sense to me to change. However, personally, I don't see the added value in modifying existing documentation that users may have already read and probably use the .html file logic. This has been working this way in Quarto since the start of this feature, based on blame.

Anyhow, I just shared the possible reason why this part on "Subscriptions" for Blog is documented with an .html file. I'll let others decide and merge.

[mcanouil]

It does not have the same code path as the listing, and there is no EJS templating here, so there will be a difference in documentation. Is this backed by a Github discussion or issue that shows the confusion?

No, but my point is that using raw HTML in markdown without raw block leads to issues (the worst being in EJS files such as listings).
The documentation states everywhere that margin-* is markdown as text or file. Only this particular example uses HTML without any explanation about why here and only here an HTML file is allowed eventhough the documentation says "markdown". This implies that you could try HTML in other places and that it should work perfectly, but that's not true.

I don't mind going the other way around and state that these margin-* support raw HTML file as well. (in this case, it means changing reference pages mostly)

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

Even if Quarto was not added the raw block it would "work" in most cases as it "works" to have plain HTML in the middle of your document (until it does not).

[mcanouil]

@cderv I'm closing this PR as I now believe the changes should be made on the other pages.
I've opened an issue to not lose track of this as I cannot made the changes now.

• margin-header, body-header, etc. should document they allow HTML quarto-cli#13270