✨ feat: add frontmatter extraction examples and documentation#1384
✨ feat: add frontmatter extraction examples and documentation#1384
Conversation
There was a problem hiding this comment.
Pull request overview
Adds user-facing examples and documentation for extracting YAML frontmatter metadata in mq (playground + VSCode LSP examples + docs), addressing #1359.
Changes:
- Add a new playground example demonstrating frontmatter extraction.
- Add a new VSCode “new file” example snippet for frontmatter extraction.
- Document frontmatter extraction in the getting-started book and top-level README.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| packages/mq-playground/src/examples.ts | Adds a new “Extract frontmatter data” playground example. |
| editors/vscode/src/extension.ts | Adds a frontmatter extraction snippet to the default EXAMPLES template. |
| docs/books/src/start/example.md | Adds a “Frontmatter Operations” section with a frontmatter extraction example. |
| README.md | Adds a frontmatter extraction example to the README command examples section. |
| }, | ||
| { | ||
| name: "Extract frontmatter data", | ||
| code: `import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title)`, |
There was a problem hiding this comment.
The if (.yaml): yaml::yaml_parse() | get(:title) example is parsed as (if (.yaml): yaml::yaml_parse()) | get(:title), meaning get(:title) runs for non-frontmatter nodes too and relies on get(None, …) -> None. To make the example clearer (and ensure both steps are conditional), wrap the piped expressions in a do ... end block inside the if.
| code: `import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title)`, | |
| code: `import "yaml" | if (.yaml): do yaml::yaml_parse() | get(:title) end`, |
| mq '.[1][2] | to_text()' data.md | ||
|
|
||
| # Extract frontmatter metadata from markdown files: | ||
| import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title) |
There was a problem hiding this comment.
The README’s mq query uses if (.yaml): yaml::yaml_parse() | get(:title), which is parsed as (if (.yaml): yaml::yaml_parse()) | get(:title); get(:title) still runs for non-frontmatter nodes and relies on get(None, …) -> None. For a clearer copy/paste example, consider wrapping the piped expressions in do ... end inside the if (in addition to making it a runnable mq '…' file.md command).
| import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title) | |
| mq 'import "yaml" | if (.yaml): do yaml::yaml_parse() | get(:title) end' file.md |
| mq '.[1][2] | to_text()' data.md | ||
|
|
||
| # Extract frontmatter metadata from markdown files: | ||
| import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title) |
There was a problem hiding this comment.
This README snippet is inside a ```sh code block where all other examples are shell commands, but the new frontmatter line isn’t a runnable command (it’s missing the mq '…' <file> wrapper/quoting). As written, it will fail if copied into a shell; please format it like the other examples (invoke `mq` with the query quoted and include a sample input file).
| import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title) | |
| mq 'import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title)' data.md |
| Extract frontmatter metadata from markdown files: | ||
|
|
||
| ```mq | ||
| import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title) |
There was a problem hiding this comment.
In mq syntax, if (cond): expr1 | expr2 parses as (if (cond): expr1) | expr2, so get(:title) will run even when the condition is false and relies on get(None, …) -> None. If you intend both steps to be conditional (and to better match the control-flow docs), wrap the piped expressions in a do ... end block under the if.
| import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title) | |
| import "yaml" | if (.yaml): do yaml::yaml_parse() | get(:title) end |
| include "csv" | csv_parse("a,b,c\n1,2,3\n4,5,6", true) | csv_to_markdown_table() | ||
|
|
||
| # Extract Front Matter | ||
| import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title) |
There was a problem hiding this comment.
This example uses if (.yaml): yaml::yaml_parse() | get(:title). In mq, the pipe after the if is outside the if body ((if (.yaml): yaml::yaml_parse()) | get(:title)), so get(:title) is evaluated for all nodes and relies on get(None, …) -> None. Consider wrapping the pipeline in do ... end inside the if to make the conditional scope explicit and avoid unnecessary work.
| import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title) | |
| import "yaml" | if (.yaml): do yaml::yaml_parse() | get(:title) end |
Closes #1359