posit-dev / posit-dev/great-docs

Allow `great-docs.yml` and build dir to live inside `docs`

Open
#329 4 comments 1 reaction 1 assignee View on GitHub

@has2k1 is already working on this.

Since Sep 1, 2026.

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

TLDR -- I think many users would prefer to have an option for the all the docs content live inside docs rather than at the project root, especially for complex projects.

Currently, great-docs.yml and the build dir (great-docs/) are located at project root, and each docs subsection (e.g. user_guide, examples) is also expected to live at project root.

For Python projects, the root folder can get kind of crowded. For tidiness, I personally would prefer if everything was (or at least had an option to be be) kept inside docs, including great-docs.yml, the build folder, and the content source folders. This would match how both Quarto and Sphinx work, and almost matches MkDocs, with the exception that mkdocs.yml (unlike _quarto.yml and Sphinx's conf.py) lives at root.

To be specific, Great Docs' current structure (from here) is:

your-project/
├── great-docs.yml           # Configuration (committed to git)
├── great-docs/              # Build directory (gitignored, ephemeral)
│   ├── _quarto.yml          # Generated Quarto config
│   ├── index.qmd            # Landing page (from README.md)
│   ├── ...
│   └── _site/               # Built HTML site
│       ├── index.html
│       └── ...
├── user_guide/              # Your narrative docs (optional)
│   ├── 01-installation.qmd
│   └── ...
├── pyproject.toml
├── README.md
└── your_package/
    └── ...

The proposed alternative would be:

your-project/
├── docs/
│   ├── great-docs.yml           # Configuration (committed to git)
│   ├── _build/                  # Build dir -- **was ./great-docs, now ./docs/_build**
│   │   ├── _quarto.yml          # Generated Quarto config
│   │   ├── index.qmd            # Landing page (from README.md)
│   │   └── ...
│   └── _site/                   # Built site -- **was ./great-docs/_site, now ./docs/_site**
│   ├── index.html
│   └── ...
│   ├── examples/               # Custom folder -- **would have lived at root before**
│   │   ├── 01-hello-world.qmd
│   │   └── ...
│   ├── user_guide/              # Additional narrative docs (optional)
│   │   ├── 01-installation.qmd
│   │   └── ...
│   ├── README.md
│   └── .gitignore               # Ignore **was ./great-docs, now ./_build/ and ./_site/** 
├── pyproject.toml
├── your_package/
│   └── ...

A couple notes:

  • Why move _site out of the build folder and at the same level as great-docs.yml? This is to parallel Python's build and dist folders, and because semantically the built site is distinct from the files that were used to build the site. However this part of the proposal is very much just a thought!
  • Why rename great-docs to _build? In big projects using unfamiliar libraries, it can be a pain to distinguish source files from auto-generated ones. _build makes it clear it's an artifact rather than part of the source code. Otherwise, it might be confusing that great-docs.yml is tracked but great-docs/ is untracked. (Alternatives to _build could be .great-docs, a la .quarto, or just _great-docs.)

I'd definitely be happy to not use the same folder structure as used by Sphinx/MkDocs/Quarto, if an alternative makes more sense ... but I feel that for a lot of Python projects, it's one of the more elegant layouts.

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.