Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add yfm-cut extension #1

Merged
merged 3 commits into from
Jul 31, 2024
Merged

add yfm-cut extension #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f0b4495
add yfm-cut plugin
d3m1d0v Jul 12, 2024
2243eaa
add runtime and styles
d3m1d0v Jul 12, 2024
f3a9a1f
add readme
d3m1d0v Jul 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 66 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,68 @@
# cut-extension
# Diplodoc cut extension

[![NPM version](https://img.shields.io/npm/v/@diplodoc/viewer.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/viewer)
[![NPM version](https://img.shields.io/npm/v/@diplodoc/cut-extension.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/cut-extension)

This is an extension of the Diplodoc platform, which allows adding collapsible sections in the documentation.

The extension contains some parts:
- [Prepared runtime](#prepared-runtime)
- [MarkdownIt transform plugin](#markdownit-transform-plugin)

## Quickstart

Attach the plugin to the transformer:

```js
import cutExtension from '@diplodoc/cut-extension';
import transform from '@diplodoc/transform';

const {result} = await transform(`
{% cut "Cut title" %}

Cut content

{% endcut %}
`, {
plugins: [
tabsExtension.transform({ bundle: false })
]
});
```

## Prepared runtime

It is necessary to add `runtime` scripts to make cuts interactive on your page.<br/>
You can add assets files which were generated by the [MarkdownIt transform plugin](#markdownit-transform-plugin).
```html
<html>
<head>
<!-- Read more about '_assets/tabs-extension.js' and '_assets/tabs-extension.css' in 'Transform plugin' section -->
<script src='_assets/cut-extension.js' async></script>
<link rel='stylesheet' href='_assets/cut-extension.css' />
</head>
<body>
${result.html}
</body>
</html>
```

Or you can just include runtime's source code in your bundle.
```js
import '@diplodoc/cut-extension/runtime'
import '@diplodoc/cut-extension/runtime/styles.css'
```

## MarkdownIt transform plugin

Plugin for [@diplodoc/transform](https://github.com/diplodoc-platform/transform) package.

Options:
- `runtime.script` - name on runtime script which will be exposed in results `script` section.<br>
Default: `_assets/tabs-extension.js`<br>

- `runtime.style` - name on runtime css file which will be exposed in results `style` section.<br>
(Default: `_assets/tabs-extension.css`)<br>

- `bundle` - boolean flag to enable/disable copying of bundled runtime to target directory.<br>
Where target directore is `<transformer output option>/<plugin runtime option>`<br>
Default: `true`<br>
24 changes: 20 additions & 4 deletions esbuild/build.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
#!/usr/bin/env node

import {build} from 'esbuild';
import {sassPlugin} from 'esbuild-sass-plugin';

import tsConfig from '../tsconfig.json' assert { type: "json" };

Expand All @@ -14,9 +15,24 @@ const common = {
tsconfig: './tsconfig.json',
};

build({
/** @type {import('esbuild').BuildOptions}*/
const plugin = {
...common,
entryPoints: ['src/plugin/index.ts'],
outfile: outDir + 'plugin/index.js',
platform: 'node',
packages: 'external',
}

/** @type {import('esbuild').BuildOptions}*/
const runtime = {
...common,
entryPoints: ['src/index.ts'],
outfile: outDir + 'index.js',
entryPoints: ['src/runtime/index.ts'],
outfile: outDir + 'runtime/index.js',
minify: true,
});
platform: 'browser',
plugins: [sassPlugin()],
};

build(plugin);
build(runtime);
Loading
Loading