custom project types should not encourage html variants

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.

Start with the custom project types documentation at quarto.org/docs/extensions/project-types.html and compare the current YAML example with the proposed format configuration. Update the guidance so it modifies the HTML format rather than encouraging a distinct HTML variant, then verify the example consistently shows a single project format.