Skip to content

Make scaffold files updatable and optional #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lundybernard wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Make scaffold files updatable and optional #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions copier.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
_subdirectory: template

# Scaffold files rendered on the first `copier copy`, but never overwritten on
# `copier update`: consumers customise these and own them thereafter. If a file
# already exists on first copy, copier keeps the existing file.
_skip_if_exists:
- Makefile
- myst.yml
- index.md
Comment on lines +6 to +9

@drammock drammock Jul 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these seem potentially useful for the end-user, although during theme development it is actually desirable to overwrite myst.yml possibly index.md and/or Makefile too.

@lundybernard lundybernard Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Valid, there are ways to work around it, if you need to overwrite those files frequently.

My concern for users updating their theme is that we don't want to clobber these.

Tell me about your dev workflow where you need to overwrite these files frequently and we can find a good solution.

@drammock drammock Jul 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

never mind. I was heavily editing footer.md.jinja and config/scientific-python.yml but not actually touching index.md.jinja or myst.yaml.jinja. and index.md.jinja is much simpler than the footer (it's just content, not really structure; the structure is inherited from book theme).

- about.md
- news.md

# Optional scaffold, decided on the first `copier copy`. When include_news is
# false, the pattern renders to "news.md" and copier excludes the file; when
# true, it renders empty and matches nothing. Do not flip the answer on
# `copier update`: a flip to false deletes news.md, and myst.yml keeps its
# News nav entry because myst.yml is in `_skip_if_exists`. To remove news
# from an existing site, delete news.md and its nav entry by hand.
_exclude:
- "{% if not include_news %}news.md{% endif %}"

project_name:
type: str
help: what is your project name?
Expand All @@ -17,3 +36,8 @@ favicon:
type: str
help: what is your project favicon?
default: "https://raw.githubusercontent.com/scientific-python/scientific-python.org/main/static/favicon.ico"

include_news:
type: bool
help: Include a news.md page? (affects the initial scaffold only)
default: true
2 changes: 2 additions & 0 deletions template/myst.yml.jinja
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,10 @@ site:
nav:
- title: About
url: /about
{% if include_news %}
- title: News
url: /news
{% endif %}
Comment on lines +10 to +13

@drammock drammock Jul 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd lean here toward just letting the user delete / modify whichever items they don't want in the nav

@lundybernard lundybernard Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I understand it, setting the include_ flags allows users to explicitly include/exclude the files/config opts. Without those, re-running copier to update their project will always add the unwanted files (manual delete each time) and overwrite their settings (resolve conflicts each time)... This won't eliminate those issues, but reduce their number.

The choices are explicit in .copier-answers.yml, and can be changed in the future, so adding a feature only requires removing it from .copier-answers.yml's exclude list and re-running copier.

The real question is still "do users only run copy once and maintain manually afterwards, or do they occasionally update the theme files?"

@drammock drammock Jul 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

after actually reading the docs of copier (instead of blindly re-running the same command every time), I realize my objections are moot. copier is quite flexible in its subcommands and flags (copy vs recopy vs update, -A to re-use answers, etc). I still have a lingering "this is more complexity than we need" feeling, but I think I'm convinced that it's not a footgun and not worth spending any more time debating; the stakes are quite low.

options:
favicon: assets/images/favicon.ico
logo: assets/images/logo.svg
Expand Down