posit-dev / posit-dev/great-docs

Customization options to replicate Quarto appearance

Open
#328 1 comment 0 reactions 1 assignee View on GitHub

Nobody has claimed this yet.

Difficulty: [3] Advanced Effort: [3] High Priority: [3] High Type: ★ Enhancement
Dominant language
Python
Stars
262
Forks
18
Avg merge
1d 4h
Merged PRs (30d)
14

Description

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!)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.