Plan the design for a MyST theme with a landing page

[agoose77]

Context

Landing pages are a common pattern in community home-pages, and something that we are lacking in the open-source space for MyST sites. Whilst it is already possible emulate some of these experiences, e.g. in https://next.jupyterbook.org/ and https://2i2c.org/demo-gallery/, these deployments make heavy use of advanced MyST features like MyST plugins and custom CSS. Instead, we should make it possible to use a vanilla version of MyST with a custom theme that has better defaults for landing pages. As such, we should opt to avoid inventing new AST types, whilst taking a markup-first approach.

Relevant Productboard feature

In this user story, we should establish a design for this new theme, and

Feature ideas:

• A simple landing page could support markup-driven "sub-blocks" that can be arranged in a linear column layout.
• We should default to an index page that has a wider column (i.e. like col-body-outset).
• There should be no primary sidebar (but this will be restored, hidden, for mobile).
• The primary & secondary titles should be large and force a linear layout.
• Alternate high-level blocks should support staggered colours.

Inspiration:

• https://nextjs.org/
• https://quarto.org/
• https://remix.run/

Tasks

Preview Give feedback

1. Identify common sub-blocks and styling elements for landing page, e.g. large title,
2. Explore different mechanisms for declaring sub-blocks (e.g. top-level +++ blocks, class names, or custom directives)
3. Implement custom route for index that understands the presence of sub-blocks in the AST

Follow up work

Leverage this new theme for JB 2.0

Definition of Done

• The feature/service is technically complete

[agoose77]

We need to expand upon this to provide an MVP for the kinds of blocks, and how we configure them, etc.

[choldgraf]

Thanks for writing this up @agoose77 - it sounds like you imagine this as a separate theme from the book theme, is that right? How do you see it in relation to this mystmd issue around achieving landing pages with directives / landing page components?

• Landing Pages with widget layouts jupyter-book/myst-theme#474

A pattern that I've seen used often in Hugo is to basically have three types of pages in a site:

• A landing page (widget-based, largely defined with configuration). E.g.: https://2i2c.org
• A blog (basically collections of content but with slightly different UI that is focused on tags, categories, dates, etc). E.g.: https://2i2c.org/blog
• Arbitrary content pages (a regular old markdown page with content that is parsed into HTML)

Is there a way in MyST themes to treat some pages as different "types" from others?

[agoose77]

It sounds like you imagine this as a separate theme from the book theme, is that right?

Yes, my starting point is that we should be looking to build custom themes for custom applications. A landing page for communities feels more custom than the generic book theme.

How do you see it in relation to this mystmd issue around achieving landing pages with directives / landing page components?

I think there's a big tension here (at least, I feel it) between the benefits of a highly-constrained document model against the freedom of a full HTML canvas. I don't have the answer, but I have thoughts.

To begin with, I think there are a few different ways one could set about with building a landing page:

1. Inject raw HTML to allow users to have HTML blocks
2. Add new markup elements to introduce blocks at the AST level
3. Add a new theme that adds a block-like view over the existing AST

The fundamental difference between JB 1 and 2 at the tech level is that the themes don't just dump arbitrary CSS and JS on the page, i.e. like the Jupyter Notebook 6 → 7 transition. This constraint gives us more re-usability to e.g. embed resources from site A into site B, at a cost of expressiveness. So, at first I'd prefer not to push people into injecting HTML and CSS (i.e. (1)).

At the same time, we also benefit strongly from having a fairly closed set of nodes that we can reason about (not just for the conceptual ease, but technically too). Because of these constraints, I'm additionally keen to avoid a proliferation of new node types that are bespoke, or highly web-focused. So, adding a suite of new component-block nodes (i.e. (2)) might not be the best move either. In particular, we want a singular MyST AST spec, so we need to be cautious here.

But, the need for this Epic is clear and without dispute. My feeling is that we are not intending to provide communities with the ability to build entirely custom websites. Instead, we're tasked with finding something that opens doors for as many people as possible, and maintains the cross-functional benefits that choosing e.g. MyST gives vs mixing MyST and/or other tools like Wordpress or Hugo.

It's worth clarifying that there is 100% nuance here. MyST already understands grids, cards, and we'll add buttons in some capacity. But I do think it's a slippery slope that has consequences (i.e. how much work we need to do to bring each export target up to speed).

That's what leads me to (3). The question I'm interested in answering is:

"Can we identify a minimal set of block-types that would be useful in recreating e.g. https://cryointhecloud.com/, https://mystmd.org, https://next.jupyterbook.org, and https://projectpythia.org/, that we can build with a new "view" over existing AST types?"

I'm picturing using top-level +++ blocks with class annotations that can e.g. recognise a MyST grid etc. as e.g. a logo cloud.

Is there a way in MyST themes to treat some pages as different "types" from others?

Yes -- the route handling is functional and supports templating, so we can (by modifying book-theme, or building a derivative theme) do something special for a particular page.

[agoose77]

@choldgraf asked me to create a brief UX workflow-style write-up that helps us to align on the user experience.

Context

A user wants a website to sit alongside their Hub. This website should take advantage of the features from MyST like rich hover-previews, content embedding, etc. They would like the homepage to draw in attention and talk about the project in broad, engaging strokes. For this, they want a landing-page style home-page, that has large hero elements, and a few different components for displaying interesting highlights of the project. The user does not want to feel like they're using a separate interface to build this landing page. They want it to feel like authoring any other MyST page.

Execution

2i2c build a new MyST theme. This theme is an conceptual extension of the MyST book theme, which behaves nearly-identically. The difference is that the / index page is rendered using different logic to other pages, such as /about. The / index route is designed to show a landing-page style layout. It looks for annotations in the MyST AST that indicate how blocks of content should be presented. If the index.md page is renamed to about.md, it will render differently, but the content will remain understandable, because index.md uses the default MyST roles and directives. As such, users will create a single MyST project that is deployed with this new theme.

Users will add top-level blocks to their index.md page that separates the content into landing-page "blocks". Each block can have a kind, which we might use the class attribute for, e.g.

+++ {"class": "logo-cloud"}

This will permit users to choose from a limited set of block types. Consider logo-cloud as an example:

In MyST, we would re-create this with the following markup:

+++ {"class": "logo-cloud"}
## Trusted by the world's most innovative teams

:::{grid} 1 2 2 5
![](transistor.png)
![](reform.png)
![](tuple.png)
![](statamic.png)
:::

The landing-page route will use a LogoCloud React component to render this block, which will look for a MyST Grid and optional heading. This same pattern will apply to other block types.

The landing page will not have a table of contents. Instead, it will have a primary side-bar containing the top navigation elements that appears only once the screen size falls below a particular breakpoint.

In order to navigate between the landing page and the rest of the "book", the primary logo is links to the / index route. An additional "book" (or suitable name, e.g. "docs") top-level navigation link should link to a non-index page that is conceptually top-level. A good example of this is https://next.jupyterbook.org