eleventy-plugin-markdown-page-links 0.0.5

package/changelog.md

@@ -0,0 +1,10 @@
+# Changelog
+
+v0.0.1 - January 11, 2026
+
+Initial release.
+
+Missing: 
+
++ Support for External Links only configuration option.
++ Link de-duplication; omitting duplicate links from shortcode output.

package/eleventy-plugin-markdown-page-links.js

@@ -0,0 +1,109 @@
+var ListType;
+(function (ListType) {
+    ListType[ListType["Simple"] = 0] = "Simple";
+    ListType[ListType["Ordered"] = 1] = "Ordered";
+    ListType[ListType["Unordered"] = 2] = "Unordered";
+})(ListType || (ListType = {}));
+const defaultConfig = {
+    'debugMode': false,
+    'collapsible': false,
+    'externalLinksOnly': false,
+    'listClass': '',
+    'listType': 0,
+    'minimumLinks': 0,
+    'openInNewTab': true,
+    'sectionTitle': 'Links',
+};
+const PLUGIN_NAME = 'Eleventy-Plugin-Markdown-Page-Links';
+const regex = /\!*\[([^\]]+)\]\(([^)]+)\)/g;
+function buildLinkList(links, delimiter, newWindow, debugMode) {
+    if (debugMode)
+        console.log(`Building link list with delimiter: ${delimiter}, newWindow: ${newWindow}`);
+    var resultStr = '';
+    links.forEach((link) => {
+        if (debugMode)
+            console.dir(link);
+        resultStr += `<${delimiter}><a href="${link.url}"${newWindow ? ' target="_blank" rel="noopener noreferrer"' : ''}>${link.title}</a></${delimiter}>\n`;
+    });
+    return resultStr;
+}
+export default function (eleventyConfig, options = {}) {
+    options = { ...defaultConfig, ...options };
+    if (options.debugMode) {
+        console.log('Options');
+        console.table(options);
+    }
+    eleventyConfig.addShortcode("pageLinks", function (listType, minimumLinks, openInNewTab, externalLinksOnly, listClass, collapsible, sectionTitle, debugMode) {
+        var content;
+        var link;
+        var links = [];
+        var match;
+        var resultStr;
+        listType = listType ?? options.listType;
+        minimumLinks = minimumLinks ?? options.minimumLinks;
+        openInNewTab = openInNewTab ?? options.openInNewTab;
+        externalLinksOnly = externalLinksOnly ?? options.externalLinksOnly;
+        listClass = listClass ?? options.listClass;
+        collapsible = collapsible ?? options.collapsible;
+        sectionTitle = sectionTitle ?? options.sectionTitle;
+        debugMode = debugMode ?? options.debugMode;
+        if (listType < 0 || listType > 2) {
+            return `${PLUGIN_NAME} Error: Invalid list type specified (${listType}).`;
+        }
+        content = this.page.rawInput;
+        while ((match = regex.exec(content)) !== null) {
+            link = {
+                title: match[1].trim(),
+                url: match[2].trim()
+            };
+            if (externalLinksOnly && (link.url.startsWith('/') || link.url.startsWith('#') || link.url.startsWith(this.page.url))) {
+                if (debugMode)
+                    console.log(`${PLUGIN_NAME} Skipping internal link: ${link.url}`);
+                continue;
+            }
+            if (links.findIndex(l => l.url === link.url) !== -1) {
+                if (debugMode)
+                    console.log(`${PLUGIN_NAME} Duplicate link found, skipping: ${link.url}`);
+                continue;
+            }
+            links.push(link);
+        }
+        if (debugMode && links.length > 0)
+            console.dir(links);
+        resultStr = '';
+        if (links.length >= minimumLinks) {
+            if (collapsible) {
+                resultStr += `<details>\n<summary>${sectionTitle}</summary>\n`;
+            }
+            switch (listType) {
+                case ListType.Ordered:
+                    if (debugMode)
+                        console.log(`${PLUGIN_NAME} Building ordered list`);
+                    resultStr += `<ol${listClass ? ` class="${listClass}"` : ''}>\n`;
+                    resultStr += buildLinkList(links, 'li', openInNewTab, debugMode);
+                    resultStr += '</ol>\n';
+                    break;
+                case ListType.Unordered:
+                    if (debugMode)
+                        console.log(`${PLUGIN_NAME} Building unordered list`);
+                    resultStr += `<ul${listClass ? ` class="${listClass}"` : ''}>\n`;
+                    resultStr += buildLinkList(links, 'li', openInNewTab, debugMode);
+                    resultStr += '</ul>\n';
+                    break;
+                default:
+                    if (debugMode)
+                        console.log(`${PLUGIN_NAME} Building div link list`);
+                    resultStr += `<div${listClass ? ` class="${listClass}"` : ''}>\n`;
+                    resultStr += buildLinkList(links, 'p', openInNewTab, debugMode);
+                    resultStr += '</div>\n';
+                    break;
+            }
+            if (collapsible) {
+                resultStr += `</details>\n`;
+            }
+        }
+        if (debugMode)
+            console.dir(resultStr);
+        return resultStr;
+    });
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "eleventy-plugin-markdown-page-links",
+  "version": "0.0.5",
+  "description": "An Eleventy plugin to generate a list of links for a particular page.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnwargo/eleventy-plugin-markdown-page-links.git"
+  },
+  "keywords": [
+    "eleventy",
+    "11ty",
+    "plugin"
+  ],
+  "author": "John M. Wargo",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc && eleventy --quiet",
+    "start": "tsc && eleventy --serve --quiet",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "bugs": {
+    "url": "https://github.com/johnwargo/eleventy-plugin-markdown-page-links/issues"
+  },
+  "homepage": "https://github.com/johnwargo/eleventy-plugin-markdown-page-links#readme",
+  "dependencies": {
+    "@11ty/eleventy": "^3.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.4.2",
+    "typescript": "^5.3.3"
+  }
+}

package/readme.md

@@ -0,0 +1,155 @@
+# Eleventy Plugin Markdown Post Links
+
+## Tasks
+
+- [x] Omit duplicate links in output
+- [x] Implement external-only flag
+- [ ] Update readme
+- [ ] Publish package
+- [ ] Write blog post
+- [ ] Share on social media
+
+---
+
+An [Eleventy](https://www.11ty.dev/) plugin that adds a shortcode to Eleventy sites that generates a list of links from a markdown page's content. The plugin supports a variety of configuration options (configurable as global settings and/or individual settings per shortcode use). 
+
+**Notes:** 
+
++ Due to some technical limitations in Eleventy, shortcodes don't have access to rendered HTML content for a page. To implement this successfully, the plugin looks for links in pre-rendered content.  Since I primarily use markdown files for site content, I built the plugin to look for markdown anchor links.
++ I only tested this plugin using Liquid template code in Markdown files. This approach also makes it easy for the plugin to ignore site navigation on posts, etc.
+
+## Installation
+
+To install the plugin, in a terminal window pointing to an Eleventy project, execute the following command:
+
+```shell
+npm install eleventy-plugin-markdown-page-links
+```
+
+In your project's eleventy.config.js file, import the package (at the top of the file) using:
+
+``` ts
+const pageLinks = require('eleventy-plugin-post-stats');
+```
+
+And in the same file's module.exports section, along with all the other plugin statements you site uses, add the following `addPlugin` method call:
+
+``` ts
+module.exports = eleventyConfig => {
+
+  // add only the following line
+  eleventyConfig.addPlugin(pageLinks);
+
+}
+```
+
+The complete file should look something like the following (but with your site's other stuff in it as well):
+
+``` ts
+const pageLinks = require('./eleventy-plugin-markdown-page-links.js');
+
+module.exports = eleventyConfig => {
+
+  eleventyConfig.addPlugin(pageLinks);
+  
+};
+```
+
+With that in place, your site now has a shortcode called `pageLinks` the site can use to generate a list of links from the current page.
+
+## Background
+
+Posts in my [personal blog](https://johnwargo.com) often reference a lot of external links, and some of the longer posts have 10 or more links. I realized I could make it easier for readers if I listed all links in a group somewhere on the page. This isn't a critical feature for the site, but something I thought visitors might find useful.
+
+Add the shortcode to a page's template to have the links appear on every page, or place the shortcode at the top or bottom of a long article to generate links for just that page. The plugin also supports a configuration option, `minimumLinks`, that instructs the shortcode to generate links only if there are a specific number of links on the page.
+
+The plugin supports the following options:
+
+**List Types:**
+
++ **Simple list** - Generates a simple list of page links with each as a separate paragraph in the page.
++ **Ordered list** - Generates a list of page links as an ordered list using the `<ol>` and `</ol>` tags
++ **Unordered list** - Generates a list of page links as an ordered list using the `<ul>` and `</ul>` tags
+
+**List Options:**
+
++ **Collapsible list** - Link list and renders it in a collapsed section on the page using the `<details>` and `<summary>` tags.
++ **New Tab** - Links open in a new tab using `target="_blank"`.
++ **Styled List** - Allows you to apply a CSS class to the list container on the page.
++ **Minimum Links** - Only generate the link list when there's at least a specified number of links on the page.
+
+This repo includes a [sample app](https://mdpagelinks.netlify.app/) (hosted for free on [Netlify](https://www.netlify.com/)) that demonstrates all of these options; check it out to learn more.
+
+## Operation
+
+Add the shortcode `pageLinks` to a page or page template to generate a list of the page's links in that location. In this example, no list type is specified, so the plugin uses the default option of the simple list.
+
+``` markdown
+Links on this page:
+
+{% pageLinks %}
+
+Bacon ipsum dolor amet picanha filet mignon beef ribs swine tongue kielbasa...
+```
+
+This generates the following content on the page:
+
+![Sample links list](/images/image-01.png)
+
+Specify a different list type (such as unordered list: 2) by specifying the list type as a parameter to the shortcode:
+
+``` markdown
+Links on this page:
+
+{% pageLinks 2 %}
+
+Bacon ipsum dolor amet picanha filet mignon beef ribs swine tongue kielbasa...
+```
+
+This generates the unordered list shown below:
+
+![Sample links list](/images/image-02.png)
+
+### Configuration Options
+
+The shortcode supports the following options:
+
+| Name            | Option              | Description | 
+| --------------- |-------------------- | ----------- |
+| Collapsible     | `collapsible`       | Generates a collapsible section containing the list of links. When you enable this option, you must also specify a value for `sectionTitle`. [Example](https://mdpagelinks.netlify.app/posts/collapsible/). Default: `false` |
+| External Links  | `externalLinksOnly` | Omits local links from the generated output. [Example](https://mdpagelinks.netlify.app/posts/external-only/). Default: `false` |
+| List Class      | `listClass`         | Defines the name of the CSS Class you want added to the list container. [Example](https://mdpagelinks.netlify.app/posts/styled/). Default: "" |
+| List Type       | `listType`          | Specifies the type of list generated; supported options are `0` {Simple), `1` (Ordered), `2` (Unordered). Examples: [Simple](https://mdpagelinks.netlify.app/posts/simple/), [Ordered](https://mdpagelinks.netlify.app/posts/ordered/), [Unordered](https://mdpagelinks.netlify.app/posts/unordered/). Default: 0  |
+| Minimum Links   | `minimumLinks`      | Specifies the minimum number of links on the page required before the shortcode generates the link list. If your site generally doesn't have a lot of links per page, you can use this it to only generates links for articles with a greater number of links. [Example](https://mdpagelinks.netlify.app/posts/minimum/). Default: 0 |
+| Open in New Tab | `openInNewTab`      | By default, the shortcut generates links that open in a new browser window/tab. With this option set to `false`, when a user clicks one of the links, the linked content will replace the current page in the browser. [Example](https://mdpagelinks.netlify.app/posts/same-window/). Default: `true` |
+| Section Title   | `sectionTitle`      | With `collapsible` enabled, this configuration option defines the text the plugin generates as the Summary (`<summary></summary>`) of the collapsible section. If you don't provide a value for this configuration option, the shortcut uses the default value. [Example](https://mdpagelinks.netlify.app/posts/collapsible/). Default: "Links" |
+
+You can set any of these settings as global options for the shortcut when you load the plugin in your project's `eleventy.config.js` file. Simply add any supported configuration variable in an object to the `addPlugin` method invocation. This following example configures the plugin to open all links in the same browser tab/window (disabling the default behavior).
+
+``` ts
+eleventyConfig.addPlugin(pageLinks, { openInNewTab: false });
+```
+
+Specify any of the configuration options as parameters to the shortcode; as positional parameters, the order is the following:
+
+1. `listType?` ListType
+2. `minimumLinks`: number
+3. `openInNewTab`: boolean
+4. `externalLinksOnly`: boolean
+5. `listClass`: string
+6. `collapsible`: boolean
+7. `sectionTitle`: string
+
+The `ListType` enum looks like this:
+
+``` ts
+enum ListType {
+  Simple,      // 0
+  Ordered,     // 1
+  Unordered,   // 2
+}
+```
+
+**Note:** Some time after launch, but perhaps before launch, I'll configure the shortCode code to use named parameters.
+
+Refer to the [sample app](https://mdpagelinks.netlify.app/) for examples for each of these options.