🛫 Add landing page blocks to book theme

[agoose77]

Overview

This PR is an implementation of an MVP for landing page blocks to the book theme. It is being driven by the Product and Services team at 2i2c, which is tracking the work under 2i2c-org/infrastructure#5482

The goal here is to allow communities to opt-in to welcoming their audience on the home page. The design requirements for the landing page are therefore different to regular page routes. This PR follows some scoping work to figure out what a potential design might look like. The exploration process can be viewed by following the chain of issues in the 2i2c infrastructure issue above.

An example website with the proper metadata (and patched theme deployment) can be found at https://2i2c.org/cryocloud-landing-demo/.

Block Types

• split-image — a hero heading with an object-fit image cover, supporting body, links, and subtitle.
• centered — a heading with optional subtitle, links, and body that is centered on the page
• justified — a heading with optional subtitle, links, and body that is left-justified on the page
• logo-cloud — a small enhancement upon a CSS grid that centers the text and adds a semibold font style

Design Points

• Block-level landing pages feel "simple", and constrained. It feels like we should be aiming for simple and good-enough rather than enabling arbitrary web pages. Therefore, blocks do not need to be nested.
• As blocks are non-nestable, it does not make much sense to use directives. Instead, this PR uses block annotation. In the future, we could unify block attributes with MEP#003 to support e.g.

  +++ {.image-split}
  

• This is not an exhaustive set of landing-page blocks, and drops the distinction between headers and CTAs. In this PR, CTAs are just headers with buttons and/or links.

Questions for Reviewers

• What should we do about the frontmatter title and subtitle? I want to suggest that we don't use them, but then how do we stop e.g. h1 in the split-image card from being swallowed? I know that this is already an active discussion topic.

Screenshots

Related

• Custom Title/Landing Page executablebooks/sphinx-book-theme#162
• Prototype landing page edits executablebooks/sphinx-book-theme#557

[changeset-bot]

🦋 Changeset detected

Latest commit: a694d61

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

This PR includes changesets to release 15 packages

Name	Type
@myst-theme/landing-pages	Patch
myst-to-react	Patch
@myst-theme/book	Patch
@myst-theme/providers	Patch
@myst-theme/frontmatter	Patch
@myst-theme/diagrams	Patch
@myst-theme/jupyter	Patch
@myst-theme/site	Patch
@myst-theme/styles	Patch
@myst-theme/common	Patch
@myst-theme/icons	Patch
@myst-theme/search	Patch
@myst-theme/search-minisearch	Patch
@myst-theme/article	Patch
myst-demo	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

[agoose77]

I think this is ready for review. It's not 100% mergeable because I haven't gone through and checked with a fine-toothed comb. But it does work, and seems pretty simple

[choldgraf]

I think this is a nice way to design the pages via blocks. Could you add here (or linked in another PR) documentation that shows how you'd control each of the things you're adding here? E.g., at a minimum, example syntax or a page that shows off each type with example code as well.

One thought on blocks vs. directives. The main benefit I see for directives is that it gives us a more expressive way to customize blocks if they are more complex. E.g., you could have key: value options rather than getting creative about how people must structure their markdown. Did you consider that pattern and have thoughts on it?

Note that @stevejpurves 's suggestion to add inline options to blocks might make this less of a big deal if it were implemented.

[agoose77]

There are a couple of reasons for opting for blocks over directives. Firstly, I think landing page blocks should be top level, and that constraint is shared by blocks.

Secondly, authoring MyST that may be verbose inside key value options I think will feel error prone (YAML indentation etc.), and awkward.

I explicitly also do not want to add new AST types just for landing pages, as that increases the nodes that we have to talk about in our spec. To me, landing pages are a Web-only feature rather than a core part of a MyST document.

My hope is that the syntax does become nicer, e.g. +++{.split-image}.

[agoose77]

@choldgraf yes, docs and a demo are next in the todo!

[choldgraf]

That's a compelling enough rationale that I think it's safe to try and see what the UX is like once it's in practice. We can try this on the jupyter book docs and we'll also get feedback from deploying this for a few communities.

BTW - I linked two related issues from the book theme. This is actually a long-requested feature in jupyter book, it was being tracked in the book theme repo so it didn't get transferred over

[agoose77]

There are some nuances in these features that I'd like to discuss. The justified example currently uses responsive CSS to move between flex-col and flex-row so that the buttons are placed after the content for narrow screens. This works by treating "header + body" as one column, and "buttons" as another. Consequently the more buttons and links there are, the narrower the body of the CTA becomes.

Another approach would be to have two button renderers, and switch between them in CSS according to the screen size. We could also use media queries for this, but this usually means that we end up with a FOUC-like transition on page load, which is not great.

[agoose77]

I evaluated using these blocks on a Pythia landing page mockup based upon projectpythia-mystmd/projectpythia-mystmd.github.io#7

I wonder whether we should distinguish between header and content sections. The larger first-paragraph in https://tailwindui.com/components/marketing/sections/content-sections seems quite nice, e.g.

I found that the automatic CTA select for links or buttons was too eager. Instead, I tuned this to only pull out buttons. Maybe this instead should be a separate component type (justified-cta?) that takes buttons and/or applies different second-paragraph formatting.

I also observed that the way that justified buttons push the main section body to the left is visually quite jarring, e.g.

I noticed that Pythia have a lot of long hero sections. We should think about how to handle those if they should have multiple buttons? It does feel like an anti-pattern, though.

In this PR, I've not tackled how to handle the frontmatter-declared title and subtitle. That needs some thought!

[stefanv]

@agoose77 What is your workflow you use for updating the theme (this branch), and then testing it in the cryocloud-landing-demo repo?

EDIT: Found this, going to try it.

[stefanv]

Looks like, currently, there are still only these themes:

    "theme:book": "turbo run dev --parallel --filter='./themes/book'",
    "theme:article": "turbo run dev --parallel --filter='./themes/article'",

So, looks like the main changes here are to packages/landing-pages, i.e. components that can be used inside of .md files. So, I am curious how you hook up the layout; presumably that's happening elsewhere, perhaps in a fork of cryocloud-landing-demo?

[stefanv]

Trying to load that site with myst start --headless it seems to try and download the book theme, even when the template: book-theme is disabled in myst.yml.

[stefanv]

Then ending up with:

Error: Cannot find module '/home/stefan/p/myst/myst-theme/themes/book/api/index.js'
Require stack:
- /home/stefan/p/myst/myst-theme/node_modules/@remix-run/serve/dist/index.js
- /home/stefan/p/myst/myst-theme/node_modules/@remix-run/dev/dist/devServer/serve.js
- /home/stefan/p/myst/myst-theme/node_modules/@remix-run/dev/dist/cli/commands.js
- /home/stefan/p/myst/myst-theme/node_modules/@remix-run/dev/dist/cli/run.js
- /home/stefan/p/myst/myst-theme/node_modules/@remix-run/dev/dist/cli/index.js
- /home/stefan/p/myst/myst-theme/node_modules/@remix-run/dev/dist/index.js
- /home/stefan/p/myst/myst-theme/node_modules/@remix-run/dev/dist/cli.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:1249:15)
    at Function.Module._load (node:internal/modules/cjs/loader:1075:27)
    at TracingChannel.traceSync (node:diagnostics_channel:315:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:218:24)
    at Module.require (node:internal/modules/cjs/loader:1340:12)
    at require (node:internal/modules/helpers:141:16)
    at /home/stefan/p/myst/myst-theme/node_modules/@remix-run/serve/dist/index.js:43:17
    at Layer.handle [as handle_request] (/home/stefan/p/myst/myst-theme/node_modules/express/lib/router/layer.js:95:5)
    at next (/home/stefan/p/myst/myst-theme/node_modules/express/lib/router/route.js:149:13)
    at next (/home/stefan/p/myst/myst-theme/node_modules/express/lib/router/route.js:145:7)

(This is with npm run theme:book going in another tab.)

[choldgraf]

Just confirming that you've also found the theme local workflow docs!

[stefanv]

Yes, thanks! That's what I've been following.

[agoose77]

@stefanv I think you've discovered the workflow:

1. Start theme from myst-theme with npm run theme:book
2. Start dev task from myst-theme to rebuild packages/ with npm run dev
3. Run a content server for your book e.g. cryocloud-landing-demo

Something to note: mystmd still uses the template you define in myst.yml to figure out which files it needs to provide to the theme via a content server. So, theme changes like #540 require you to build the theme and make it available to mystmd. Or, just patch the template.yml in _build/templates/site/myst/book-theme/ from the theme PR version.

@stefanv let's touch base with a call if you are still stuck!

[rowanc1]

@agoose77, feel free to rebase or cherry pick up the single commit of relevant changes in #542 if easier. Content blocks change is merged in.

[stefanv]

Block Types

* `split-image` — a hero heading with an `object-fit` image cover, supporting body, links, and subtitle.

* `centered` — a heading with optional subtitle, links, and body that is centered on the page

* `justified` — a heading with optional subtitle, links, and body that is left-justified on the page

* `logo-cloud` — a small enhancement upon a CSS grid that centers the text and adds a `semibold` font style

This is great, thank you @agoose77!

I thought the snippet from the PR description was insightful for and helpful to people who want to use this. Is there a place to document all these building blocks?

[agoose77]

@stefanv thanks! The myst docs will soon ship some language on this :)

[stefanv]

Cool, happy to help review that PR.