diplodoc-platform · makhnatkin · Jun 28, 2024 · Jun 12, 2024 · Jun 12, 2024 · Jun 14, 2024
diff --git a/.eslintignore b/.eslintignore
@@ -1,3 +1,8 @@
 /build
 /coverage
 /node_modules
+/runtime
+/react
+/plugin
+/example/node_modules
+/example/build
diff --git a/.gitignore b/.gitignore
@@ -6,7 +6,15 @@
 /build
 /coverage
 /node_modules
+/runtime
+/plugin
+/react
 
 # libraries
 npm-debug.log
 
+index.d.ts
+*.d.ts
+example/package-lock.json
+example/build
+example/node_modules
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm run precommit
diff --git a/.npmignore b/.npmignore
@@ -0,0 +1,3 @@
+src
+esbuild
+example
diff --git a/README-template.md b/README-template.md
diff --git a/README.md b/README.md
@@ -1,11 +1,139 @@
-## How to start
+# Diplodoc html extension
 
-```bash
-# Clone this repo to new folder
-git clone [email protected]:diplodoc-platform/package-template.git new-package
-cd new-package
+#### TODO: add html-extension.svg
+[![NPM version](https://img.shields.io/npm/v/@diplodoc/html-extension.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/html-extension)
 
-# Init repo with new package name
-./init.sh new-package
+This is an extension of the Diplodoc platform, which allows adding HTML in the documentation.
+
+The extension contains some parts:
+- [Prepared runtime](#prepared-runtime)
+- [MarkdownIt transform plugin](#markdownit-transform-plugin)
+- [HTML plugin API](#api)
+- [React hook for smart control](#react-hook-for-smart-control)
+
+## Quickstart
+
+Attach the plugin to the transformer:
+
+```js
+import htmlExtension from '@diplodoc/html-extension';
+import transform from '@diplodoc/transform';
+import * as sanitizeHtml from 'sanitize-html';
+
+const {result} = await transform(`
+::: html
+
+<article class="forecast">
+  <h1>Weather forecast for Seattle</h1>
+  <article class="day-forecast">
+    <h2>12 June 2024</h2>
+    <p>Rain.</p>
+  </article>
+  <article class="day-forecast">
+    <h2>13 June 2024</h2>
+    <p>Periods of rain.</p>
+  </article>
+  <article class="day-forecast">
+    <h2>14 June 2024</h2>
+    <p>Heavy rain.</p>
+  </article>
+</article>
+
+:::
+`, {
+    plugins: [
+        htmlExtension.transform({
+            sanitize: dirtyHtml => sanitizeHtml(dirtyHtml, {
+                allowedTags: ['article', 'h1', 'h2', 'p', 'span'],
+                allowedAttributes: {
+                    '*': ['class']
+                }
+            }),
+            containerClasses: 'my-own-class'
+        })
+    ]
+});
+```
+
+## Prepared runtime
+
+It is necessary to add `runtime` scripts to make html 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/html-extension.js' and '_assets/html-extension.css' in 'Transform plugin' section -->
+        <script src='_assets/html-extension.js' async></script>
+    </head>
+    <body>
+        ${result.html}
+    </body>
+</html>
+```
+
+Or you can just include runtime's source code in your bundle.
+```js
+import '@diplodoc/html-extension/runtime'
+```
+
+## MarkdownIt transform plugin
+
+Plugin for [@diplodoc/transform](https://github.com/diplodoc-platform/transform) package.
+
+Options:
+- `runtimeJsPath` - name on runtime script which will be exposed in results `script` section.<br>
+  Default: `_assets/html-extension.js`<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>
+
+- `containerClasses` - additional classes which will be added to tab's container node. It allows to customize the html view.<br>
+  Example: `my-own-class and-other-class`<br>
+  Default: `undefined`<br>
+
+## API
+
+### Syntax
+
+This plugin uses the directive syntax [proposed](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) in the CommonMark community, indicated by a block-level double colon at the beginning and end of a block. This HTML directives use `::: html` to open an HTML block, followed by your HTML content, and then `:::` to close the block. The number of empty lines before or after the opening or closing block is not significant.
+
+Please note:
+- Nested content within the block will not be parsed as Markdown.
+- Embedded directives within the block are not supported.
+- Inline directives are not yet supported.
+
+
+Simple example:
 ```
+::: html
 
+<div>Your HTML code is here</div>
+
+:::
+```
+Example with some styles:
+```
+::: html
+<style>
+<style>
+  :root {
+    --dark-bg-color: #000;
+    --dark-text-color: #FFF;
+  }
+  .dark {
+    background-color: var(--primary-bg-color);
+    color: : var(--primary-text-color);
+  }
+</style>
+<div class="dark">Some info is here</div>
+:::
+```
+
+## React hook for smart control
+
+You can use the React hook to interact programmatically with the HTML content inside the block.
+
+```TypeScript
+// TODO
+```
diff --git a/esbuild/build.js b/esbuild/build.js
diff --git a/esbuild/build.mjs b/esbuild/build.mjs
@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import {readFileSync} from 'node:fs';
+import {fileURLToPath} from 'url';
+import {dirname} from 'path';
+
+import {build} from 'esbuild';
+import {sassPlugin} from 'esbuild-sass-plugin';
+const tsconfigJson = readJSON('../tsconfig.json');
+const packageJson = readJSON('../package.json');
+
+const {
+    compilerOptions: {target},
+} = tsconfigJson;
+
+const common = {
+    bundle: true,
+    sourcemap: true,
+    target,
+    tsconfig: './tsconfig.json',
+};
+
+build({
+    ...common,
+    entryPoints: ['src/runtime/index.ts'],
+    outfile: 'runtime/index.js',
+    minify: true,
+    platform: 'browser',
+    plugins: [
+        sassPlugin()
+    ],
+});
+
+build({
+    ...common,
+    entryPoints: ['src/react/index.ts'],
+    outfile: 'react/index.js',
+    platform: 'neutral',
+    external: ['react'],
+    target: 'es6',
+    format: 'cjs',
+});
+
+build({
+    ...common,
+    entryPoints: ['src/plugin/index.ts'],
+    outfile: 'plugin/index.js',
+    platform: 'node',
+    packages: 'external',
+    define: {
+        PACKAGE: JSON.stringify(packageJson.name),
+    },
+});
+
+function readJSON(path) {
+    const currentFilename = fileURLToPath(import.meta.url);
+    return JSON.parse(readFileSync(`${dirname(currentFilename)}/${path}`));
+}
diff --git a/example/README.md b/example/README.md
@@ -0,0 +1,59 @@
+# Simple example
+
+```
+npm i
+npm start
+```
+
+Then this documentation will be rendered by [@diplodoc/transform](https://github.com/diplodoc-platform/transform) and opened in your default browser.
+
+# Example
+
+::: html
+<div>Simple HTML code</div>
+:::
+
+## Markdown header
+Markdown text
+
+::: html
+<div>HTML code with table</div>
+<style>
+/*****************/
+/***  header   ***/
+/*****************/
+.header {
+    background: #EEE;
+    border-radius: 16px;
+    font-size: 40px;
+    line-height: 40px;
+    padding:16px;
+    box-sizing: border-box;
+    color: #363E45;
+    height:335px;
+}
+.text_header { font-size:16px; line-height:120%; font-weight:500; }
+
+</style>
+
+<!----------------->
+<!--   header   --->
+<!----------------->
+<table width="100%">
+    <tr>
+        <td width="74%" class="header">
+            <div style="width:720px">
+                <strong>Header</strong>
+                <div class="text_header" style="width:520px">Some text here</div>
+            </div>
+        </td>
+        <td width="1%" style="padding-left:6px"></td>
+        <td width="25%" style="min-width:300px"></td>
+    </tr>
+</table>
+
+:::
+
+
+
+After html text
diff --git a/example/index.js b/example/index.js
@@ -0,0 +1,34 @@
+import transform from '@diplodoc/transform';
+import htmlPlugin from '@diplodoc/html-extension';
+
+import {readFile, writeFile} from 'node:fs/promises';
+import {exec} from 'node:child_process';
+import {promisify} from 'node:util';
+
+(async () => {
+    const content = await readFile('./README.md', 'utf8');
+    const {result} = await transform(content, {
+        needToSanitizeHtml: false,
+        output: './build',
+        plugins: [
+            htmlPlugin.transform({
+                bundle: true,
+            }),
+        ],
+    });
+
+    const html = `
+<html>
+    <head>
+        ${result.meta.script.map((scriptFile) => `<script src="${scriptFile}"></script>`).join('\n')}
+        ${result.meta.style.map((styleFile) => `<link rel="stylesheet" href="${styleFile}" />`).join('\n')}
+    </head>
+    <body>
+        ${result.html}
+    </body>
+</html>
+    `;
+
+    await writeFile('./build/index.html', html);
+    await promisify(exec)('open build/index.html');
+})();
diff --git a/example/package.json b/example/package.json
@@ -0,0 +1,12 @@
+{
+  "name": "@diplodoc/html-extension-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node ."
+  },
+  "dependencies": {
+    "@diplodoc/html-extension": "file:..",
+    "@diplodoc/transform": "*"
+  }
+}
diff --git a/jest.config.js b/jest.config.js
@@ -0,0 +1,9 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+    preset: 'ts-jest',
+    transform: {
+        '^.+\\.(j|t)s?$': ['ts-jest', {tsconfig: '<rootDir>/test/tsconfig.json'}],
+    },
+    transformIgnorePatterns: [],
+    testEnvironment: 'jsdom',
+};
-Original file line number
+Diff line change
@@ -0,0 +1,3 @@
+    src
+    esbuild
+    example