{"id":19607892,"url":"https://github.com/mkdoc/mkql","last_synced_at":"2025-04-27T20:32:28.397Z","repository":{"id":57298936,"uuid":"56728971","full_name":"mkdoc/mkql","owner":"mkdoc","description":"Query language for markdown documents","archived":true,"fork":false,"pushed_at":"2016-04-24T09:46:41.000Z","size":136,"stargazers_count":19,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-22T23:48:58.254Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkdoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-21T00:06:37.000Z","updated_at":"2024-12-11T22:13:09.000Z","dependencies_parsed_at":"2022-08-26T18:12:41.093Z","dependency_job_id":null,"html_url":"https://github.com/mkdoc/mkql","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkdoc","download_url":"https://codeload.github.com/mkdoc/mkql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251204565,"owners_count":21552239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T10:12:52.981Z","updated_at":"2025-04-27T20:32:28.040Z","avatar_url":"https://github.com/mkdoc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Query Language\n\n[![Build Status](https://travis-ci.org/mkdoc/mkql.svg?v=3)](https://travis-ci.org/mkdoc/mkql)\n[![npm version](http://img.shields.io/npm/v/mkql.svg?v=3)](https://npmjs.org/package/mkql)\n[![Coverage Status](https://coveralls.io/repos/mkdoc/mkql/badge.svg?branch=master\u0026service=github\u0026v=3)](https://coveralls.io/github/mkdoc/mkql?branch=master)\n\n\u003e Query a document tree with selectors\n\nExtracts nodes using a selector syntax that is a subset of the CSS selectors specification.\n\n## Install\n\n```\nnpm i mkql --save\n```\n\nFor the command line interface install [mkdoc][] globally (`npm i -g mkdoc`).\n\n---\n\n- [Install](#install)\n- [Usage](#usage)\n- [Example](#example)\n- [Selectors](#selectors)\n  - [Type Selectors](#type-selectors)\n  - [Descendant Combinator](#descendant-combinator)\n  - [Child Combinator](#child-combinator)\n  - [Adjacent Sibling Combinator](#adjacent-sibling-combinator)\n  - [Following Sibling Combinator](#following-sibling-combinator)\n  - [Attribute Selectors](#attribute-selectors)\n    - [Literal Attribute](#literal-attribute)\n    - [Content Attribute](#content-attribute)\n    - [Anchor Attributes](#anchor-attributes)\n    - [Image Attributes](#image-attributes)\n    - [Code Block Attributes](#code-block-attributes)\n    - [List Attributes](#list-attributes)\n  - [Pseudo Classes](#pseudo-classes)\n    - [Relational](#relational)\n    - [Negation](#negation)\n    - [Empty](#empty)\n  - [Pseudo Elements](#pseudo-elements)\n    - [HTML](#html)\n- [Help](#help)\n- [API](#api)\n  - [compile](#compile)\n  - [range](#range)\n  - [slice](#slice)\n  - [query](#query)\n  - [ql](#ql)\n    - [Options](#options)\n- [License](#license)\n\n---\n\n## Usage\n\nPass selectors when creating the stream:\n\n```javascript\nvar ql = require('mkql')\n  , ast = require('mkast');\n\nast.src('Paragraph\\n\\n* 1\\n* 2\\n* 3\\n\\n```javascript\\nvar foo;\\n```')\n  .pipe(ql('p, ul, pre[info^=javascript]'))\n  .pipe(ast.stringify({indent: 2}))\n  .pipe(process.stdout);\n```\n\n## Example\n\n```shell\nmkcat README.md | mkql 'p, ul, pre[info^=javascript]' | mkout\n```\n\n```shell\nprintf 'Para 1\\n\\nPara 2\\n\\n* List item\\n\\n' | mkcat | mkql '*' | mkout -y\n```\n\n## Selectors\n\nImplemented selectors work like their CSS counterparts and in some cases extensions have been added specific to markdown tree nodes.\n\n### Type Selectors\n\nTypes are based on the equivalent HTML element name, so to select a node of `paragraph` type use `p`; the universal selector `*` will select nodes of any type.\n\nThe map of standard HTML tag names to node types is:\n\n* `p`: paragraph\n* `ul`: list\n* `ol`: list\n* `li`: item\n* `h1-h6`: heading\n* `pre`: code_block\n* `blockquote`: block_quote\n* `hr`: thematic_break\n* `code`: code\n* `em`: emph\n* `strong`: strong\n* `a`: link\n* `br`: linebreak\n* `img`: image\n\nExtensions for markdown specific types:\n\n* `nl`: softbreak\n* `text`: text\n* `html`: html_block\n* `inline`: html_inline\n\n### Descendant Combinator\n\nUse whitespace for a descendant combinator or if you prefer use the explicit `\u003e\u003e` notation from CSS4:\n\n```css\nol li\nol \u003e\u003e li\n```\n\n### Child Combinator\n\nA selector such as `ol li` will find all descendants use the child combinator operator when you just want direct children:\n\n```css\nol \u003e li\n```\n\n### Adjacent Sibling Combinator\n\nThe adjacent sibling combinator is supported; select all lists that are directly preceeded by a paragraph:\n\n```css\np + ul\n```\n\n### Following Sibling Combinator\n\nThe following sibling combinator is supported; select code that is preceeded by a text node:\n\n```css\np text ~ code\n```\n\n### Attribute Selectors\n\nYou can match on attributes in the same way as usual but attributes are matched against tree nodes not HTML elements so the attribute names are often different.\n\n```css\na[href^=http://domain.com]\n```\n\nSee [attribute selectors (@mdn)](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors) for more information on the available operators.\n\nThe operator `=~` (not to be confused with `~=`) is a non-standard operator that may be used to match by regular expression pattern:\n\n```css\nimg[src=~\\.(png|jpg)$]\n```\n\n#### Literal Attribute\n\nFor all nodes that have a `literal` property you may match on the attribute.\n\n```css\np text[literal~=example]\n```\n\nNodes that have a `literal` property include:\n\n* `pre`: code_block\n* `code`: code\n* `text`: text\n* `html`: html_block\n* `inline`: html_inline\n\n#### Content Attribute\n\nThe `content` attribute is available for containers that can contain `text` nodes. This is a more powerful (but slower) method to match on the text content.\n\nConsider the document:\n\n```markdown\nParagraph with some *emphasis* and *italic*.\n```\n\nIf we select on the `literal` attribute we would get a `text` node, for example:\n\n```css\np [literal^=emph]\n```\n\nResults in the child `text` node with a literal value of `emphasis`. Often we may wish to match the parent element instead to do so use the `content` attribute:\n\n```css\np [content^=emph]\n```\n\nWhich returns the `emph` node containing the `text` node matched with the previous `literal` query.\n\nThe value for the `content` attribute is all the child text nodes concatenated together which is why it will always be less performant than matching on the `literal`.\n\n#### Anchor Attributes\n\nLinks support the `href` and `title` attributes.\n\n```css\na[href^=http://]\na[title^=Example]\n```\n\n#### Image Attributes\n\nImages support the `src` and `title` attributes.\n\n```css\nimg[src$=.jpg]\nimg[title^=Example]\n```\n\n#### Code Block Attributes\n\nCode blocks support the `info` and `fenced` attributes.\n\n```css\npre[info^=javascript]\npre[fenced]\n```\n\n#### List Attributes\n\nThe `list` and `item` types (`ul`, `ol` and `li`) support the `bullet` and `delimiter` attributes.\n\nSo you can select elements depending upon the bullet character used (unordered lists) or the delimiter (ordered lists). For the `bullet` attribute valid values are `+`, `*` and `-`; for the `delimiter` attribute valid values are `.` or `)`.\n\nThis selector will match lists declared using the `*` character:\n\n```css\nul[bullet=*]\n```\n\nOr for all ordered lists declared using the `1)` style:\n\n```css\nol[delimiter=)]\n```\n\nUse a child selector to get list items:\n\n```css\nul li[bullet=+]\n```\n\n### Pseudo Classes\n\nThe pseudo classes `:first-child`, `:last-child`, `:only-child` and `:nth-child` are supported.\n\n```css\np a:first-child\np a:last-child\nul li:nth-child(5)\nul li:nth-child(2n+1)\nul li:nth-child(odd) /* same as above */\nul li:nth-child(2n)\nul li:nth-child(even)  /* same as above */\nul li:only-child\n```\n\nSee the [:nth-child docs (@mdn)](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-child) for more information.\n\n#### Relational\n\nThe relational pseudo-class `:has` is useful for selecting parents based on a condition:\n\n```css\np:has(em)\na:has(\u003e img)\n```\n\n#### Negation\n\nThe negation pseudo-class `:not` is also available:\n\n```css\np:not(:first-child)\n```\n\n#### Empty\n\nUse the `:empty` pseudo-class to select nodes with no children:\n\n```css\np :empty\n```\n\n### Pseudo Elements\n\nUse the pseudo element prefix `::` to select elements not directly in the tree.\n\n#### HTML\n\nThe pseudo elements used to select the `html_block` and `html_inline` nodes by type are:\n\n* `::comment` Select comments `\u003c!-- --\u003e`\n* `::pi` Select processing instructions `\u003c? ?\u003e`\n* `::doctype` Select doctype declarations `\u003c!doctype html\u003e`\n* `::cdata` Select CDATA declarations `\u003c![CDATA[]]\u003e`\n* `::element` Select block and inline elements `\u003cdiv\u003e\u003c/div\u003e`\n\n```css\n::doctype           /* select doctype declarations */\np ::comment         /* select inline html comments */\n```\n\n## Help\n\n```\nUsage: mkql [-dprmnh] [--delete] [--preserve] [--range] [--multiple]\n            [--newline] [--help] [--version] \u003cselector...\u003e\n       mkql [-dprmnh] [--delete] [--preserve] [--multiple] [--newline] [--help]\n            [--version] --range \u003cstart-selector\u003e [end-selector]\n\n  Query documents with selectors.\n\nOptions\n  -d, --delete            Remove matched nodes\n  -p, --preserve          Preserve text when deleting\n  -r, --range             Execute a range query\n  -m, --multiple          Include multiple ranges\n  -n, --newline           Add line break between matches\n  -h, --help              Display help and exit\n  --version               Print the version and exit\n\nmkql@1.0.8\n```\n\n## API\n\n### compile\n\n```javascript\ncompile(source)\n```\n\nCompile a source selector string to a tree representation.\n\nReturns Object result tree.\n\n* `source` String input selector.\n\n### range\n\n```javascript\nrange(start[, end])\n```\n\nCompile a range query.\n\nWhen an `end` selector is given it must have the same number of\nselectors in the list as the `start` selector.\n\nIf the `end` selector is not given the range will end when the `start`\nselector matches again or the end of file is reached.\n\n* `start` String selector to start the range match.\n* `end` String selector to end the range match.\n\n### slice\n\n```javascript\nslice(source[, opts])\n```\n\nExecute a range query on the input nodes.\n\nReturns Range query execution object.\n\n* `source` Object compiled range query.\n* `opts` Object range query options.\n\n### query\n\n```javascript\nquery(markdown, source[, opts])\n```\n\nQuery a markdown document tree with a source selector.\n\nIf the markdown parameter is a string it is parsed into a document tree.\n\nIf the given source selector is a string it is compiled otherwise it should\nbe a previously compiled result tree.\n\nIf the source selector appears to be a range query the `slice` function is\ncalled with the range query.\n\nReturns Array list of matched nodes.\n\n* `markdown` Array|Object|String input data.\n* `source` String|Object input selector.\n* `opts` Object query options.\n\n### ql\n\n```javascript\nql([opts][, cb])\n```\n\nRun queries on an input stream.\n\nReturns an output stream.\n\n* `opts` Object processing options.\n* `cb` Function callback function.\n\n#### Options\n\n* `input` Readable input stream.\n* `output` Writable output stream.\n\n## License\n\nMIT\n\n---\n\nCreated by [mkdoc](https://github.com/mkdoc/mkdoc) on April 24, 2016\n\n[source-highlight]: https://www.gnu.org/software/src-highlite/source-highlight.html\n[mkdoc]: https://github.com/mkdoc/mkdoc\n[mktransform]: https://github.com/mkdoc/mktransform\n[commonmark]: http://commonmark.org\n[jshint]: http://jshint.com\n[jscs]: http://jscs.info\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdoc%2Fmkql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkdoc%2Fmkql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdoc%2Fmkql/lists"}