posit-dev / posit-dev/great-docs
Allow `great-docs.yml` and build dir to live inside `docs`
@has2k1 is already working on this.
Since Sep 1, 2026.
- 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
_siteout of the build folder and at the same level asgreat-docs.yml? This is to parallel Python'sbuildanddistfolders, 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-docsto_build? In big projects using unfamiliar libraries, it can be a pain to distinguish source files from auto-generated ones._buildmakes it clear it's an artifact rather than part of the source code. Otherwise, it might be confusing thatgreat-docs.ymlis tracked butgreat-docs/is untracked. (Alternatives to_buildcould 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.