feat: add relative path support for transforming urls

docs/README.md

@@ -6,6 +6,7 @@ astro-rehype-relative-markdown-links
 
 ### Interfaces
 
+- [CollectionConfig](interfaces/CollectionConfig.md)
 - [Options](interfaces/Options.md)
 
 ### Functions
@@ -37,4 +38,4 @@ Rehype plugin for Astro to add support for transforming relative links in MD and
 
 #### Defined in
 
-[src/index.mjs:33](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/index.mjs#L33)
+[src/index.mjs:36](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/index.mjs#L36)

docs/interfaces/CollectionConfig.md

@@ -0,0 +1,64 @@
+[astro-rehype-relative-markdown-links](../README.md) / CollectionConfig
+
+# Interface: CollectionConfig
+
+## Hierarchy
+
+- `input`\<`CollectionConfigSchemaType`\>
+
+  ↳ **`CollectionConfig`**
+
+## Table of contents
+
+### Properties
+
+- [base](CollectionConfig.md#base)
+- [name](CollectionConfig.md#name)
+
+## Properties
+
+### base
+
+• `Optional` **base**: ``false`` \| ``"name"`` \| ``"collectionRelative"`` \| ``"pathRelative"``
+
+**`Name`**
+
+base
+
+**`Description`**
+
+Override the top-level [collectionBase](Options.md#collectionbase) option for this collection.
+
+#### Inherited from
+
+z.input.base
+
+#### Defined in
+
+[src/options.mjs:17](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L17)
+
+___
+
+### name
+
+• `Optional` **name**: `string`
+
+**`Name`**
+
+name
+
+**`Description`**
+
+Override the name of the collection from disk.
+
+Use this option when your collection page path does not correspond to the name of the collection on disk (ex. `src/content/docs/reference.md` resolves to a page path of /my-docs/reference).
+
+When not specified, the name of the collection from disk will be used where applicable.
+
+#### Inherited from
+
+z.input.name
+
+#### Defined in
+
+[src/options.mjs:28](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L28)

docs/interfaces/Options.md

@@ -13,8 +13,9 @@
 ### Properties
 
 - [basePath](Options.md#basepath)
-- [collectionPathMode](Options.md#collectionpathmode)
-- [contentPath](Options.md#contentpath)
+- [collectionBase](Options.md#collectionbase)
+- [collections](Options.md#collections)
+- [srcDir](Options.md#srcdir)
 - [trailingSlash](Options.md#trailingslash)
 
 ## Properties
@@ -35,11 +36,11 @@ https://docs.astro.build/en/reference/configuration-reference/#base
 
 The base path to deploy to. Astro will use this path as the root for your pages and assets both in development and in production build.
 
-In the example below, `astro dev` will start your server at `/docs`.
+In the example below, `astro dev` will start your server at `/my-site`.
 
 ```js
 {
-  base: '/docs'
+  base: '/my-site'
 }
 ```
 
@@ -49,74 +50,159 @@ z.input.basePath
 
 #### Defined in
 
-[src/options.mjs:50](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L50)
+[src/options.mjs:131](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L131)
 
 ___
 
-### collectionPathMode
+### collectionBase
 
-• `Optional` **collectionPathMode**: ``"root"`` \| ``"subdirectory"``
+• `Optional` **collectionBase**: ``false`` \| ``"name"`` \| ``"collectionRelative"`` \| ``"pathRelative"``
 
 **`Name`**
 
-collectionPathMode
+collectionBase
 
 **`Default`**
 
-`subdirectory`
+`"name"`
 
 **`Description`**
 
-Where you store your collections:
-  - `subdirectory` - Subdirectories under `contentPath` (ex: `src/content/docs/index.md` where `docs` is the content collection subdirectory of the contentPath `src/content`)
-  - `root` - Directly inside `contentPath` (ex: `src/content/docs/index.md` where `src/content/docs` is the `contentPath`)
+Set how the URL path to the referenced markdown file should be derived:
+  - `"name"` - An absolute path prefixed with the optional [basePath](Options.md#basepath) followed by the collection name
+  - `false` - An absolute path prefixed with the optional [basePath](Options.md#basepath)
+  - `"collectionRelative"` - A relative path from the collection directory
+  - `"pathRelative"` - A relative path from the current page path
+
+For example, given a file `./guides/section/my-guide.md` referenced from `./guides/section/my-other-guide.md` with
+the link `[My Guide](./my-guide.md)` in the content collection `docs`, the transformed url would be:
+  - `"name"`: `[/basePath]/docs/guides/section/my-guide`
+  - `false`: `[/basePath]/guides/section/my-guide`
+  - `"collectionRelative"`: `../../guides/section/my-guide`
+  - `"pathRelative"`: `my-guide`
+
+Use `false`, `"collectionRelative"`, or `"pathRelative"` when you are treating your content collection as if it were located in the site
+root (ex: `src/content/docs/test.md` resolves to the page path `/test` instead of the typical `/docs/test`).
+
+Use `"collectionRelative"` or `"pathRelative"` when you are serving your content collection pages from multiple page path roots that use a
+common content collection (ex: `/my-blog/test` and `/your-blog/test` both point to the file `./src/content/posts/test.md`
+in the content collection `posts`).
+
+Important Notes:
+- This is a top-level option and will apply to all content collections.  If you have multiple content collections
+and want the behavior to be different on a per content collection basis, add the collection(s) to the [collections](Options.md#collections)
+option and provide a value for collection specific [base](CollectionConfig.md) option.
+- When using either `"collectionRelative"` or `"pathRelative"`, due to the nature of relative links, you MUST ensure
+that any directory paths in your site (e.g., urls to `index` pages), contain a trailing slash.  For example, given
+`./src/content/docs/index.md`, the url should be `/docs/` and not `/docs` as any link generated on that page by the plugin
+for a page inside of `./src/content/docs` directory will not navigate correctly since, in relative terms, `/docs` is
+different than `/docs/`. Along this line, it is highly encouraged to apply `trailingSlash="always"` to your Astro site and
+this plugin to help avoid relative pathing issues.
 
-Use the `root` configuration option when you are explicitly setting the [contentPath](Options.md#contentpath) property to something other than `src/content` and you want the directory you specify
-for [contentPath](Options.md#contentpath) to be treated a single content collection as if it where located in the site root.  In most scenarios, you should set this value to `subdirectory` or not
-set this value and the default of `subdirectory` will be used.
+**`Example`**
+
+```js
+{
+  // Do not apply a collection name segment to the generated absolute URL path
+  collectionBase: false
+}
+```
+
+**`See`**
+
+[collections](Options.md#collections)
+
+#### Inherited from
+
+z.input.collectionBase
+
+#### Defined in
+
+[src/options.mjs:94](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L94)
+
+___
+
+### collections
+
+• `Optional` **collections**: `Record`\<`string`, \{ `base?`: ``false`` \| ``"name"`` \| ``"collectionRelative"`` \| ``"pathRelative"`` ; `name?`: `string`  }\>
+
+**`Name`**
+
+collections
+
+**`Default`**
+
+`{}`
+
+**`Description`**
+
+Specify a mapping of collections where the `key` is the name of a collection on disk and the value is a [CollectionConfig](CollectionConfig.md)
+which will override any top-level configuration where applicable.
 
 **`Example`**
 
 ```js
 {
-  // Use 'subdirectory' mode
-  collectionPathMode: 'subdirectory'
+  // Do not apply a collection name segment to the generated absolute URL path for the collection `docs`
+  collections: {
+    docs: {
+      base: false
+    }
+  }
 }
 ```
 
+**`See`**
+
+[CollectionConfig](CollectionConfig.md)
+
 #### Inherited from
 
-z.input.collectionPathMode
+z.input.collections
 
 #### Defined in
 
-[src/options.mjs:33](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L33)
+[src/options.mjs:116](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L116)
 
 ___
 
-### contentPath
+### srcDir
 
-• `Optional` **contentPath**: `string`
+• `Optional` **srcDir**: `string`
 
 **`Name`**
 
-contentPath
+srcDir
+
+**`Reference`**
+
+https://docs.astro.build/en/reference/configuration-reference/#srcdir
 
 **`Default`**
 
-`src/content`
+`./src`
 
 **`Description`**
 
-This defines where the content (i.e. md, mdx, etc. files) is stored. This should be a path relative to the root directory
+Set the directory that Astro will read your site from.
+
+The value can be either an absolute file system path or a path relative to the project root.
+
+**`Example`**
+
+```js
+{
+  srcDir: './www'
+}
+```
 
 #### Inherited from
 
-z.input.contentPath
+z.input.srcDir
 
 #### Defined in
 
-[src/options.mjs:12](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L12)
+[src/options.mjs:49](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L49)
 
 ___
 
@@ -130,16 +216,16 @@ trailingSlash
 
 **`Default`**
 
-`ignore`
+`"ignore"`
 
 **`Description`**
 
 Allows you to control the behavior for how trailing slashes should be handled on transformed urls:
-  - `'always'` - Ensure urls always end with a trailing slash regardless of input
-  - `'never'` - Ensure urls never end with a trailing slash regardless of input
-  - `'ignore'` - Do not modify the url, trailing slash behavior will be determined by the file url itself or a custom slug if present.
+  - `"always"` - Ensure urls always end with a trailing slash regardless of input
+  - `"never"` - Ensure urls never end with a trailing slash regardless of input
+  - `"ignore"` - Do not modify the url, trailing slash behavior will be determined by the file url itself or a custom slug if present.
 
-When set to `'ignore'` (the default), the following will occur:
+When set to `"ignore"` (the default), the following will occur:
   - If there is not a custom slug on the target file, the markdown link itself will determine if there is a trailing slash.
       - `[Example](./my-doc.md/)` will result in a trailing slash
       - `[Example](./my-doc.md)` will not result in a trailing slash
@@ -152,7 +238,7 @@ When set to `'ignore'` (the default), the following will occur:
 ```js
 {
   // Use `always` mode
-  trailingSlash: `always`
+  trailingSlash: "always"
 }
 ```
 
@@ -166,4 +252,4 @@ z.input.trailingSlash
 
 #### Defined in
 
-[src/options.mjs:77](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L77)
+[src/options.mjs:158](https://github.com/vernak2539/astro-rehype-relative-markdown-links/blob/main/src/options.mjs#L158)

package.json

@@ -35,7 +35,7 @@
     "pre-release": "yarn run changelog && yarn run prettier && yarn run generate-docs",
     "generate-docs": "typedoc --readme none --gitRevision main --plugin typedoc-plugin-markdown src",
     "prettier": "prettier ./src/** -w",
-    "test": "node --loader=esmock --test",
+    "test": "ARRML_MATTER_CACHE_DISABLE=true node --loader=esmock --test",
     "type-check": "tsc --noEmit --emitDeclarationOnly false"
   },
   "dependencies": {

src/fixtures/content/dir-test-custom-slug/with-trailing-slash.md

@@ -0,0 +1,3 @@
+---
+slug: slug-with-trailing-slash/
+---

src/fixtures/content/dir-test-custom-slug/without-trailing-slash.md

@@ -0,0 +1,3 @@
+---
+slug: slug-without-trailing-slash
+---

src/fixtures/content/docs/_test.md

@@ -0,0 +1,3 @@
+## Test
+
+Test [link](./other-markdown.md)

src/fixtures/content/docs/dir-test/index.md

@@ -0,0 +1 @@
+## Test

src/fixtures/content/docs/test.md

@@ -0,0 +1,3 @@
+## Test
+
+Test [link](./other-markdown.md)

src/fixtures/content/relative-tests/dir-child-1/dir-grandchild-1/test-custom-slug-is-collection-root.md

@@ -0,0 +1,5 @@
+---
+slug: test.custom.slug.is.collection.root
+---
+
+Test

src/fixtures/content/relative-tests/dir-child-1/dir-grandchild-1/test-custom-slug.md

@@ -0,0 +1,5 @@
+---
+slug: dir-child-1/dir-grandchild-1/test.custom.slug
+---
+
+Test

src/fixtures/content/relative-tests/dir-child-1/dir-grandchild-1/test.md

@@ -0,0 +1,3 @@
+## Test
+
+Test [link](./other-markdown.md)

src/fixtures/content/relative-tests/dir-child-1/dir-grandchild-1/test2.md

@@ -0,0 +1,3 @@
+## Test
+
+Test [link](./other-markdown.md)

src/fixtures/content/relative-tests/dir-child-1/dir-grandchild-2/test.md

@@ -0,0 +1,3 @@
+## Test
+
+Test [link](./other-markdown.md)

src/fixtures/content/relative-tests/dir-child-1/test-custom-slug-with-forward-slash.md

@@ -0,0 +1,5 @@
+---
+slug: dir-child-1/test.custom.slug.with-forward.slash/
+---
+
+Test

src/fixtures/content/relative-tests/dir-child-1/test-me-out.md

@@ -0,0 +1,3 @@
+## Test
+
+Test [link](./other-markdown.md)

src/fixtures/content/relative-tests/dir-child-1/test.md

@@ -0,0 +1,3 @@
+## Test
+
+Test [link](./other-markdown.md)

src/fixtures/content/relative-tests/dir-child-2/test.md

@@ -0,0 +1,3 @@
+## Test
+
+Test [link](./other-markdown.md)

src/fixtures/content/relative-tests/dir-child-3.md/test-me-out.md

@@ -0,0 +1,3 @@
+## Test
+
+Test [link](./other-markdown.md)