Customization options to replicate Quarto appearance

[cliffckerr]

We currently have 20-30 docsets written using Quarto + quartodoc, e.g. Sciris and Starsim, or Material for MkDocs, e.g. History Matching.

What's currently blocking us from migrating to Great Docs is the ability to keep the current styling (at least for the Quarto sites, which we spent a lot of time on the aesthetics of). Since Great Docs creates a _quarto.yml and then uses Quarto for render, this should be technically feasible: keep the Great Docs configs, but provide a pass-through mechanism to allow for arbitrary customization of the resultant _quarto.yml.

This feature proposal consists of:

• Provide a pass-through option for users who know exactly what they want (parts of) their `_quarto.yaml to look like;
• More configurability for the API reference (at minimum, being able to replicate the quartodoc layout);
• Scripts and/or agent skills to migrate a project from a Quarto docs build to a Great Docs build.

Stretch goals would be to also migrate from Material for MkDocs and Sphinx, but that (especially the latter) is a pretty substantial project and probably deserves an issue of its own!

I can try to put together a prototype of this feature in the next ~month or so on my fork and make a PR. Feel free to ping me if you can get to this first!

(As discussed today -- thanks @rich-iannone!)

[rich-iannone]

Thanks for putting this issue together! This really is the kind of adoption blocker we'd like to remove. We could have a tiered passthrough system so people can use whatever level of control they need:

1: quarto: key in great-docs.yml : Add a top-level quarto: block to great-docs.yml containing any valid _quarto.yml content. It'll merge into the generated config before the file is written. Then theming, fonts, execute settings, etc. all survive in every build.

# great-docs.yml
quarto:
  format:
    html:
      theme:
        light: [flatly, custom.scss]
        dark:  [darkly, custom.scss]
      mainfont: "Source Sans Pro"

2: first-class config options for the most common patterns (theme, custom CSS, TOC depth) so you don't need a raw quarto: block for everyday things.

3: _quarto.user.yml overlay as an expert mode, it'll be good for users who want a separate committed file that's never touched by Great Docs and merges in last.

Will develop a plan for this soon and add a note about that right here in this issue!