jupyter-book / mystmd

Command line tools for working with MyST Markdown.
https://mystmd.org/guide
MIT License
192 stars 60 forks source link

Flatten `myst.yml` #1308

Open rowanc1 opened 2 months ago

rowanc1 commented 2 months ago

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 commented 2 months ago

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

rowanc1 commented 2 months ago

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.