Issue 7624: New Documentation

.github/workflows/documentation.yml

@@ -0,0 +1,44 @@
+name: Documentation Deployment
+
+env:
+  GHA_DOCKER_TAG: docker.pkg.github.com/${{ github.repository }}/handsontable-documentation
+  GHA_DOCKER_TAG_SHA: docker.pkg.github.com/${{ github.repository }}/handsontable-documentation:${{ github.sha }}
+
+on:
+  push:
+    branches: [ vuepress, develop, feature/issue-7624 ]
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
+defaults:
+  run:
+    working-directory: ./docs/
+
+jobs:
+  docker:
+    name: Docker
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # v2
+
+      - name: Docker login into GHCR
+        run: |
+          echo "${{ secrets.GITHUB_TOKEN }}" | docker login -u ${GITHUB_ACTOR} --password-stdin https://docker.pkg.github.com
+
+      - name: Docker build
+        run: |
+          npm run docs:docker:build
+
+      - name: Docker tags
+        run: |
+          docker tag docs-md $GHA_DOCKER_TAG
+          docker tag docs-md $GHA_DOCKER_TAG_SHA
+
+      - name: Docker push latest into GHCR
+        run: |
+          docker push ${GHA_DOCKER_TAG}
+
+      - name: Docker push SHA tagged into GHCR
+        run: |
+          docker push ${GHA_DOCKER_TAG_SHA}

docs/.dockerignore

@@ -0,0 +1,17 @@
+pids
+logs
+node_modules
+npm-debug.log
+coverage/
+run
+dist
+.DS_Store
+.nyc_output
+.basement
+config.local.js
+basement_dist
+.idea
+
+# this file are required for build process (in opposite to .gitignore)
+!/.vuepress/public/handsontable.js
+!/.vuepress/public/handsontable.css

docs/.gitignore

@@ -0,0 +1,16 @@
+pids
+logs
+node_modules
+npm-debug.log
+coverage/
+run
+dist
+.DS_Store
+.nyc_output
+.basement
+config.local.js
+basement_dist
+.idea
+
+/.vuepress/public/handsontable.js
+/.vuepress/public/handsontable.css

docs/.vuepress/config.js

@@ -0,0 +1,93 @@
+const highlight = require('./highlight');
+const helpers = require('./helpers');
+const examples = require('./examples');
+
+const environmentHead = process.env.BUILD_MODE === 'production' ?
+  [
+    // Google Tag Manager, an extra element within the `ssr.html` file.
+    ['script', {}, `
+      (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+        new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+        j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+        '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+      })(window,document,'script','dataLayer','GTM-55L5D3');
+    `],
+    // Google Console //todo replace with valid token
+    // ['meta', { name: 'google-site-verification', content: 'MZpSOa8SNvFLRRGwUQpYVZ78kIHQoPVdVbafHhJ_d4Q' }]
+  ]
+  : [];
+
+module.exports = {
+  patterns: ['**/*.md', '!README.md', '!README-EDITING.md', '!README-DEPLOYMENT.md'], // to enable vue pages add: '**/*.vue'.
+  description: 'Handsontable',
+  base: '/docs/',
+  head: [
+    ['script', { src: '/scripts/handsontable-manager.js' }],
+    ...environmentHead
+  ],
+  markdown: {
+    toc: {
+      includeLevel: [2,3],
+      containerHeaderHtml: '<div class="toc-container-header">Table of contents</div>'
+    },
+  },
+  plugins: [
+    ['sitemap', {
+      hostname: 'https://handsontable.com'
+    }],
+    ['@vuepress/active-header-links', {
+      sidebarLinkSelector: '.table-of-contents a',
+      headerAnchorSelector: '.header-anchor'
+    }],
+    ['container', examples],
+    {
+      chainMarkdown (config) {
+        // inject custom markdown highlight with our snippet runner
+        config
+          .options
+          .highlight(highlight)
+          .end()
+      },
+    },
+    ['@vuepress/search', {
+      searchPlaceholder: 'Search...',
+      test: helpers.getLatestVersion().replace('.','\\.') // todo make sensible for currentVersion
+    }]
+  ],
+  extendPageData ($page) {
+    $page.versions = helpers.getVersions();
+    $page.latestVersion = helpers.getLatestVersion();
+    $page.currentVersion = helpers.parseVersion($page.path)
+
+    if($page.currentVersion === $page.latestVersion && $page.frontmatter.permalink) {
+        $page.frontmatter.permalink = $page.frontmatter.permalink.replace(/^\/[^/]*\//,'/');
+    }
+  },
+  themeConfig: {
+    logo: '/logo.png',
+    nextLinks: true,
+    prevLinks: true,
+    repo: 'handsontable/handsontable',
+    docsRepo: 'handsontable/handsontable',
+    docsDir: 'docs',
+    docsBranch: 'develop',
+    editLinks: true,
+    editLinkText: 'Help us improve this page',
+    lastUpdated: true,
+    smoothScroll: false,
+    nav: [
+      // Guide & API Reference has defined in: theme/components/NavLinks.vue
+      { text: 'Demo', link: 'https://handsontable.com/examples' },
+      { text: 'Support', items: [
+          { text: 'Forum', link: 'https://forum.handsontable.com' },
+          { text: 'Report an issue', link: 'https://github.com/handsontable/handsontable/issues/new' },
+          { text: 'Contact support', link: 'https://handsontable.com/contact?category=technical_support' },
+        ]
+      },
+    ],
+    displayAllHeaders: true, // collapse other pages
+    activeHeaderLinks: true,
+    sidebarDepth: 0,
+    sidebar: helpers.getSidebars()
+  }
+};

docs/.vuepress/enhanceApp.js

@@ -0,0 +1,16 @@
+// import RouterLink from './theme/components/RouterLink.vue';
+
+const buildRegisterCleaner = (register) => () => {
+    if(register === undefined){
+        console.warn('The register doesn\'t exists');
+        return;
+    }
+
+    register.destroyAll();
+}
+
+export default ({ Vue, options, router, siteData, isServer }) => {
+    if(!isServer) {
+        router.afterEach(buildRegisterCleaner(handsontableInstancesRegister));
+    }
+}

docs/.vuepress/examples.js

@@ -0,0 +1,67 @@
+/**
+ * Matches into: `example #ID .class`
+ * @type {RegExp}
+ */
+const exampleRegex = /^(example)\s*(#\S*|)\s*(\.\S*|)\s*([\S|\s]*)$/
+
+const JSFIDDLE_ENDPOINT = 'https://jsfiddle.net/api/post/library/pure/';
+
+const mapVersion = (version='latest') => (version.match(/^\d+\.\d+\.\d+$/) ? version : 'latest');
+
+const getHotUrls = (version) => {
+  const mappedVersion = mapVersion(version);
+
+  return [
+    `https://cdn.jsdelivr.net/npm/handsontable@${mappedVersion}/dist/handsontable.full.min.js`,
+    `https://cdn.jsdelivr.net/npm/handsontable@${mappedVersion}/dist/handsontable.full.min.css`,
+  ];
+};
+
+const getCss = (version) => {
+  const [scriptUrl, styleUrl] = getHotUrls(version);
+
+  return `</style><!-- Ugly Hack due to jsFiddle issue -->
+<script src="${scriptUrl}"></script>
+<link type="text/css" rel="stylesheet" href="${styleUrl}" />
+`;
+}
+
+const getHtml = (id) => `<div id="${id}" ></div>`;
+const jsfiddle = (id, code)=>{
+  return `
+    <form
+      id="jsfiddle-${id}"
+      action=${JSFIDDLE_ENDPOINT}
+      method="post"
+      target="_blank"
+      style="display:none;"
+    >
+      <input type="text" name="title" readOnly value="Handsontable example" />
+      <input type="text" name="wrap" readOnly value="d" />
+      <textarea name="js" readOnly>${code}</textarea>
+      <textarea name="html" readOnly>${getHtml(id)}</textarea>
+      <textarea name="css" readOnly>${getCss()}</textarea>
+    </form>
+    <div class="js-fiddle-link"><button type="submit" form="jsfiddle-${id}"><i class="fa fa-jsfiddle"></i>Edit</button></div>
+  `;
+}
+module.exports = {
+  type: 'example',
+  render: function (tokens, index, opts, env) {
+    const token = tokens[index]
+    const tokenNext = tokens[index + 1]
+    const m = token.info.trim().match(exampleRegex);
+    const version = env.relativePath.split('/')[0];
+
+    if (token.nesting === 1 && m) {
+      let [full, tag, id, klass, content] = m;
+      id = id ? id.substring(1): '';
+      klass = klass ? klass.substring(1) : '';
+      // opening tag
+      return `<div data-jsfiddle="${id}"><div id="${id}" class="hot ${klass}"></div></div><script data-jsfiddle="${id}">useHandsontable('${version}', ()=>{${tokenNext.content}});</script><div class="codeLayout">${jsfiddle(id, tokenNext.content)}\n`;
+    } else {
+      // closing tag
+      return `</div>\n`;
+    }
+  }
+}

docs/.vuepress/helpers.js

@@ -0,0 +1,37 @@
+const fs = require('fs');
+const path = require('path');
+const semver = require('semver');
+
+// TODO: adjust to meet the monorepo structure requirements
+const unsortedVersions = fs.readdirSync(path.join(__dirname, '..'))
+  .filter(f => semver.valid(semver.coerce(f)));
+
+const versions = unsortedVersions.sort((a, b) => semver.rcompare(semver.coerce(a), semver.coerce((b))))
+
+module.exports = {
+  getVersions () {
+    return ['next', ...versions];
+  },
+
+  getLatestVersion () {
+    return versions[0];
+  },
+
+  getSidebars () {
+    const sidebars = { };
+    const versions = this.getVersions();
+
+    versions.forEach(version => {
+      const s = require(path.join(__dirname, `../${version}/sidebars.js`));
+
+      sidebars[`/${version}/api/`] = s.api;
+      sidebars[`/${version}/`] = s.guide;
+    });
+
+    return sidebars;
+  },
+
+  parseVersion(url){
+    return url.split('/')[1] || this.getLatestVersion();
+  }
+};

docs/.vuepress/highlight.js

@@ -0,0 +1,57 @@
+const prism = require('prismjs')
+const loadLanguages = require('prismjs/components/index')
+const { logger, chalk, escapeHtml } = require('@vuepress/shared-utils')
+
+// required to make embedded highlighting work...
+loadLanguages(['markup', 'css', 'javascript'])
+
+function wrap (code, lang) {
+  if (lang === 'text') {
+    code = escapeHtml(code)
+  }
+  return `<pre v-pre class="language-${lang}"><code>${code}</code></pre>`
+}
+
+function getLangCodeFromExtension (extension) {
+  const extensionMap = {
+    vue: 'markup',
+    html: 'markup',
+    md: 'markdown',
+    rb: 'ruby',
+    ts: 'typescript',
+    py: 'python',
+    sh: 'bash',
+    yml: 'yaml',
+    styl: 'stylus',
+    kt: 'kotlin',
+    rs: 'rust',
+    hf: 'excel-formula',
+    formula: 'excel-formula',
+    hyperformula: 'excel-formula',
+  }
+
+  return extensionMap[extension] || extension
+}
+
+module.exports = (str, lang) => {
+  if (!lang) {
+    return wrap(str, 'text')
+  }
+  lang = lang.toLowerCase()
+  const rawLang = lang
+
+  lang = getLangCodeFromExtension(lang)
+
+  if (!prism.languages[lang]) {
+    try {
+      loadLanguages([lang])
+    } catch (e) {
+      logger.warn(chalk.yellow(`[vuepress] Syntax highlight for language "${lang}" is not supported.`))
+    }
+  }
+  if (prism.languages[lang]) {
+    const code = prism.highlight(str, prism.languages[lang], lang)
+    return wrap(code, rawLang)
+  }
+  return wrap(str, 'text')
+}