📝 docs(processing-markdown): add skills#1273
Merged
Conversation
… reference Add SKILL.md, REFERENCE.md, and EXAMPLES.md for the processing-markdown skill, providing usage patterns, function reference, and CLI examples for mq.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for the processing-markdown skill, providing users with quick references, function documentation, and practical examples for using mq (a jq-like command-line tool for Markdown processing). The documentation is well-structured and covers most of mq's capabilities.
Changes:
- Added SKILL.md with quick reference tables, common patterns, and CLI options documentation
- Added REFERENCE.md with categorized function listings for all built-in functions
- Added EXAMPLES.md with practical code examples demonstrating language features and usage patterns
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| skills/processing-markdown/SKILL.md | Provides quick reference for selectors, attributes, common patterns, and CLI options for mq |
| skills/processing-markdown/REFERENCE.md | Lists all available functions categorized by type (string, array, numeric, etc.) |
| skills/processing-markdown/EXAMPLES.md | Contains practical examples of content extraction, transformation, format conversion, and language syntax |
|
|
||
| ## Array & Collection Functions | ||
|
|
||
| `len`, `reverse`, `sort`, `sort_by(arr, fn)`, `uniq`, `unique_by(arr, fn)`, `compact`, `flatten`, `first`, `last`, `nth(arr, n)`, `min`, `max`, `group_by(arr, fn)`, `pluck(arr, key)`, `any(arr, fn)`, `all(arr, fn)`, `map(arr, fn)`, `filter(arr, fn)`, `fold(arr, init, fn)`, `select(condition)`, `range(start, end, step)` |
There was a problem hiding this comment.
The function signature select(condition) is misleading. The actual implementation in builtin.mq is select(v, f) which takes two parameters: a value and a condition function. When used with pipes (e.g., | select(.code)), the piped value becomes the first parameter automatically. Consider clarifying this behavior in the documentation or noting that the value parameter is implicit when using pipes.
Suggested change
| `len`, `reverse`, `sort`, `sort_by(arr, fn)`, `uniq`, `unique_by(arr, fn)`, `compact`, `flatten`, `first`, `last`, `nth(arr, n)`, `min`, `max`, `group_by(arr, fn)`, `pluck(arr, key)`, `any(arr, fn)`, `all(arr, fn)`, `map(arr, fn)`, `filter(arr, fn)`, `fold(arr, init, fn)`, `select(condition)`, `range(start, end, step)` | |
| `len`, `reverse`, `sort`, `sort_by(arr, fn)`, `uniq`, `unique_by(arr, fn)`, `compact`, `flatten`, `first`, `last`, `nth(arr, n)`, `min`, `max`, `group_by(arr, fn)`, `pluck(arr, key)`, `any(arr, fn)`, `all(arr, fn)`, `map(arr, fn)`, `filter(arr, fn)`, `fold(arr, init, fn)`, `select(v, condition)`, `range(start, end, step)` |
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Comment on lines
+12
to
+30
| | Selector | Description | | ||
| | ---------------- | ---------------------- | | ||
| | `.h` | All headings | | ||
| | `.h1`–`.h6` | Specific heading level | | ||
| | `.text` | Text nodes | | ||
| | `.code` | Code blocks | | ||
| | `.code_inline` | Inline code | | ||
| | `.strong` | Bold text | | ||
| | `.emphasis` | Italic text | | ||
| | `.delete` | Strikethrough | | ||
| | `.link` | Links | | ||
| | `.image` | Images | | ||
| | `.list` | List items | | ||
| | `.blockquote` | Block quotes | | ||
| | `.[][]` | Table cells | | ||
| | `.html` or `.<>` | HTML nodes | | ||
| | `.footnote` | Footnotes | | ||
| | `.math` | Math blocks | | ||
| | `.yaml`, `.toml` | Frontmatter | |
There was a problem hiding this comment.
In the table selector row, the syntax .[][][] is incorrect. Based on the implementation, table cells are accessed using .[row][column] with numeric indices. The syntax should be documented as:
.[0][0] for accessing table cells by row and column indices
The current notation .[][][] with four brackets is not valid in the mq language.
Suggested change
| | Selector | Description | | |
| | ---------------- | ---------------------- | | |
| | `.h` | All headings | | |
| | `.h1`–`.h6` | Specific heading level | | |
| | `.text` | Text nodes | | |
| | `.code` | Code blocks | | |
| | `.code_inline` | Inline code | | |
| | `.strong` | Bold text | | |
| | `.emphasis` | Italic text | | |
| | `.delete` | Strikethrough | | |
| | `.link` | Links | | |
| | `.image` | Images | | |
| | `.list` | List items | | |
| | `.blockquote` | Block quotes | | |
| | `.[][]` | Table cells | | |
| | `.html` or `.<>` | HTML nodes | | |
| | `.footnote` | Footnotes | | |
| | `.math` | Math blocks | | |
| | `.yaml`, `.toml` | Frontmatter | | |
| | Selector | Description | | |
| | ---------------- | -------------------------------- | | |
| | `.h` | All headings | | |
| | `.h1`–`.h6` | Specific heading level | | |
| | `.text` | Text nodes | | |
| | `.code` | Code blocks | | |
| | `.code_inline` | Inline code | | |
| | `.strong` | Bold text | | |
| | `.emphasis` | Italic text | | |
| | `.delete` | Strikethrough | | |
| | `.link` | Links | | |
| | `.image` | Images | | |
| | `.list` | List items | | |
| | `.blockquote` | Block quotes | | |
| | `.[0][0]` | Table cells (row 0, column 0) | | |
| | `.html` or `.<>` | HTML nodes | | |
| | `.footnote` | Footnotes | | |
| | `.math` | Math blocks | | |
| | `.yaml`, `.toml` | Frontmatter | |
Comment on lines
+12
to
+31
| | Selector | Description | | ||
| | ---------------- | ---------------------- | | ||
| | `.h` | All headings | | ||
| | `.h1`–`.h6` | Specific heading level | | ||
| | `.text` | Text nodes | | ||
| | `.code` | Code blocks | | ||
| | `.code_inline` | Inline code | | ||
| | `.strong` | Bold text | | ||
| | `.emphasis` | Italic text | | ||
| | `.delete` | Strikethrough | | ||
| | `.link` | Links | | ||
| | `.image` | Images | | ||
| | `.list` | List items | | ||
| | `.blockquote` | Block quotes | | ||
| | `.[][]` | Table cells | | ||
| | `.html` or `.<>` | HTML nodes | | ||
| | `.footnote` | Footnotes | | ||
| | `.math` | Math blocks | | ||
| | `.yaml`, `.toml` | Frontmatter | | ||
|
|
There was a problem hiding this comment.
The HTML selector documentation shows two forms: .html and .<>. Based on the selector implementation, both are valid, but it's worth noting that .<> is the symbolic shorthand. Consider adding a note that multiple selector forms exist for some elements (e.g., .blockquote and .>, .footnote and .^).
Suggested change
| | Selector | Description | | |
| | ---------------- | ---------------------- | | |
| | `.h` | All headings | | |
| | `.h1`–`.h6` | Specific heading level | | |
| | `.text` | Text nodes | | |
| | `.code` | Code blocks | | |
| | `.code_inline` | Inline code | | |
| | `.strong` | Bold text | | |
| | `.emphasis` | Italic text | | |
| | `.delete` | Strikethrough | | |
| | `.link` | Links | | |
| | `.image` | Images | | |
| | `.list` | List items | | |
| | `.blockquote` | Block quotes | | |
| | `.[][]` | Table cells | | |
| | `.html` or `.<>` | HTML nodes | | |
| | `.footnote` | Footnotes | | |
| | `.math` | Math blocks | | |
| | `.yaml`, `.toml` | Frontmatter | | |
| | Selector | Description | | |
| | ---------------------- | -------------------------------------------------------- | | |
| | `.h` | All headings | | |
| | `.h1`–`.h6` | Specific heading level | | |
| | `.text` | Text nodes | | |
| | `.code` | Code blocks | | |
| | `.code_inline` | Inline code | | |
| | `.strong` | Bold text | | |
| | `.emphasis` | Italic text | | |
| | `.delete` | Strikethrough | | |
| | `.link` | Links | | |
| | `.image` | Images | | |
| | `.list` | List items | | |
| | `.blockquote` or `.>` | Block quotes | | |
| | `.[][]` | Table cells | | |
| | `.html` or `.<>` | HTML nodes (`.<>` is the symbolic shorthand) | | |
| | `.footnote` or `.^` | Footnotes | | |
| | `.math` | Math blocks | | |
| | `.yaml`, `.toml` | Frontmatter | | |
| Some elements have both a long-form selector (for example, `.html`, `.blockquote`, `.footnote`) | |
| and a symbolic shorthand (for example, `.<>`, `.>`, `.^`). Both forms are equivalent. |
Co-authored-by: Copilot <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add SKILL.md, REFERENCE.md, and EXAMPLES.md for the processing-markdown skill, providing usage patterns, function reference, and CLI examples for mq.