Skip to content
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.

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

Flatten myst.yml #1308

Open
rowanc1 opened this issue Jun 13, 2024 · 2 comments
Open

Flatten myst.yml #1308

rowanc1 opened this issue Jun 13, 2024 · 2 comments
Assignees

Comments

@rowanc1
Copy link
Collaborator

rowanc1 commented Jun 13, 2024

Right now we have a few high level keys in the myst.yml including project/site/version/extends. It is confusing to users where to put the keys (mostly always under project). Additionally, when writing a shared configuration, for example, abbreviations, authors, etc. that requires you to write it under the project key.

Instead, I suggest that we lean into the single project, and flatten all keys that are in the project. Moving from:

version: 1
project:
  open_access: true
  license:
    content: Apache-2.0
    code: CC-BY-4.0
  references:
    foundations: https://projectpythia-mystmd.github.io/pythia-foundations
site:
  template: book-theme

to

version: 1
open_access: true
license:
  content: Apache-2.0
  code: CC-BY-4.0
references:
  foundations: https://projectpythia-mystmd.github.io/pythia-foundations
site:
  template: book-theme

There are still potentially some site options to configure, but they will be obviously related to the theme (nav links, footer, etc.).

@jmunroe

@fwkoch fwkoch self-assigned this Jun 15, 2024
@fwkoch
Copy link
Collaborator

fwkoch commented Jun 17, 2024

Some additional thoughts around simplifying/flattening the myst.yml:

  • Many of the project fields are also allowed on site, but it's ambiguous why they would be defined in one place or the other. Almost exclusively, they are only needed on project. I think we should move all "SiteFrontmatter" (https://github.com/executablebooks/mystmd/blob/main/packages/myst-frontmatter/src/site/types.ts#L58) to "ProjectFrontmatter" and remove them from the site config
  • With the above change, site will have way fewer fields; this means we can remove the site.options key and just define those options directly on the site.

@rowanc1
Copy link
Collaborator Author

rowanc1 commented Jun 17, 2024

Thanks @fwkoch -- I am a big fan of these changes and think it would make the onboarding simpler, and the code a lot simpler to reason about. This also is closer to mimic-ing how the exports options work, which is helpful.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants