@diplodoc/file-extension

Diplodoc platform extension that provides file links in documentation. Allows adding downloadable file links with customizable styling and asset bundling support.

Features

- MarkdownIt transform plugin — Process file directives in YFM
- Runtime styles — SCSS styles for file links
- File markup syntax — {% file src="..." name="..." %} syntax support
- Directive syntax — Modern :filename syntax support
- Asset bundling — Integration with documentation build process

Installation

``bash
npm install @diplodoc/file-extension
`

Usage

$3

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.

You can add assets files which were generated by the MarkdownIt transform plugin.

`html






${result.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 package.

Options:

- runtime.style - name on runtime css file which will be exposed in results style section.

(Default: _assets/file-extension.css)


- bundle - boolean flag to enable/disable copying of bundled runtime to target directory.

Where target directore is /

Default: true


- extraAttrs – array of additional attributes in format [name, value], that will be added to file links\
Default: undefined

- directiveSyntax – enables new directive syntax. \
Available values: 'disabled' | 'enabled' | 'only'\
Default: 'disabled'

File markup

`md
{% file src="path/to/file" name='readme.md' %}

==>

readme.md
`

$3

| Name | Required | Description |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| src | yes | URL of the file. Will be mapped to href attribute |
| name | yes | Name of the file. Will be mapped to download attribute |
| lang | - | Language of the file content. Will be mapped to hreflang attribute |
| referrerpolicy | - | referrerpolicy attribute |
| rel | - | rel attribute |
| target | - | target attribute |
| type | - | type attribute |

> _Note: other attributes will be ignored_

Directive syntax

Also you can use inline directive syntax for file links. For more information see here: diplodoc-platform/directive.

To enable directive syntax pass directiveSyntax: 'enabled' to options. Or you can disabled old syntax and use only directive syntax: directiveSyntax: 'only'.

`md
:file

:filereadme.md{type=text/plain}
`

$3

| Name | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| hreflang | anchor hreflang attribute |
| referrerpolicy | anchor referrerpolicy attribute |
| rel | anchor rel attribute |
| target | anchor target attribute |
| type | anchor type attribute |

> _Note: other attributes will be ignored_

CSS public variables

- --yfm-file-icon – sets custom file icon image
- --yfm-file-icon-color – sets custom file icon color

Development

$3

`bash


Install dependencies

npm install

Build package

npm run build

Run tests

npm test

Lint code

npm run lint
``

Documentation

For detailed information about architecture, development, and contributing, see AGENTS.md.

License

MIT