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
MarkdownIt transform plugin

Quickstart

Attach the plugin to the transformer:

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>
  <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.

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 <transformer output option>/<plugin runtime option>
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

{% 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
`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'.

:file[<file-name>](file-url)

<!-- Example: -->

:file[readme.md](path/to/readme/md){type=text/plain}

Supported attributes:

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