Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/diplodoc-platform/file-extension
File extension for Diplodoc platform
https://github.com/diplodoc-platform/file-extension
Last synced: about 1 month ago
JSON representation
File extension for Diplodoc platform
- Host: GitHub
- URL: https://github.com/diplodoc-platform/file-extension
- Owner: diplodoc-platform
- License: mit
- Created: 2024-11-13T08:23:52.000Z (about 2 months ago)
- Default Branch: master
- Last Pushed: 2024-11-13T09:19:35.000Z (about 2 months ago)
- Last Synced: 2024-11-13T10:26:10.784Z (about 2 months ago)
- Language: JavaScript
- Size: 66.4 KB
- Stars: 0
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Diplodoc file extension
[](https://www.npmjs.org/package/@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](#prepared-styles)
- [MarkdownIt transform plugin](#markdownit-transform-plugin)
## Quickstart
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](#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](https://github.com/diplodoc-platform/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`
## File markup
```md
{% file src="path/to/file" name='readme.md' %}
==>
readme.md
```
### Supported attributes:
| Name | Required | Description |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src` | yes | URL of the file. Will be mapped to [`href` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href) |
| `name` | yes | Name of the file. Will be mapped to [`download` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-download) |
| `lang` | - | Language of the file content. Will be mapped to [`hreflang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-hreflang) |
| `referrerpolicy` | - | [`referrerpolicy` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-referrerpolicy) |
| `rel` | - | [`rel` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-rel) |
| `target` | - | [`target` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target) |
| `type` | - | [`type` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-type) |
> _Note: other attributes will be ignored_
### Plugin options
| Name | Type | Description |
| ---------------- | -------------------- | ------------------------------------------------ |
| `fileExtraAttrs` | `[string, string][]` | Adds additional attributes to rendered hyperlink |
## CSS public variables
- `--yfm-file-icon` – sets custom file icon image
- `--yfm-file-icon-color` – sets custom file icon color