tool that prints a subset of a markdown document
MIT License
markdown-slice
prints a subset of a markdown document
markdown-slice is a command-line tool and node API for selecting and printing a subset of a markdown document.
In order to select which part(s) of the document to print, the document is first parsed into an mdast-format AST. Then, ESQuery's CSS-selector-like language is used to target specific nodes of the AST. By specifying a start node, an end node, and which edge of each node to target (start or end), you can describe a subset of a markdown document. markdown-slice then prints the portion of the document which corresponds to your selection.
markdown-slice - prints a subset of a markdown document
usage: markdown-slice <filename> [options]
options:
--input, -i: Path to the input file to read. If unspecified, reads from stdin.
--output, -o: Path to the output file to write to. If unspecified, writes to stdout.
--from-start-of, --from-end-of: The (CSS-like) query selector string to determine where to start the slice
--to-start-of, --to-end-of: The (CSS-like) query selector string to determine where to end the slice
--from-start: Start the slice at the start of the document instead of via a query selector string
--to-end: End the slice at the end of the document instead of via a query selector string
--print: Print the AST of the file instead of slicing
--help, -h: Show this help text
examples:
# Print the first code block
markdown-slice -i README.md --from-start-of 'code' --to-end-of 'code'
# Print the first code block with lang "ts"
markdown-slice -i README.md --from-start-of 'code[lang="ts"]' --to-end-of 'code[lang="ts"]'
# Print the second code block with lang "ts"
markdown-slice -i README.md --from-start-of 'code[lang="ts"] ~ code[lang="ts"]' --to-end-of 'code[lang="ts"] ~ code[lang="ts"]'
# Print everything from the start of the document up until the table of contents
markdown-slice -i README.md --from-start --to-start-of 'heading:has(text[value="Table of Contents"])'
# Print everything after the "License" heading, including the heading itself
markdown-slice -i README.md --from-start-of 'heading:has(text[value="License"])' --to-end
# Print from the first h2 to right before the next heading
markdown-slice -i README.md --from-start-of 'heading[depth=2]' --to-start-of 'heading[depth=2] ~ heading'
# Print everything from after the "Description" heading until the next heading
markdown-slice -i README.md --from-end-of 'heading:has(text[value="Description"])' --to-start-of 'heading:has(text[value="Description"]) ~ heading'
references:
- The AST is in 'mdast' format: https://github.com/syntax-tree/mdast
- The query selector stuff is done via 'ESQuery': https://github.com/estools/esquery
npx markdown-slice --input README.md --from-start-of 'heading:has(text[value="License"])' --to-end-of 'code[lang="sh"]'
All CLI flags starting with --from
or --to
have equivalent options that can be passed into the 'markdownSlice' function:
CLI Flag | API Option | API Type |
---|---|---|
--from-start-of | fromStartOf | string |
--from-end-of | fromEndOf | string |
--to-start-of | toStartOf | string |
--to-end-of | toEndOf | string |
--from-start | fromStart | boolean |
--to-end | toEnd | boolean |
import { markdownSlice } from "markdown-slice";
const someMarkdown = `
# Hi
This is a paragraph
\`\`\`
this is a code block
\`\`\`
- this is a list
- with some items
`;
const aBitLessMarkdown = markdownSlice(someMarkdown, {
fromStartOf: "code",
toEnd: true,
});
console.log(aBitLessMarkdown);
// Prints:
//
// ```
// this is a code block
// ```
//
// - this is a list
// - with some items
MIT