custom project types should not encourage html variants

[aronatkins]

What would you like to do?

Report an issue on quarto.org

Description

The documentation for custom project type extensions should not encourage folks to create html format variations.

https://quarto.org/docs/extensions/project-types.html

The current advice is to do something like:

title: Lexdocs Project
author: Lexcorp, Inc.
version: 1.0.0
quarto-version: ">=1.2.0"
contributes:
  project:
    project:
      type: website
    format: lexdocs-html
  formats:
    html:
      theme: [default, theme.scss]
      code-overflow: wrap
      code-line-numbers: true
      filters:
        - filter.lua

It is often better to modify the HTML format rather than creating a distinct format:

title: Lexdocs Project
author: Lexcorp, Inc.
version: 1.0.0
quarto-version: ">=1.2.0"
contributes:
  project:
    project:
      type: website
    format:
      html:
        theme: [default, theme.scss]
        code-overflow: wrap
        code-line-numbers: true
        filters:
          - filter.lua

Without this adjustment, it is really easy for folks to have some arbitrary.qmd file which adjusts the HTML format. Unfortunately, that has the side-effect of effectively producing two formats for the project.