Add plugin to set attributes on links (#108)

CHANGELOG.md

@@ -20,6 +20,8 @@ Any non-code changes should be prefixed with `(docs)`.
 See `PUBLISH.md` for instructions on how to publish a new version.
 -->
 
+- (minor) Add link attributes plugin
+
 
 ## v1.12.6 - b59f604
 

README.md

@@ -1133,6 +1133,24 @@ Set this property to `false` to disable this plugin.
 - `sizeUnits` (`string[]`, optional, defaults to `['', 'px', '%']`): Image size units to allow.
 </details>
 
+### link_attributes
+
+<details>
+<summary>Apply custom attributes to all links in the Markdown content.</summary>
+
+If an object is provided, the provided attributes are merged with the existing attributes.
+
+If a function is provided, the existing attributes are passed to it,
+ and the existing attributes are replaced (not merged) with the return value.
+
+**Options:**
+
+Pass options for this plugin as the `link_attributes` property of the `do-markdownit` plugin options.
+This plugin is disabled by default, pass an object to enable it.
+
+- `attributes` (`Object<string, string>|function(Object<string, string>): Object<string, string>`): Object or function to generate attributes for links.
+</details>
+
 ### prismjs
 
 <details>

index.js

@@ -57,7 +57,8 @@ const safeObject = require('./util/safe_object');
  * @property {false|import('./modifiers/heading_id').HeadingIdOptions} [heading_id] Disable Ids on headings, or set options for the feature.
  * @property {false|import('./modifiers/image_settings').ImageSettingsOptions} [image_settings] Disable image settings syntax, or set options for the feature.
  * @property {false|import('./modifiers/prismjs').PrismJsOptions} [prismjs] Disable Prism highlighting, or set options for the feature.
- * @property {false|import('./rules/limit_tokens').LimitTokensOptions} [limit_tokens] Disable token filtering, or set options for the feature.
+ * @property {import('./modifiers/link_attributes').LinkAttributesOptions} [link_attributes] Enable custom link attributes by setting options for the feature.
+ * @property {import('./rules/limit_tokens').LimitTokensOptions} [limit_tokens] Enable token filtering by setting options for the feature.
  */
 
 /**
@@ -203,11 +204,17 @@ module.exports = (md, options) => {
         md.use(require('./modifiers/image_settings'), safeObject(optsObj.image_settings));
     }
 
+    if (optsObj.link_attributes) {
+        md.use(require('./modifiers/link_attributes'), safeObject(optsObj.link_attributes));
+    }
+
     if (optsObj.prismjs !== false) {
         md.use(require('./modifiers/prismjs'), safeObject(optsObj.prismjs));
     }
 
-    if (optsObj.limit_tokens && optsObj.limit_tokens !== false) {
+    // Limiting the token streams should be the last step
+
+    if (optsObj.limit_tokens) {
         md.use(require('./rules/limit_tokens'), safeObject(optsObj.limit_tokens));
     }
 };

modifiers/link_attributes.js

@@ -0,0 +1,71 @@
+/*
+Copyright 2024 DigitalOcean
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+'use strict';
+
+/**
+ * @module modifiers/link_attributes
+ */
+
+const safeObject = require('../util/safe_object');
+
+/**
+ * @typedef {Object} LinkAttributesOptions
+ * @property {Object<string, string>|function(Object<string, string>): Object<string, string>} attributes Object or function to generate attributes for links.
+ */
+
+/**
+ * Apply custom attributes to all links in the Markdown content.
+ *
+ * If an object is provided, the provided attributes are merged with the existing attributes.
+ *
+ * If a function is provided, the existing attributes are passed to it,
+ *  and the existing attributes are replaced (not merged) with the return value.
+ *
+ * @type {import('markdown-it').PluginWithOptions<LinkAttributesOptions>}
+ */
+module.exports = (md, options) => {
+    // Get the correct options
+    const optsObj = safeObject(options);
+
+    /**
+     * Wrap the link render function to inject custom attributes.
+     *
+     * @param {import('markdown-it/lib/renderer').RenderRule} [original] Original render function. Defaults to `renderToken`.
+     * @returns {import('markdown-it/lib/renderer').RenderRule}
+     * @private
+     */
+    const render = original => (tokens, idx, opts, env, self) => {
+        // Get the token
+        const token = tokens[idx];
+
+        // Handle a function for transforming attributes
+        // Otherwise, merge the attributes
+        if (typeof optsObj.attributes === 'function') {
+            const currentAttrs = Object.fromEntries(token.attrs);
+            token.attrs = Object.entries(optsObj.attributes(currentAttrs));
+        } else {
+            token.attrs = Object.entries({ ...Object.fromEntries(token.attrs), ...optsObj.attributes });
+        }
+
+        // Render as normal
+        return typeof original === 'function'
+            ? original(tokens, idx, opts, env, self)
+            : self.renderToken(tokens, idx, opts, env);
+    };
+
+    md.renderer.rules.link_open = render(md.renderer.rules.link_open);
+};

modifiers/link_attributes.test.js

@@ -0,0 +1,39 @@
+/*
+Copyright 2024 DigitalOcean
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+'use strict';
+
+const md = require('markdown-it')().use(require('./link_attributes'));
+
+it('does not alter links by default', () => {
+    expect(md.render('[hello](/world "test")')).toBe(`<p><a href="/world" title="test">hello</a></p>
+`);
+});
+
+const mdObject = require('markdown-it')({ }).use(require('./link_attributes'), { attributes: { target: '_blank', title: 'other' } });
+
+it('handles an object of attributes', () => {
+    expect(mdObject.render('[hello](/world "test")')).toBe(`<p><a href="/world" title="other" target="_blank">hello</a></p>
+`);
+});
+
+// eslint-disable-next-line jsdoc/require-jsdoc
+const mdFunction = require('markdown-it')({ }).use(require('./link_attributes'), { attributes: attrs => ({ ...attrs, target: '_blank', title: 'other' }) });
+
+it('handles a function returning attributes', () => {
+    expect(mdFunction.render('[hello](/world "test")')).toBe(`<p><a href="/world" title="other" target="_blank">hello</a></p>
+`);
+});