Skip to content

Latest commit

 

History

History
126 lines (88 loc) · 5.45 KB

README.md

File metadata and controls

126 lines (88 loc) · 5.45 KB
Raw

Diplodoc file extension

NPM version

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