✨ Add extends field to myst.yml for composing multiple yamls
#1215
Conversation
stevejpurves
left a comment
stevejpurves
left a comment
There was a problem hiding this comment.
looks good! would perhaps just add some tests around existing Page->Project frontmatter inheritance, since the function that was doing that previously looks like it has been made generic? and is now doing Project->Project as well as Page->Project filling...
docs/frontmatter.md
Outdated
| ``` | ||
| (composing-myst-yml)= | ||
| :::{note} Composing multiple `.yml` files |
There was a problem hiding this comment.
If the TOC PR gets in before this one is finished:
I'd recommend using that as an example here. I think a common use-case will be to have a separate toc.yml file and use this feature to bring it in (for communities that have a lot of TOC content and thus don't want to have to scroll through a huge list of pages in their config file)
There was a problem hiding this comment.
That makes sense - I'll update, depending on the order these come in...
I also suspect we will be scattering this all around the docs. E.g. where we talk about math macros, we can say "reference external macros by..." and where we talk about the toc, "reference external toc by..." etc. So hopefully this one little section won't be the only mention in the docs, long term.
docs/frontmatter.md
Outdated
| ``` | ||
| (composing-myst-yml)= | ||
| :::{note} Composing multiple `.yml` files |
There was a problem hiding this comment.
Could this be a subsection instead of a note? That way it is easier to discover in the table of contents
| site: ... | ||
| project: ... | ||
| extends: | ||
| - ../macros.yml |
There was a problem hiding this comment.
Does this work for externally-defined .yml files? (e.g. in a different github repository?)
If not, then would it be possible to download external files locally as part of the build process in a way that would work as expected here?
There was a problem hiding this comment.
Currently the files must be available locally, from a relative path at build-time (they can be outside the MyST project).
I agree we should be able to also put a url here, e.g.:
extends:
- https://example.com/my-other-myst.ymlWe get into a discussion of this over here: #336
But I think the url download/caching is a separate (smaller) PR.
|
I was just thinking of looking at this in the coming week. How exciting!!! |
fwkoch
force-pushed
the
feat/myst-yml-template
branch
from
7c45e94 to
49882d5
Compare
This PR allows users to have project frontmatter defined in multiple files (all of the same
myst.ymlformat), then the mainmyst.ymlcan bring in those other files under the top levelextendskey. A small example has been added to the docs.