feat(markdown): add section extraction options

Author: DavidWells

README.md

@@ -392,6 +392,11 @@ Get local file contents.
 
 **Options:**
 - `src`: The relative path to the file to pull in
+- `sections`: Comma-separated list or array of markdown section headings to include
+- `section`: Single markdown section heading to include
+- `headings`: Array of markdown heading levels to include, such as `headings={[2,3]}`
+- `removeLeadingH1`: Remove the first H1 from imported markdown
+- `shiftHeaders`: Shift imported markdown headings up or down by a number
 
 **Example:**
 ```md
@@ -415,6 +420,12 @@ Get any remote Data and put in markdown
 
 **Options:**
 - `url`: The URL of the remote content to pull in
+- `src`: Alias for `url`
+- `sections`: Comma-separated list or array of markdown section headings to include
+- `section`: Single markdown section heading to include
+- `headings`: Array of markdown heading levels to include, such as `headings={[2,3]}`
+- `removeLeadingH1`: Remove the first H1 from imported markdown
+- `shiftHeaders`: Shift imported markdown headings up or down by a number
 
 **Example:**
 ```md

docs/4-advanced-usage.md

@@ -9,6 +9,34 @@ This guide covers advanced patterns and techniques for using markdown-magic effe
 
 ## Complex Transform Combinations
 
+### Sync Selected README Sections
+
+Use `sections` when you want to include only specific README sections:
+
+```md
+<!-- docs REMOTE
+  src="https://raw.githubusercontent.com/DavidWells/example/master/README.md"
+  sections="Installation,Usage,API"
+  removeLeadingH1
+  shiftHeaders=1
+-->
+<!-- /docs -->
+```
+
+Use `headings` when you want to include every section at specific heading levels:
+
+```md
+<!-- docs FILE
+  src="./README.md"
+  headings={[2,3]}
+  removeLeadingH1
+  shiftHeaders=1
+-->
+<!-- /docs -->
+```
+
+`sections` matches normalized heading text. `headings={[2,3]}` includes all H2 and H3 sections without duplicating nested sections that are already part of a selected parent.
+
 ### Chaining Transforms
 
 You can use multiple transform blocks in sequence to build complex documentation:
@@ -321,4 +349,4 @@ module.exports = {
 3. **Testing**: Write tests for custom transforms
 4. **Documentation**: Document custom transforms and options
 5. **Validation**: Validate inputs before processing
-6. **Modularity**: Keep transforms focused and reusable
+6. **Modularity**: Keep transforms focused and reusable

packages/core/_tests/transform-file.test.js

@@ -16,6 +16,10 @@ function getNewFile(result) {
 
 const SILENT = true
 
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true })
+}
+
 test('FILE - includes local file content', async () => {
   const fileName = 'transform-file.md'
   const filePath = path.join(MARKDOWN_FIXTURE_DIR, fileName)
@@ -50,4 +54,56 @@ test('FILE - includes file with line ranges', async () => {
   assert.is(matches.length, 4, 'correct number of insertions')
 })
 
+test('FILE - extracts markdown sections and heading levels', async () => {
+  const tempDir = path.join(MARKDOWN_FIXTURE_DIR, 'temp-file')
+  ensureDir(tempDir)
+
+  const sourceFile = path.join(tempDir, 'README.md')
+  const markdownFile = path.join(tempDir, 'sections.md')
+
+  fs.writeFileSync(sourceFile, `# Package
+
+## Install
+
+Install docs.
+
+### Browser
+
+Browser docs.
+
+## Usage
+
+Usage docs.
+
+## License
+
+MIT.
+`)
+
+  fs.writeFileSync(markdownFile, `<!-- docs FILE
+  src="./README.md"
+  sections="Install"
+  headings={[3]}
+  removeLeadingH1
+  shiftHeaders=1
+-->
+original
+<!-- /docs -->`)
+
+  const result = await markdownMagic(markdownFile, {
+    open: 'docs',
+    close: '/docs',
+    outputDir: OUTPUT_DIR,
+    applyTransformsToSource: false,
+    silent: SILENT
+  })
+
+  const newContent = fs.readFileSync(getNewFile(result), 'utf8')
+  assert.ok(newContent.includes('### Install'), 'selected section was included and shifted')
+  assert.ok(newContent.includes('#### Browser'), 'nested heading was included and shifted')
+  assert.is(newContent.match(/Browser docs/g).length, 1, 'nested heading content was not duplicated')
+  assert.not.ok(newContent.includes('## Usage'), 'unselected sibling was excluded')
+  assert.not.ok(newContent.includes('## License'), 'unselected license was excluded')
+})
+
 test.run()

packages/core/_tests/transform-remote.test.js

@@ -1,6 +1,7 @@
 // Tests for remote transform
 
 const fs = require('fs')
+const http = require('http')
 const path = require('path')
 const { test } = require('uvu')
 const assert = require('uvu/assert')
@@ -23,6 +24,23 @@ function ensureDir(dir) {
 
 const SILENT = true
 
+function listen(server) {
+  return new Promise((resolve) => {
+    server.listen(0, () => {
+      resolve(server.address().port)
+    })
+  })
+}
+
+function close(server) {
+  return new Promise((resolve, reject) => {
+    server.close((err) => {
+      if (err) return reject(err)
+      resolve()
+    })
+  })
+}
+
 test('remote - fetches content from URL', async () => {
   const fileName = 'transform-remote.md'
   const filePath = path.join(MARKDOWN_FIXTURE_DIR, fileName)
@@ -141,4 +159,63 @@ original
   )
 })
 
+test('remote - extracts markdown sections and heading levels', async () => {
+  const server = http.createServer((req, res) => {
+    res.setHeader('content-type', 'text/markdown')
+    res.end(`# Package
+
+## Install
+
+Install docs.
+
+### Browser
+
+Browser docs.
+
+## Usage
+
+Usage docs.
+
+## License
+
+MIT.
+`)
+  })
+
+  const port = await listen(server)
+
+  try {
+    const content = `<!-- docs remote
+  url='http://127.0.0.1:${port}/README.md'
+  sections="Install"
+  headings={[3]}
+  removeLeadingH1
+  shiftHeaders=1
+-->
+original
+<!-- /docs -->`
+
+    ensureDir(TEMP_FIXTURE_DIR)
+    const tempFile = path.join(TEMP_FIXTURE_DIR, 'remote-sections.md')
+    fs.writeFileSync(tempFile, content)
+
+    const result = await markdownMagic(tempFile, {
+      open: 'docs',
+      close: '/docs',
+      outputDir: OUTPUT_DIR,
+      applyTransformsToSource: false,
+      silent: SILENT
+    })
+
+    const newContent = fs.readFileSync(getNewFile(result), 'utf8')
+    assert.ok(newContent.includes('### Install'), 'selected section was included and shifted')
+    assert.ok(newContent.includes('#### Browser'), 'nested heading was included and shifted')
+    assert.is(newContent.match(/Browser docs/g).length, 1, 'nested heading content was not duplicated')
+    assert.not.ok(newContent.includes('## Usage'), 'unselected sibling was excluded')
+    assert.not.ok(newContent.includes('## License'), 'unselected license was excluded')
+  } finally {
+    await close(server)
+  }
+})
+
 test.run()

packages/core/src/transforms/index.js

@@ -74,6 +74,11 @@ const transforms = {
    *
    * **Options:**
    * - `src`: The relative path to the file to pull in
+   * - `sections`: Comma-separated list or array of markdown section headings to include
+   * - `section`: Single markdown section heading to include
+   * - `headings`: Array of markdown heading levels to include, such as `headings={[2,3]}`
+   * - `removeLeadingH1`: Remove the first H1 from imported markdown
+   * - `shiftHeaders`: Shift imported markdown headings up or down by a number
    *
    * **Example:**
    * ```md
@@ -97,6 +102,12 @@ const transforms = {
    *
    * **Options:**
    * - `url`: The URL of the remote content to pull in
+   * - `src`: Alias for `url`
+   * - `sections`: Comma-separated list or array of markdown section headings to include
+   * - `section`: Single markdown section heading to include
+   * - `headings`: Array of markdown heading levels to include, such as `headings={[2,3]}`
+   * - `removeLeadingH1`: Remove the first H1 from imported markdown
+   * - `shiftHeaders`: Shift imported markdown headings up or down by a number
    *
    * **Example:**
    * ```md
@@ -208,4 +219,4 @@ const transforms = {
   install: install,
 }
 
-module.exports = transforms
+module.exports = transforms