diplodoc-platform · d3m1d0v · Nov 27, 2024 · Nov 18, 2024 · Nov 18, 2024 · Nov 18, 2024
diff --git a/README.md b/README.md
@@ -63,6 +63,13 @@ Options:
   Where target directore is `<transformer output option>/<plugin runtime option>`<br>
   Default: `true`<br>
 
+- `extraAttrs` – array of additional attributes in format `[name, value]`, that will be added to file links\
+  Default: `undefined`
+
+- `directiveSyntax` – enables new [directive syntax](#directive-syntax). \
+  Available values: `'disabled' | 'enabled' | 'only'`\
+  Default: `'disabled'`
+
 ## File markup
 
 ```md
@@ -75,23 +82,43 @@ Options:
 
 ### Supported attributes:
 
-| Name             | Required | Description                                                                                                                                       |
-| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src`            | yes      | URL of the file. Will be mapped to [`href` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href)                      |
-| `name`           | yes      | Name of the file. Will be mapped to [`download` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-download)             |
-| `lang`           | -        | Language of the file content. Will be mapped to [`hreflang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-hreflang) |
-| `referrerpolicy` | -        | [`referrerpolicy` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-referrerpolicy)                                     |
-| `rel`            | -        | [`rel` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-rel)                                                           |
-| `target`         | -        | [`target` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target)                                                     |
-| `type`           | -        | [`type` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-type)                                                         |
+| Name             | Required | Description                                                                                                                                  |
+| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`            | yes      | URL of the file. Will be mapped to [`href` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href)                      |
+| `name`           | yes      | Name of the file. Will be mapped to [`download` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download)             |
+| `lang`           | -        | Language of the file content. Will be mapped to [`hreflang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#hreflang) |
+| `referrerpolicy` | -        | [`referrerpolicy` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#referrerpolicy)                                     |
+| `rel`            | -        | [`rel` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#rel)                                                           |
+| `target`         | -        | [`target` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target)                                                     |
+| `type`           | -        | [`type` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#type)                                                         |
 
 > _Note: other attributes will be ignored_
 
-### Plugin options
+## Directive syntax
+
+Also you can use inline directive syntax for file links. For more information see here: [diplodoc-platform/directive](https://github.com/diplodoc-platform/directive/?tab=readme-ov-file#directive-syntax).
+
+To enable directive syntax pass `directiveSyntax: 'enabled'` to options. Or you can disabled old syntax and use only directive syntax: `directiveSyntax: 'only'`.
+
+```md
+:file[<file-name>](file-url)
+
+<!-- Example: -->
 
-| Name             | Type                 | Description                                      |
-| ---------------- | -------------------- | ------------------------------------------------ |
-| `fileExtraAttrs` | `[string, string][]` | Adds additional attributes to rendered hyperlink |
+:file[readme.md](path/to/readme/md){type=text/plain}
+```
+
+### Supported attributes:
+
+| Name             | Description                                                                                                     |
+| ---------------- | --------------------------------------------------------------------------------------------------------------- |
+| `hreflang`       | [anchor `hreflang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#hreflang)             |
+| `referrerpolicy` | [anchor `referrerpolicy` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#referrerpolicy) |
+| `rel`            | [anchor `rel` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#rel)                       |
+| `target`         | [anchor `target` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target)                 |
+| `type`           | [anchor `type` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#type)                     |
+
+> _Note: other attributes will be ignored_
 
 ## CSS public variables
 

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -51,6 +51,9 @@
     "npm-run-all": "^4.1.5",
     "typescript": "^5.6.3"
   },
+  "dependencies": {
+    "@diplodoc/directive": "^0.3.0"
+  },
   "peerDependencies": {
     "markdown-it": "^13.0.0"
   }

diff --git a/src/plugin/directive.ts b/src/plugin/directive.ts
@@ -0,0 +1,59 @@
+import type {FileOptions} from './plugin';
+
+import {directiveParser, registerInlineDirective} from '@diplodoc/directive';
+
+import {fileRenderer} from './renderer';
+import {ENV_FLAG_NAME, FILE_TOKEN, FileClassName, LinkHtmlAttr} from './const';
+
+const ALLOWED_ATTRS: readonly string[] = [
+    LinkHtmlAttr.ReferrerPolicy,
+    LinkHtmlAttr.Rel,
+    LinkHtmlAttr.Target,
+    LinkHtmlAttr.Type,
+    LinkHtmlAttr.HrefLang,
+];
+
+export const fileDirective: markdownit.PluginWithOptions<FileOptions> = (md, opts = {}) => {
+    const {fileExtraAttrs} = opts;
+
+    fileRenderer(md);
+
+    md.use(directiveParser());
+
+    registerInlineDirective(md, 'file', (state, params) => {
+        if (!params.content || !params.dests) {
+            return false;
+        }
+
+        const filename = params.content.raw;
+        const filelink = params.dests.link || '';
+
+        const token = state.push(FILE_TOKEN, '', 0);
+        token.block = false;
+        token.markup = ':file';
+        token.content = params.content.raw;
+
+        token.attrSet('class', FileClassName.Link);
+        token.attrSet(LinkHtmlAttr.Href, filelink);
+        token.attrSet(LinkHtmlAttr.Download, filename);
+
+        if (params.attrs) {
+            for (const attrName of ALLOWED_ATTRS) {
+                if (params.attrs[attrName]) {
+                    token.attrSet(attrName, params.attrs[attrName]);
+                }
+            }
+        }
+
+        if (Array.isArray(fileExtraAttrs)) {
+            for (const [name, value] of fileExtraAttrs) {
+                token.attrSet(name, value);
+            }
+        }
+
+        state.env ??= {};
+        state.env[ENV_FLAG_NAME] = true;
+
+        return true;
+    });
+};
diff --git a/src/plugin/plugin.ts b/src/plugin/plugin.ts
@@ -1,5 +1,3 @@
-import type MarkdownIt from 'markdown-it';
-
 import {
     ENV_FLAG_NAME,
     FILE_TOKEN,
@@ -12,12 +10,15 @@ import {
     REQUIRED_ATTRS,
     RULE_NAME,
 } from './const';
+import {fileRenderer} from './renderer';
 
 export type FileOptions = {
     fileExtraAttrs?: [string, string][];
 };
 
-export const filePlugin: MarkdownIt.PluginWithOptions<FileOptions> = (md, opts) => {
+export const filePlugin: markdownit.PluginWithOptions<FileOptions> = (md, opts) => {
+    fileRenderer(md);
+
     md.inline.ruler.push(RULE_NAME, (state, silent) => {
         if (state.src.substring(state.pos, state.pos + PREFIX_LENGTH) !== PREFIX) {
             return false;
@@ -82,10 +83,4 @@ export const filePlugin: MarkdownIt.PluginWithOptions<FileOptions> = (md, opts)
 
         return true;
     });
-
-    md.renderer.rules[FILE_TOKEN] = (tokens, idx, _opts, _env, self) => {
-        const token = tokens[idx];
-        const iconHtml = `<span class="${md.utils.escapeHtml(FileClassName.Icon)}"></span>`;
-        return `<a${self.renderAttrs(token)}>${iconHtml}${md.utils.escapeHtml(token.content)}</a>`;
-    };
 };
diff --git a/src/plugin/renderer.ts b/src/plugin/renderer.ts
@@ -0,0 +1,9 @@
+import {FILE_TOKEN, FileClassName} from './const';
+
+export const fileRenderer: markdownit.PluginSimple = (md) => {
+    md.renderer.rules[FILE_TOKEN] = (tokens, idx, _opts, _env, self) => {
+        const token = tokens[idx];
+        const iconHtml = `<span class="${md.utils.escapeHtml(FileClassName.Icon)}"></span>`;
+        return `<a${self.renderAttrs(token)}>${iconHtml}${md.utils.escapeHtml(token.content)}</a>`;
+    };
+};
diff --git a/src/plugin/transform.ts b/src/plugin/transform.ts
@@ -3,6 +3,7 @@ import MarkdownIt from 'markdown-it';
 import {type FileOptions, filePlugin} from './plugin';
 import {ENV_FLAG_NAME} from './const';
 import {hidden} from './utils';
+import {fileDirective} from './directive';
 
 export type PluginOptions = FileOptions & {
     output?: string;
@@ -14,6 +15,16 @@ export type TransformOptions = {
     runtime?: string | {style: string};
     bundle?: boolean;
     extraAttrs?: FileOptions['fileExtraAttrs'];
+    /**
+     * Enables directive syntax of yfm-file.
+     *
+     * - 'disabled' – directive syntax is disabled.
+     * - 'enabled' – directive syntax is enabled; old (curly bracket) syntax is also enabled.
+     * - 'only' – enabled only directive syntax; old (curly bracket) syntax is disabled.
+     *
+     * @default 'disabled'
+     */
+    directiveSyntax?: 'disabled' | 'enabled' | 'only';
     /** @internal */
     onBundle?: (env: {bundled: Set<string>}, output: string, runtime: RuntimeObj) => void;
 };
@@ -26,13 +37,20 @@ const registerTransform = (
         onBundle,
         runtime,
         output,
+        directiveSyntax,
     }: Pick<TransformOptions, 'extraAttrs' | 'onBundle'> & {
         bundle: boolean;
         runtime: {style: string};
         output: string;
+        directiveSyntax: NonNullable<TransformOptions['directiveSyntax']>;
     },
 ) => {
-    filePlugin(md, {fileExtraAttrs: extraAttrs});
+    if (directiveSyntax === 'disabled' || directiveSyntax === 'enabled') {
+        filePlugin(md, {fileExtraAttrs: extraAttrs});
+    }
+    if (directiveSyntax === 'enabled' || directiveSyntax === 'only') {
+        fileDirective(md, {fileExtraAttrs: extraAttrs});
+    }
 
     md.core.ruler.push('yfm_file_after', ({env}) => {
         if (env?.[ENV_FLAG_NAME]) {
@@ -49,7 +67,7 @@ const registerTransform = (
 };
 
 export const transform = (opts: TransformOptions = {}) => {
-    const {bundle = true} = opts;
+    const {bundle = true, directiveSyntax = 'disabled'} = opts;
 
     if (bundle && typeof opts.runtime === 'string') {
         throw new TypeError('Option `runtime` should be record when `bundle` is enabled.');
@@ -68,6 +86,7 @@ export const transform = (opts: TransformOptions = {}) => {
             bundle,
             runtime,
             output,
+            directiveSyntax,
             onBundle: opts.onBundle,
             extraAttrs: fileExtraAttrs ?? opts.extraAttrs,
         });
@@ -79,6 +98,7 @@ export const transform = (opts: TransformOptions = {}) => {
                 registerTransform(md, {
                     bundle,
                     runtime,
+                    directiveSyntax,
                     output: destRoot,
                     onBundle: opts.onBundle,
                     extraAttrs: opts.extraAttrs,