Simplify Markdown Layouts

[Pukimaa]

Have a config system for Layouts

This is a simple example on how that could look like

// Simple

markdown: {
   defaultLayout: 'layouts/BaseLayout.astro'
}

// Advanced

markdown: {
  defaultLayout: [
    ['pages/blog/**.md', 'layouts/Blog.astro'],
    ['pages/**.md', 'layouts/BaseLayout.astro'],
  ],
}

Using _config.json (already draft pr)

{
  "setup": [
     "layout": "relative path to a Layout.astro",
     "components": "not sure how this one works yet.. seems similar but not quite to setup",
     "setup": "import Component from 'path-to-file'"
  ]
}

• Maybe use root path instead of relative path

General questions

• How does the configuration merging posited here impact SSR? Can we ensure it is performant and simple in terms of code complexity?
• Are there techniques for granular targeting collections of Markdown files other than using something like a glob?
• Because Markdown frontmatter is written in YAML and is easily serialised and manipulated, the proposed approach is viable. What if in the future a way to pass details to any Astro page became desirable? Could .astro files also receive defaults in some way? Using the glob syntax at least leaves the door open for targeting non-.md files in the future although the config naming would have to change.
• Is shallow merging OK for multiple defaults? In general it seems less likely to lead to confusion, but there are scenarios where a deep merge might be desirable:

# default
tags: ['blog']

# post.md
tags: ['food']

This proposal would see the default dropped in this scenario, but someone might expect both tags to survive.

[delucis]

Thanks for getting the ball rolling @Pukimaa.

The one thing I wasn't sure of when putting that syntax together was how important order is. Glob patterns are likely to overlap, e.g. to have a catch-all glob and then more specific patterns, so order would be the obvious way to decide which layout wins when multiple globs match.

We might need to use an array of tuples like:

markdown: {
  defaultLayout: [
    ['pages/blog/**.md', 'layouts/Blog.astro'],
    ['pages/**.md', 'layouts/BaseLayout.astro'],
  ],
}

[readonlychild]

Here is my approach (in the PR)

Draft PR 3096

While looking for where to implement, I also saw the other 2 special frontmatter fields: components and setup, being also strings.

I approached it by having a folder-level config, that way, by creating the special _config.json file, all MD files in that folder can share the fields:

{
  "layout": "relative path to a Layout.astro",
  "components": "not sure how this one works yet.. seems similar but not quite to setup",
  "setup": "import Component from 'path-to-file'"
}

[Pukimaa]

@readonlychild Would the _config.json then just be in the folder that the frontmatter should be set? So if I want all my blog posts to have the same Layout I would just place the _config.json in the blog directory?

[readonlychild]

@Pukimaa correct 👍

[Pukimaa]

That might be a nicer solution. We probably need to check if there's more than one config and if there is then throw an error. Or do you plan on handling this?

[readonlychild]

Yeah, we can flesh out the details... looking for a _config would stop when the first on is found.

• found in same folder? yes 👍 no, look in parent folder ...
• does the found _config have a layout prop? yes, 👍 , no, do not use a layout or keep searching in parent configs ???
• cascade-style

[readonlychild]

Coming back after reading Chris's comments on the next block, while the "same folder" _config could work with relative paths, going for parent configs and finding paths there, relative paths would not work. So only "absolute paths" relative to /src would work 🙃

[delucis]

Going to share my draft RFC from a couple of weeks ago for a frontmatterDefaults config approach. As mentioned on Discord, writing this helped me decide against this kind of full on defaults system, but sharing it might be helpful because some of the considerations are relevant here.

Something in particular to think about is resolving imports for layout or any setup/components. My current thinking is that keeping this in astro.config.mjs and Astro expecting any import to be relative to the project src directory, might produce the most predictable DX as otherwise you end up with something like layout: ../../layouts/Layout.astro applied at several different directory depths and confusion about how that gets resolved seems likely.

---

• Start Date: 2022-03-31
• Reference Issues:
• Implementation PR:

Summary

The ability to set defaults for Markdown frontmatter to avoid repetition across many files is often requested in Discord discussions.

This RFC proposes a way to support this.

Example

If this RFC is accepted, defaults could be provided via a markdown.frontmatterDefaults config option.

// astro.config.mjs

export default defineConfig({
  markdown: {
    frontmatterDefaults: {
      './src/pages/blog/*.md': {
        layout: '~/layouts/BlogPost.astro',
        color: 'blue'
      },
      './src/pages/products/*.md': {
        layout: '~/layouts/Product.astro',
        color: 'yellow'
      }
    }
  }
})

The defaults could be used in expressions within Markdown like existing frontmatter:

{frontmatter.color}

And would be included in the payload from Astro.fetchContent (or future similar APIs):

const [blogPost] = Astro.fetchContent('../pages/blog/*.md')
// blogPost.color === 'blue'

Motivation

The initial motivation relates to default layouts (which is a common feature request). Astro treats Markdown files differently from other kinds of pages, allowing us to wrap them in a layout component and helping to pass data from Markdown to the layout for us. However, currently each Markdown file has to specify which layout to use, which for large amounts of content can become unwieldy and difficult to maintain. Supporting defaults makes it easier and quicker to make large changes.

@natemoo-re has suggested a defaultLayout config option to specifically target this use-case. This RFC proposes generalising a defaults system to support arbitrary keys, not only layout.

Potential use cases include:

• A default setup block, allowing a user for example to import a standard collection of components without having to re-include them in every Markdown file.

• Any arbitrary data that applies across a collection of Markdown content that a user wants to ensure is consistent.

Importantly, this RFC proposes ways to apply defaults with granularity, such that different collections of content can have different defaults.

Detailed design

Config design

markdown.frontmatterDefaults is a map of glob patterns to objects describing the defaults to apply to Markdown files matching the glob.

interface AdditionToCurrentConfig {
  markdown?: {
    frontmatterDefaults?: Record<string, FrontmatterDefault>
  }
}

/** Shape of a single entry in the `frontmatterDefaults` map. */
interface FrontmatterDefault {
  layout?: string
  setup?: string
  [key: string]: any
}

Usage example

// astro.config.mjs

export default defineConfig({
  markdown: {
    frontmatterDefaults: {
      // Applies to all Markdown files
      './**/*.md': {
        layout: '~/layouts/DefaultLayout.astro',
        setup: 'import Components from "~/components/index.tsx"'
      },
      // Applies to Markdown files in the blog directory
      './src/pages/blog/**/*.md': {
        layout: '~/layouts/BlogPost.astro',
        collectionType: 'blog',
        author: {
          name: 'Laika',
          url: 'https://space.dog'
        }
      },
      // Applies only to `index.md` files
      './**/index.md': {
        layout: '~/layouts/Index.astro'
      }
    }
  }
})

Implementation

1. When loading a Markdown file, its path is tested against the keys of markdown.frontmatterDefaults.

2. Any matches are applied in order with the Markdown file’s frontmatter taking priority along the lines of:

   const finalFrontmatter = {
     ...defaultsMatch0,
     // ...
     ...defaultsMatchN,
     ...markdownFileFrontmatter
   }

Notes

• Frontmatter entries are shallow merged as the above pseudocode suggests.

• Values are copied as is. In particular, this means layout and setup defaults are resolved from the file they end up applied to. If the glob string matches files at different depths, this means relative module URLs will not work. Instead, aliases would be required to make those work seamlessly.

Example

Based on the usage example above:

1. All Markdown files would have layout and setup defaults set by the ./**/*.md entry.

   layout: ~/layouts/DefaultLayout.astro
   setup: import Components from "~/components/index.tsx"

2. Markdown files in the blog/ directory would see their layout entry set by the ./src/pages/blog/**/*.md entry (overwriting the layout from step 1 as well as receiving collectionType and author defaults.

   layout: ~/layouts/BlogPost.astro
   setup: import Components from "~/components/index.tsx"
   collectionType: blog
   author:
     name: Laika
     url: https://space.dog

3. Given an example Markdown file at ./src/pages/blog/hello-world.md with the following frontmatter

   title: Extra Special Announcement
   layout: ~/layouts/SpecialLayout.astro
   author:
     name: Veterok

   the layout set by the defaults process would be overwritten by the layout in the Markdown file itself. author.url is not inherited from the defaults, so the final frontmatter after merging would be:

   title: Extra Special Announcement
   layout: ~/layouts/SpecialLayout.astro
   setup: import Components from "~/components/index.tsx"
   collectionType: blog
   author:
     name: Veterok

Additional usage possibilities

There may be cases where defaults should be easily edited via no-code tooling (CMS, CLI, etc.). I think this would be supported with this design. For example, storing your defaults in an easy to parse and write JSON file would allow them to be imported in the Astro config:

./defaults.json

{
  "./**/*.md": {
    "layout": "~/layouts/DefaultLayout.astro"
  }
}

./astro.config.mjs

import { readFileSync } from 'node:fs'

export default {
  markdown: {
    frontmatterDefaults: JSON.parse(readFileSync('./defaults.json'))
  }
}

Similarly, thanks to top-level await, you could fetch remote resources in astro.config.mjs and use those to populate Markdown defaults.

Drawbacks

• Global defaults like this do add some complexity to a project — there are now potentially multiple sources to check to see where a specific frontmatter value is being set. This is particularly the case with multiple defaults being merged.

• Using a glob string may not be the most user-friendly way to apply defaults. An alternative is described below, but I believe it has other significant drawbacks. I’d be happy to hear alternative ideas.

• For layout and setup specifically, there is potential for confusion about how imports are resolved. I suggest a concrete option above, but it’s still an area which could trip people up. This is a significant drawback in contrast to a defaultLayout config, which could potentially be resolved by Astro.

Alternatives

File-based defaults

I also considered a directory-level special _defaults.(yml|json|js|ts) file that would apply to Markdown in the same directory and in child directories. This is a similar approach to 11ty’s idea of a “data cascade”. In some ways this is an easier to grasp way of targeting files than the glob proposal above, but it can be confusing, shards data across multiple files, and is in general quite different from how Astro tends to work so far.

Only support defaults for layouts

This is basically Nate’s defaultLayout proposal: have a config option specifically for setting the layout. This would actually unlock almost the same things as this proposal. A layout could itself apply the defaults you’re looking for (including loading them from a local config file or fetching them remotely). The key differences would be in not providing the defaults to {frontmatter} expressions and in Astro.fetchContent responses.

I imagine this alternative would still require a similar config-file syntax to support applying different default layouts to different content.

Adoption strategy

If we implement this proposal, how will existing Astro developers adopt it?

As this is a new opt-in API, developers could choose to gradually adopt it or ignore it.

Is this a breaking change? Can we write a codemod?

Not a breaking change. I suspect someone choosing to migrate all their layout keys from individual Markdown files to a config default may be beyond the scope of a codemod.

How will this affect other projects in the Astro ecosystem?

Integrations may wish to make use of this to expose variables to Markdown files. In the case of an integration extending the Astro config in this way, I would expect markdown.frontmatterDefaults to be deep merged as other config options are currently.

Unresolved questions

• How does the configuration merging posited here impact SSR? Can we ensure it is performant and simple in terms of code complexity?

• Are there techniques for granular targeting collections of Markdown files other than using something like a glob?

• Because Markdown frontmatter is written in YAML and is easily serialised and manipulated, the proposed approach is viable. What if in the future a way to pass details to any Astro page became desirable? Could .astro files also receive defaults in some way? Using the glob syntax at least leaves the door open for targeting non-.md files in the future although the config naming would have to change.

• Is shallow merging OK for multiple defaults? In general it seems less likely to lead to confusion, but there are scenarios where a deep merge might be desirable:

  # default
  tags: ['blog']
  
  # post.md
  tags: ['food']

  This proposal would see the default dropped in this scenario, but someone might expect both tags to survive.

[Pukimaa]

Thanks for this very indepth comment. I put some things into the main message now. We might need to talk about this with more people...for example which system might be better.

[delucis]

Thanks! I might not copy over that last point about shallow merging. I feel like there’s consensus around this being for layouts and at a push component imports/setup, but not for arbitrary keys (which is what my RFC draft was originally considering, but which I no longer believe is wise).

[readonlychild]

Very insightful @delucis 👍

[Pukimaa]

Thanks! I might not copy over that last point about shallow merging. I feel like there’s consensus around this being for layouts and at a push component imports/setup, but not for arbitrary keys (which is what my RFC draft was originally considering, but which I no longer believe is wise).

But I think it's kinda important for the example of tags you gave

[delucis]

I feel there’s consensus around this being for layouts and maybe component imports/setup, but not for arbitrary keys, so the tags example wouldn’t be relevant.