diplodoc-platform · d3m1d0v · Nov 18, 2024 · Nov 13, 2024 · Nov 13, 2024
diff --git a/README.md b/README.md
@@ -2,3 +2,98 @@
 
 [![NPM version](https://img.shields.io/npm/v/@diplodoc/file-extension.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/file-extension)
 
+This is an extension of the Diplodoc platform, which allows adding links to files in the documentation.
+
+The extension contains some parts:
+
+- [Prepared styles](#prepared-styles)
+- [MarkdownIt transform plugin](#markdownit-transform-plugin)
+
+## Quickstart
+
+Attach the plugin to the transformer:
+
+```js
+import * as fileExtension from '@diplodoc/file-extension';
+import transform from '@diplodoc/transform';
+
+const {result} = await transform(
+  `
+Download here: {% file src="path/to/file" name='readme.md' %}
+`,
+  {
+    plugins: [fileExtension.transform({bundle: false})],
+  },
+);
+```
+
+## Prepared styles
+
+It is necessary to add styles for file links on your page.<br/>
+You can add assets files which were generated by the [MarkdownIt transform plugin](#markdownit-transform-plugin).
+
+```html
+<html>
+  <head>
+    <!-- Read more about '_assets/file-extension.css' in 'Transform plugin' section -->
+    <link rel="stylesheet" href="_assets/file-extension.css" />
+  </head>
+  <body>
+    ${result.html}
+  </body>
+</html>
+```
+
+Or you can just include styles source code in your bundle.
+
+```js
+import '@diplodoc/cut-extension/runtime/styles.css';
+```
+
+## MarkdownIt transform plugin
+
+Plugin for [@diplodoc/transform](https://github.com/diplodoc-platform/transform) package.
+
+Options:
+
+- `runtime.style` - name on runtime css file which will be exposed in results `style` section.<br>
+  (Default: `_assets/file-extension.css`)<br>
+
+- `bundle` - boolean flag to enable/disable copying of bundled runtime to target directory.<br>
+  Where target directore is `<transformer output option>/<plugin runtime option>`<br>
+  Default: `true`<br>
+
+## File markup
+
+```md
+{% file src="path/to/file" name='readme.md' %}
+
+==>
+
+<a href="path/to/file" download="readme.md" class="yfm-file"><span class="yfm-file__icon"></span>readme.md</a>
+```
+
+### 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)                                                         |
+
+> _Note: other attributes will be ignored_
+
+### Plugin options
+
+| Name             | Type                 | Description                                      |
+| ---------------- | -------------------- | ------------------------------------------------ |
+| `fileExtraAttrs` | `[string, string][]` | Adds additional attributes to rendered hyperlink |
+
+## CSS public variables
+
+- `--yfm-file-icon` – sets custom file icon image
+- `--yfm-file-icon-color` – sets custom file icon color
diff --git a/esbuild/build.mjs b/esbuild/build.mjs
@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import {build} from 'esbuild';
+import {sassPlugin} from 'esbuild-sass-plugin';
 
 import tsConfig from '../tsconfig.json' assert {type: 'json'};
 
@@ -14,9 +15,34 @@ const common = {
     tsconfig: './tsconfig.publish.json',
 };
 
-build({
+/** @type {import('esbuild').BuildOptions}*/
+const plugin = {
     ...common,
-    entryPoints: ['src/index.ts'],
-    outfile: outDir + '/index.js',
+    entryPoints: ['src/plugin/index.ts'],
+    outfile: outDir + '/plugin/index.js',
+    platform: 'node',
     packages: 'external',
-});
+};
+
+/** @type {import('esbuild').BuildOptions}*/
+const pluginNode = {
+    ...common,
+    entryPoints: ['src/plugin/index-node.ts'],
+    outfile: outDir + '/plugin/index-node.js',
+    platform: 'node',
+    packages: 'external',
+};
+
+/** @type {import('esbuild').BuildOptions}*/
+const runtime = {
+    ...common,
+    entryPoints: ['src/runtime/index.ts'],
+    outfile: outDir + '/runtime/index.js',
+    minify: true,
+    platform: 'browser',
+    plugins: [sassPlugin()],
+};
+
+build(plugin);
+build(pluginNode);
+build(runtime);