🛫 Add documentation for Landing Pages

[agoose77]

Note

This PR depends upon jupyter-book/myst-theme#531

This PR modifies our block transform to pull class and kind from .data, and adds documentation for the landing-page feature.

To try this PR out, build mystmd, and run it locally in the docs with e.g. env -C docs -- npx myst start --headless, then run the book-theme from the myst-theme PR.

[changeset-bot]

🦋 Changeset detected

Latest commit: 52e7f77

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
myst-transforms	Patch
myst-cli	Patch
mystmd	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[mmcky]

genuinely excited for this feature. Thanks @agoose77

[agoose77]

@rowanc1 note that if we use kind, it will mean that ipynb files that want to define landing pages will lose the notebook-cell block kind.

[choldgraf]

What about block, since we are calling these "blocks" it would be more precise than "kind". E.g.

--- {"block": "blah-blah"}

Text

--- {"block": "blah-blah-blah"}

Text

please disregard this if I'm misunderstanding the problem!

[rowanc1]

@agoose77 you can have blocks in blocks ... so I think this should be fine?

[agoose77]

Er @rowanc1 our schema states that we don't support that, which is why it's in my ➕ column for using blocks rather than directives 😅

What's the incentive for nested blocks? Shouldn't we use div for that?

[rowanc1]

Ah, yeah, for a text-only/markup notebook that is true. We don't disallow blocks inside of markdown cells in an ipynb though, so nesting is technically possible in the AST. This is also the case when we are pulling in imported files or content.

I don't think that a text-notebook actually puts in kind for the notebook content cells. Which I think is fine? I also think if you are overriding kind to be a landing-hero unit, I think that does make sense to be the override..?!

[agoose77]

I feel as though notebook-content isn't that useful, so I'm OK with it being easy to override.