This is an extension of the Diplodoc platform, which allows adding links to files in the documentation.
The extension contains some parts:
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})],
},
);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';Plugin for @diplodoc/transform package.
Options:
-
runtime.style- name on runtime css file which will be exposed in resultsstylesection.
(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 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>| 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
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}| 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
--yfm-file-icon– sets custom file icon image--yfm-file-icon-color– sets custom file icon color