Enhancement: Extending another config

Is your feature request related to a problem? Please describe.

I’ve been working through configuring Front Matter for my site and my configuration (without adding the data types for my data files) has been getting long. I’m currently at ~750 lines and adding the data schemas will add another 500+, plus additional short codes etc.

I’m also a hugo theme developer and maintainer with multiple themes, but no way to provide my users defaults for Front Matter when using my themes.

Describe the solution you’d like

I would like an extensibility model similar to markdownlint or vale, which would allow me to package up Front Matter configuration items (data types, snippets, sorting options, content types, etc) for my users to take advantage of and extend or override as needed.

In the Front Matter config, something like:

{
  "frontMatter.extends": [
    "https://platen.io/data/frontmatter/base.frontmatter.json",
    "./local.frontmatter.json"
  ]
}

Where the configurations are merged in the order that they are specified, with any new items from local.frontmatter.json added to the settings in the remote config, and items in this config added to that merged config.

Any subkeys with the same name would replace existing keys, so if I had this config in local.frontmatter.json:

"frontMatter.content.snippets": {
  "Hint": {
    "description": "Add a colored callout hint/alert - info, warning, or danger.",
    "body": [
      "{{< hint [[type]] >}}",
      "[[&selection]]",
      "{{< /hint >}}"
    ],
    "fields": [
      {
        "name": "type",
        "title": "Type: How the hint should be styled.",
        "type": "choice",
        "choices": [
          "info",
          "warning",
          "danger"
        ],
        "default": ""
      },
      {
        "name": "selection",
        "title": "Body",
        "type": "string",
        "default": "FM_SELECTED_TEXT"
      }
    ]
  },
}

and this one in frontmatter.json at the project root:

"frontMatter.content.snippets": {
  "Hint": {
    "description": "Add a colored callout hint/alert - info, warning, or danger.",
    "body": [
      "{{< hint [[type]] >}}",
      "[[&selection]]",
      "{{< /hint >}}"
    ],
    "fields": [
      {
        "name": "type",
        "title": "Type: How the hint should be styled.",
        "type": "choice",
        "choices": [
          "info",
          "warning",
          "danger",
          "example",
          "important"
        ],
        "default": ""
      },
      {
        "name": "selection",
        "title": "Body",
        "type": "string",
        "default": "FM_SELECTED_TEXT"
      }
    ]
  },
}

The second definition of Hint would be used, making the valid choices include example and important as well as info, warning, and danger.

This would allow me to supercharge the usability of my themes for my users and make maintenance a little easier on myself at the same time.

Describe alternatives you’ve considered

I could resolve this with custom scripting (probably rising to the level of a toolkit or small app), but that would be another thing to require my users to install/track/manage, which is always extra friction.

I can see a potential for publishing Front Matter configuration setting packages that Front Matter could be aware of, but that seems like much more effort and would require a lot of UI and workflow updates and be difficult/costly to maintain (though possibly high value for users).

Additional context

I’m coming at this from both a “I have to maintain a very big complex configuration for myself” and “I would like to make delightful UX/DevX for users of my themes” which are separate but related use cases that could both benefit from a feature like this.

I’m fairly ignorant of typescript and VS Code development, but I would be happy to test this and help pitch in however you think helpful, if this feature is something you think worth bringing into the project. And if not, I’m also willing to write some scripts and document those as a workaround/prototype.

[estruyf]

@davidsneighbour @michaeltlombardi first external config support functionality got added and is up for its first tests.

How it works

In the frontmatter.json file, you can add the frontMatter.extends setting, and a list of URLs/file paths to load needs to be passed.

Here is an example:

"frontMatter.extends": [
  "https://beta.frontmatter.codes/demo/frontmatter.extends.json",
  "./config/frontmatter.config.json"
],

Info: I’ll keep the https://beta.frontmatter.codes/demo/frontmatter.extends.json file available for testing.

The order in how configuration gets applied

• Loads and applies external configuration files in the order how they are defined
• Loads the splitted configuration files (the ones in the .frontmatter/config folder)
• Loads the frontmatter.json file and overrides or merges with the other settings.

[estruyf]

Thank you for the reply @michaeltlombardi this clarifies things a lot.

Specifically for frontmatter.js vs ~/.vscode/settings.json vs .vscode/settings.json vs extended configurations, my understanding/thoughts are:

For the configuration part, first, the frontmatter.json files get used, then any settings you might have in Visual Studio Code, which for this kind of extension typically happens on the project settings.

Maybe a way to handle this would be to cache the remote configuration blob (maybe in .frontmatter/extends or similar?)

This makes sense, and we could introduce show a notification once the remote file changes with a message saying: Do you wish to update?

I publish major versions to their own file, like platen.io/frontmatter/base.v1.frontmatter.json and whenever I need to make a breaking change (if ever), I keep the last release of that major version around.

Wouldn’t this mean that the user needs to update the reference in their frontmatter.json file?

Merging and overriding

For merging I was thinking like the example you gave above:

• If the setting does not exist, it will be added
• If the setting exists on the remote/frontmatter.json, it will get overridden when it also exists locally
  • But, if the setting is an array (and only for a couple), both arrays are merged. For example, this would work for the snippets, where you have snippets coming from the remote file, and extended with the snippets locally.
  • Reason I mentioned that it only works for a couple, is for instance with the different modes you can enable for Front Matter. This is a setting that should not be extended but overwritten.

That last part makes me think.

1. Internally we need to map which settings are meant to be extended, and which to be overridden (might be the default)
2. Should the user somehow be able to decide on: whether this setting needs to be overridden or extended? What if they want to only use their snippets?