@diplodoc/file-extension
v0.2.1
Published
Template package for Diplodoc platform development
Downloads
2,862
Keywords
Readme
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:
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 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:trueextraAttrs– array of additional attributes in format[name, value], that will be added to file links
Default:undefineddirectiveSyntax– 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