@p-buddy/parkdown 0.0.4 → 0.0.5

package/README.md

@@ -1,15 +1,16 @@
-# parkdown (p▼)
+# parkdown (p↓)
 
 `parkdown` allows you to include other file's content within your markdown using a link with no text (i.e. `[](<url>)`), where `<url>` corresponds to either:
   - a local file, e.g. `[](./other.md)` or `[](../root.ts)`
   - **_COMING SOON_**: An external link 
 
-Markdown renderers shouldn't display these links, but [parkdown]() can process and populate them. Also, your editor hopefully makes these links easy to navigate to, improving productivity.
+Markdown renderers shouldn't display these links, but [parkdown](https://www.npmjs.com/package/@p-buddy/parkdown) can process and populate them. Also, your editor hopefully makes these links easy to navigate to, improving productivity.
 
-Collectively, [parkdown]() enables your documentation to behave a little more like code, and for your code to have a rightful place in your documentation.
+Collectively, [parkdown](https://www.npmjs.com/package/@p-buddy/parkdown) enables your documentation to behave a little more like code, and for your code to have a rightful place in your documentation.
 
 [](./.assets/invocation.md)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 29 chars: 796 -->
 ## Invocation
 
 Invoke [parkdown's]() functionality with either the [cli](#cli-inclusions) or via the `processMarkdownIncludes` [export](#populateMarkdownIncludes-export):
@@ -18,28 +19,32 @@ Invoke [parkdown's]() functionality with either the [cli](#cli-inclusions) or vi
 
 The following commands are all equivalent:
 ```bash
-npx parkdown --file ./README.md
-npx parkdown -f README.md
-npx parkdown # defaults to processing inclusions in the 'README.md' file of the current working directory
+npx @p-buddy/parkdown --file ./README.md
+npx @p-buddy/parkdown -f README.md
+npx @p-buddy/parkdown # defaults to processing inclusions in the 'README.md' file of the current working directory
 ```
 
 ### `populateMarkdownIncludes` export
 
-[](.assets/code/inclusions.ts?region=replace(pkg,'''parkdown'''))
-<!-- p▼ BEGIN -->
+[](.assets/code/inclusions.ts?region=replace(pkg,'''@p-buddy_slash_parkdown''',_))
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 10 chars: 172 -->
+
 ```ts
-import { populateMarkdownInclusions } from "parkdown";
+import { populateMarkdownInclusions } from "@p-buddy/parkdown";
 
 const file = "README.md";
 const writeFile = true;
 
 populateMarkdownInclusions(file, writeFile);
 ```
-<!-- p▼ END -->
-<!-- p▼ END -->
+
+<!-- p↓ END -->
+<!-- p↓ END -->
 
 [](./.assets/authoring.md)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 558 chars: 17214 -->
 ## Authoring
 
 You author inclusions in your markdown files using a link with no text i.e. `[](<url>)`, where `<url>` points to some local or remote text resource (e.g.`./other.md`, `https://example.com/remote.md`).
@@ -57,84 +62,110 @@ There are two equivalent ways to author inline inclusions, [single-line](#single
 What you write:
 
 [](.assets/unpopulated/inline.single.md?wrap=code)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 5 chars: 40 -->
+
 ```md
 Before... [](<url>) ...After
 ```
-<!-- p▼ END -->
 
-What is rendered (**_before_** processing, same as [Option B](#option-b-multi-line)):
+<!-- p↓ END -->
+
+<details>
+<summary>See rendering and processing output</summary>
+
+What is rendered (**_before_** processing, same as [Multi-line](#multi-line)):
 
 [](.assets/unpopulated/inline.single.md?wrap=quote&inline)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 1 chars: 30 -->
 > Before... [](<url>) ...After
-<!-- p▼ END -->
+<!-- p↓ END -->
 
 What your markdown file contains (**_after_** processing):
 
 [](.assets/populated/inline.single.md?wrap=code)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 7 chars: 120 -->
+
 ```md
-Before... [](<url>) <!-- p▼ Begin -->
+Before... [](<url>) <!-- p↓ Begin -->
 ...Included Content...
-...Included Content... <!-- p▼ End --> ...After
+...Included Content... <!-- p↓ End --> ...After
 ```
-<!-- p▼ END -->
 
-What is rendered (**_after_** processing, same as [Option B](#option-b-multi-line)):
+<!-- p↓ END -->
+
+What is rendered (**_after_** processing, same as [Multi-line](#multi-line)):
 
 [](.assets/populated/inline.single.md?wrap=quote&inline)
-<!-- p▼ BEGIN -->
-> Before... [](<url>) <!-- p▼ Begin -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 3 chars: 110 -->
+> Before... [](<url>) <!-- p↓ Begin -->
 ...Included Content...
-...Included Content... <!-- p▼ End --> ...After
-<!-- p▼ END -->
+...Included Content... <!-- p↓ End --> ...After
+<!-- p↓ END -->
+
+</details>
 
 #### Multi-line
 
 What you write:
 
 [](.assets/unpopulated/inline.multi.md?wrap=code)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 7 chars: 41 -->
+
 ```md
 Before... 
 [](<url>)
 ...After
 ```
-<!-- p▼ END -->
 
-What is rendered (**_before_** processing, same as [Option A](#option-a-single-line)):
+<!-- p↓ END -->
+
+<details>
+<summary>See rendering and processing output</summary>
+
+What is rendered (**_before_** processing, same as [Single-line](#single-line)):
 
 [](.assets/unpopulated/inline.multi.md?wrap=quote&inline)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 3 chars: 31 -->
 > Before... 
 [](<url>)
 ...After
-<!-- p▼ END -->
+<!-- p↓ END -->
 
 What your markdown file contains (**_after_** processing):
 
 [](.assets/populated/inline.multi.md?wrap=code)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 9 chars: 122 -->
+
 ```md
 Before... 
-[](<url>) <!-- p▼ Begin -->
+[](<url>) <!-- p↓ Begin -->
 ...Included Content...
-...Included Content... <!-- p▼ End --> 
+...Included Content... <!-- p↓ End --> 
 ...After
 ```
-<!-- p▼ END -->
 
-What is rendered (**_after_** processing, same as [Option A](#option-a-single-line)):
+<!-- p↓ END -->
+
+What is rendered (**_after_** processing, same as [Single-line](#single-line)):
 
 [](.assets/populated/inline.multi.md?wrap=quote&inline)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 5 chars: 112 -->
 > Before... 
-[](<url>) <!-- p▼ Begin -->
+[](<url>) <!-- p↓ Begin -->
 ...Included Content...
-...Included Content... <!-- p▼ End --> 
+...Included Content... <!-- p↓ End --> 
 ...After
-<!-- p▼ END -->
+<!-- p↓ END -->
+
+</details>
 
 ### Block
 
@@ -143,7 +174,9 @@ Block inclusions occur when your "empty" link is the **only** node in a [paragra
 What you write:
 
 [](.assets/unpopulated/block.md?wrap=code)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 9 chars: 42 -->
+
 ```md
 Before...
 
@@ -151,12 +184,18 @@ Before...
 
 ...After
 ```
-<!-- p▼ END -->
+
+<!-- p↓ END -->
+
+<details>
+<summary>See rendering and processing output</summary>
 
 What is rendered (**_before_** processing):
 
 [](.assets/unpopulated/block.md?wrap=quote)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 11 chars: 61 -->
+
 <blockquote>
 
 Before...
@@ -167,47 +206,55 @@ Before...
 
 </blockquote>
 
-<!-- p▼ END -->
+<!-- p↓ END -->
 
 What your markdown file contains (**_after_** processing):
 
 [](.assets/populated/block.md?wrap=code)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 13 chars: 124 -->
+
 ```md
 Before...
 
 [](<url>)
-<!-- p▼ Begin  -->
+<!-- p↓ Begin  -->
 ...Included Content...
 ...Included Content...
-<!-- p▼ End  -->
+<!-- p↓ End  -->
 
 ...After
 ```
-<!-- p▼ END -->
+
+<!-- p↓ END -->
 
 What is rendered (**_after_** processing):
 
 [](.assets/populated/block.md?wrap=quote)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 15 chars: 143 -->
+
 <blockquote>
 
 Before...
 
 [](<url>)
-<!-- p▼ Begin  -->
+<!-- p↓ Begin  -->
 ...Included Content...
 ...Included Content...
-<!-- p▼ End  -->
+<!-- p↓ End  -->
 
 ...After
 
 </blockquote>
 
-<!-- p▼ END -->
+<!-- p↓ END -->
+
+</details>
 
 [](.assets/query.md?heading=-1)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 347 chars: 12711 -->
 ### Query parameters
 
 You can pass query parameters to your inclusion links to control how their content is processed and included within your markdown.
@@ -215,7 +262,9 @@ You can pass query parameters to your inclusion links to control how their conte
 #### Processing Order
 
 [](src/include.ts?&region=extract(query))
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 10 chars: 322 -->
+
 ```ts
 const params = new URLSearchParams(query);
 const regions = params.get("region")?.split(COMMA_NOT_IN_PARENTHESIS);
@@ -224,7 +273,8 @@ const headingModfiier = params.get("heading") ?? 0;
 const inlineOverride = params.has("inline");
 const wraps = params.get("wrap")?.split(COMMA_NOT_IN_PARENTHESIS);
 ```
-<!-- p▼ END -->
+
+<!-- p↓ END -->
 
 #### `region`
 
@@ -238,14 +288,16 @@ Specifiers will be searched for within the file's comments, and are expected to
 /** some-specifier */
 ```
 
-```md
-[](...?region=extract(some-specifier))
-```
+Below is the currently supported API for the `region` query parameter, where each defined method signature can be _invoked_ as a value for the `region` parameter, for example:
 
-Below is the currently supported API for the `region` query parameter, where each defined method signature can be _invoked_ as a value for the `region` parameter (e.g. `[](<url>?region=extract(some-specifier))`, `[](<url>?region=remove(some-specifier))`, `[](<url>?region=replace(some-specifier))`).
+- `[](<url>?region=extract(some-specifier))`
+- `[](<url>?region=remove(some-specifier))`
+- `[](<url>?region=replace(some-specifier,replacement-content))`
 
 [](.assets/api-note.md?wrap=quote)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 9 chars: 352 -->
+
 <blockquote>
 
 **_NOTE ON API USAGE:_** As you can see from the included examples, each _invocation_ of an API method looks like a less strict (more quirky) version of a typical javascript function invocation. 
@@ -254,28 +306,61 @@ Please see the [full explanation](#query-parameters-with-function-like-apis) to
 
 </blockquote>
 
-<!-- p▼ END -->
+<!-- p↓ END -->
 
 [](src/region.ts?region=extract(definition))
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 36 chars: 1651 -->
+
 ```ts
 const definitions = [
+  /**
+   * Extract regions from the retrieved content between comments that INCLUDE the specified ids.
+   * @param id The id of the comment to extract.
+   * @param 0 An optional additional id to extract.
+   * @param 1 An optional additional id to extract.
+   * @param 2 An optional additional id to extract.
+   * @example [](<url>?region=extract(specifier))
+   * @example [](<url>?region=extract(specifier,other-specifier,some-other-specifier))
+   */
   "extract(id: string, 0?: string, 1?: string, 2?: string)",
+  /**
+   * Remove regions from the retrieved content between comments that INCLUDE the specified ids.
+   * @param id The id of the comment to remove.
+   * @param 0 An optional additional id to remove.
+   * @param 1 An optional additional id to remove.
+   * @param 2 An optional additional id to remove.
+   * @example [](<url>?region=remove(specifier))
+   * @example [](<url>?region=remove(specifier,other-specifier,some-other-specifier))
+   */
   "remove(id: string, 0?: string, 1?: string, 2?: string)",
+  /**
+   * Replace regions from the retrieved content between comments that INCLUDE the specified ids.
+   * @param id The id of the comment to replace.
+   * @param with The replacement content (if ommitted, the content of the detected comment will be used).
+   * @param space The space character to use between words in the replacement content (defaults to `-`).
+   * @example [](<url>?region=replace(specifier))
+   * @example [](<url>?region=replace(specifier,new-content))
+   * @example [](<url>?region=replace(specifier,new_content,_)
+   */
   "replace(id: string, with?: string, space?: string)",
 ]
 ```
-<!-- p▼ END -->
+
+<!-- p↓ END -->
 
 #### `skip`
 
 Skip the default processing behavior for the given type of file. 
 
 [](src/include.ts?wrap=dropdown(See-default-processing-behavior.)&region=extract(Default-Behavior),replace(...))
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 17 chars: 267 -->
 
 <details>
-<summary>See default processing behavior.</summary>
+<summary>
+See default processing behavior.
+</summary>
 
 ```ts
 if (extension === "md") {
@@ -285,9 +370,10 @@ if (extension === "md") {
 else if (/^(js|ts)x?|svelte$/i.test(extension))
   content = wrap(content, "code", ...);
 ```
+
 </details>
 
-<!-- p▼ END -->
+<!-- p↓ END -->
 
 ```md
 [](<url>?skip)
@@ -295,36 +381,66 @@ else if (/^(js|ts)x?|svelte$/i.test(extension))
 
 #### `heading` 
 
-Modify the heading depth applied to included content. By default, the headings of the included content are adjusted to be one-level below their parent heading.
+Modify the heading depth applied to included content. By default, the headings of the included content are adjusted to be one-level below their parent heading (i.e. the heading the included content falls under).
 
-In the following example, the headings within the included content of `<url>` will be adjusted to one-level below the parent heading (which is an `h2` / `##`), so any `#` headings will be converted to `###` headings, and `##` headings will be converted to `####` headings, and so on.
+You might commonly see `[](<url>?heading=-1)` used to ensure that the included content's heading level is the same as it's parent heading.
+
+<details>
+<summary>
+See example usage:
+</summary>
+Assuming you have the following markdown files:
 
 ```md
-## Heading
+<!-- to-be-included.md -->
+# Included Heading
+```
 
-[](<url>)
+```md
+<!-- README.md -->
+# Heading
+
+[](./to-be-included.md)
 ```
 
-The following would then ensure that the headings of the included content are at the same level as the parent heading.
+When `README.md` is processed, it will be transformed into the following:
 
 ```md
-## Heading
+# Heading
 
-[](<url>?heading=-1)
+## Included Heading
 ```
 
-A value of `-2` would result in the headings of the included content being at their original level (since the content is being included underneath an `h2` / `##` heading).
+Where the included content's heading has been modified to be one-level below the parent heading (i.e. it is converted from an `h1` / `#` heading to a `h2` / `##` heading — `h1 + 1 = h2`).
+
+If we instead wanted the included heading to remain a `h1` / `#` heading, we'd make use of the `heading` query parameter with a value of `-1` (since `h1 + 1 - 1 = h1`), like so:
+
+```md
+<!-- README.md -->
+# Heading
+
+[](./to-be-included.md?heading=-1)
+```
+
+</details>
 
 #### `inline` (Advanced)
 
+Force a replacement target to be treated as [inline](#inline) content.
+
 #### `wrap`
 
 Wrap the content of the included file in a specific kind of element.
 
-Below is the currently supported API for the `wrap` query parameter, where each defined method signature can be _invoked_ as a value for the `wrap` parameter (e.g. `[](<url>?wrap=code)`, `[](<url>?wrap=dropdown(hello-world))`).
+Below is the currently supported API for the `wrap` query parameter, where each defined method signature can be _invoked_ as a value for the `wrap` parameter, for example:
+
+- `[](<url>?wrap=code)`
+- `[](<url>?wrap=dropdown(hello-world))`
 
 [](.assets/api-note.md?wrap=quote)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 9 chars: 352 -->
+
 <blockquote>
 
 **_NOTE ON API USAGE:_** As you can see from the included examples, each _invocation_ of an API method looks like a less strict (more quirky) version of a typical javascript function invocation. 
@@ -333,10 +449,12 @@ Please see the [full explanation](#query-parameters-with-function-like-apis) to
 
 </blockquote>
 
-<!-- p▼ END -->
+<!-- p↓ END -->
 
 [](src/wrap.ts?region=extract(definition))
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 38 chars: 1384 -->
+
 ```ts
 const definitions = [
   /**
@@ -373,13 +491,123 @@ const definitions = [
 
 ]
 ```
-<!-- p▼ END -->
 
-<!-- p▼ END -->
-<!-- p▼ END -->
+<!-- p↓ END -->
+
+[](.assets/api.md?heading=-1)
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 104 chars: 4981 -->
+#### Query Parameters with Function-like APIs
+
+Some query parameters have more complex APIs, which are defined by a collection of typescript function singatures (limited to only `string`, `boolean`, and `number` arguments), like:
+
+```ts
+const definitions = [
+  "method(arg1: string, arg2: boolean, arg3?: number)",
+  "otherMethod(arg1: string, arg2?: boolean, arg3?: number)"
+]
+```
+
+These APIs are utilized when setting the value of the specific query parameter with a _function-like_ invocation syntax, such as:
+
+```md
+[](<url>?example=method(hello-world,true))
+```
+
+As you can see from the example above, we're relaxing some constraints on typical function invocations (like the need to wrap string arguments in quotes), while also imposing some additional constraints (like not using _any_ spaces) to ensure the links are valid markdown and the URLs are [safe](https://support.exactonline.com/community/s/knowledge-base?language=en_GB#All-All-DNO-Content-urlcharacters).
+
+The goal is to make it as painless as possible to author links that are valid markdown, valid URLs, and easy to read and write.
+
+Please note the following:
+
+- Methods that take no arguments can be invoked without parentheses (e.g. `[](<url>?example=method)`).
+- String arguments do not need to be wrapped in quotes (e.g. `[](<url>?example=method(some-string))`), and they **CANNOT** be wrapped in double quotes (see more below).
+- You cannot use spaces within a string argument or anywhere else in the query (as this would violate the markdown link syntax). For arguments that reasonably could include spaces, there should be an optional `space` argument that defaults to `-`, so that any usage of the space character will be converted to a space (e.g. `hello-world` becomes `hello world`).
+- Characters that are reserved or unsafe in URLs can be included by using the below remapping, where you'll write the corresponding key wrapped in the applicable `space` character (see the above bullet point, defaults to `-`). For example, if you want to use a `/`, you'd instead write `-slash-` (or with whatever you specify as your space character instead of `-`).
+
+[](src/utils.ts?region=extract(url))
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 31 chars: 498 -->
+
+```ts
+const urlCharacters = {
+  reserved: {
+    ["semi"]: ";",
+    ["slash"]: "/",
+    ["question"]: "?",
+    ["colon"]: ":",
+    ["at"]: "@",
+    ["equal"]: "=",
+    ["and"]: "&",
+  },
+  unsafe: {
+    ["quote"]: "\"",
+    ["angle"]: "<",
+    ["unangle"]: ">",
+    ["hash"]: "#",
+    ["percent"]: "%",
+    ["curly"]: "{",
+    ["uncurly"]: "}",
+    ["pipe"]: "|",
+    ["back"]: "\\",
+    ["carrot"]: "^",
+    ["tilde"]: "~",
+    ["square"]: "[",
+    ["unsquare"]: "]",
+    ["tick"]: "`",
+  }
+}
+```
+
+<!-- p↓ END -->
+
+- If a method takes a string argument, and you want to include a comma within that argument, you must wrap it in one or more single quotes (e.g.`hello,-world` should be specified as `'hello,-world'`). 
+- String arguments wrapped in a single set of single quotes will automatically have the quotes removed when the query is parsed (e.g. the argument included in `[](<url>?example=method('hello,world'))` will parse to `hello,world`).
+- If you want single quotes preserved in the parsed output, use two single quotes in a row (e.g. `[](<url>?example=method(''single-quoted''))`). 
+- You cannot use double quotes within a string argument (as they are not a [URL safe character](https://support.exactonline.com/community/s/knowledge-base#All-All-DNO-Content-urlcharacters)). To include a double-quote in the parsed output, use three single quotes in a row (e.g. `[](<url>?example=method('''double-quoted'''))`). Or use the remapping described above, like `[](<url>?example=method(-quote-double-quoted-quote-))`.
+- Optional arguments can be completely ommitted (for example if a `method` took 3 optional arguments, and you only wanted to provide the third, you could do the following: `[](<url>?example=method(,,your-third-argument))`).
+- Overall, text meant to be displayed will be _sanitized_ in the following manner (unless otherwise noted):
+
+[](src/utils.ts?region=extract(sanitize))
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 29 chars: 779 -->
+
+```ts
+type Replacement = [from: RegExp | string, to: string];
+
+const replacements: Record<string, Replacement[]> = {
+  static: [
+    [`'''`, `"`],
+    [`''`, `'`],
+    [/parkdown:\s+/g, ``],
+    [/p↓:\s+/g, ``],
+  ],
+  url: [
+    ...(Object.entries(urlCharacters.unsafe)),
+    ...(Object.entries(urlCharacters.reserved))
+  ]
+};
+
+const applyReplacement = (accumulator: string, [from, to]: Replacement) =>
+  accumulator.replaceAll(from, to);
+
+export const sanitize = (replacement: string, space: string = DEFAULT_SPACE) => {
+  const sanitized = replacements.static.reduce(applyReplacement, replacement)
+  return replacements.url
+    .map(([key, to]) => ([space + key + space, to] satisfies Replacement))
+    .reduce(applyReplacement, sanitized)
+    .replaceAll(space, " ");
+}
+```
+
+<!-- p↓ END -->
+<!-- p↓ END -->
+<!-- p↓ END -->
+<!-- p↓ END -->
 
 [](./.assets/depopulated.md)
-<!-- p▼ BEGIN -->
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 38 chars: 1473 -->
 ## Removing populated inclusions
 
 Sometimes you may want to remove populated inclusions from your markdown file, since they can make things more difficult to read during authoring. You can do this either using the [cli](#cli-removing-populated-inclusions) or via the `removePopulatedInclusions` [export](#depopulateMarkdownIncludes-export):
@@ -389,30 +617,33 @@ Sometimes you may want to remove populated inclusions from your markdown file, s
 The following commands are all equivalent:
 
 ```bash
-npx parkdown --file ./README.md --depopulate --no-inclusions
-npx parkdown -f README.md -d --ni # Notice the double-dash (--) on 'ni'
-npx parkdown -d --ni # defaults to processing the 'README.md' file of the current working directory
+npx @p-buddy/parkdown --file ./README.md --depopulate --no-inclusions
+npx @p-buddy/parkdown -f README.md -d --ni # Notice the double-dash (--) on 'ni'
+npx @p-buddy/parkdown -d --ni # defaults to processing the 'README.md' file of the current working directory
 ```
 
 The following commands will lead to the same result, but since `--no-inclusions` (`--ni`) is not specified, there will be some wasted work as inclusions will be processed and then removed.
 
 ```bash
-npx parkdown --file ./README.md --depopulate
-npx parkdown -f README.md -d
-npx parkdown -d # defaults to processing the 'README.md' file of the current working directory
+npx @p-buddy/parkdown --file ./README.md --depopulate
+npx @p-buddy/parkdown -f README.md -d
+npx @p-buddy/parkdown -d # defaults to processing the 'README.md' file of the current working directory
 ```
 
 ### `depopulateMarkdownIncludes` export
 
-[](.assets/code/depopulate.ts?region=replace(pkg,'''parkdown'''))
-<!-- p▼ BEGIN -->
+[](.assets/code/depopulate.ts?region=replace(pkg,'''@p-buddy_slash_parkdown''',_))
+<!-- p↓ BEGIN -->
+<!-- p↓ length lines: 10 chars: 176 -->
+
 ```ts
-import { depopulateMarkdownInclusions } from "parkdown";
+import { depopulateMarkdownInclusions } from "@p-buddy/parkdown";
 
 const file = "README.md";
 const writeFile = true;
 
 depopulateMarkdownInclusions(file, writeFile);
 ```
-<!-- p▼ END -->
-<!-- p▼ END -->
+
+<!-- p↓ END -->
+<!-- p↓ END -->