Move code samples to separate files and update links in documentation

docs/.eslintrc.js

@@ -5,6 +5,7 @@ module.exports = {
     parser: 'babel-eslint',
     sourceType: 'module'
   },
+  ignorePatterns: ['**/guides/**/*.js'],
   rules: {
     'no-restricted-globals': 'off',
     'import/no-unresolved': 'off'

docs/.vuepress/config.js

@@ -11,6 +11,7 @@ const dumpDocsDataPlugin = require('./plugins/dump-docs-data');
 const dumpRedirectPageIdsPlugin = require('./plugins/dump-redirect-page-ids');
 const firstHeaderInjection = require('./plugins/markdown-it-header-injection');
 const conditionalContainer = require('./plugins/markdown-it-conditional-container');
+const includeCodeSnippet = require('./plugins/markdown-it-include-code-snippet');
 const {
   createSymlinks,
   getDocsBase,
@@ -171,7 +172,9 @@ module.exports = {
       rel: 'nofollow noopener noreferrer',
     },
     extendMarkdown(md) {
-      md.use(conditionalContainer).use(firstHeaderInjection);
+      md.use(includeCodeSnippet)
+        .use(conditionalContainer)
+        .use(firstHeaderInjection);
     },
   },
   configureWebpack: {

docs/.vuepress/plugins/markdown-it-include-code-snippet/index.js

@@ -0,0 +1,105 @@
+const fs = require('fs');
+
+const fileExists = filePath => fs.existsSync(filePath);
+
+const readFileContent = filePath =>
+  (fileExists(filePath)
+    ? fs.readFileSync(filePath).toString()
+    : `Not Found: ${filePath}`);
+
+const parseOptions = (optionsString) => {
+  const parsedOptions = {};
+
+  optionsString
+    .trim()
+    .split(' ')
+    .forEach((pair) => {
+      const [option, value] = pair.split('=');
+
+      parsedOptions[option] = value;
+    });
+
+  return parsedOptions;
+};
+
+module.exports = function includeCodeSnippet(markdown, options) {
+  const rootDirectory = options && options.root ? options.root : process.cwd();
+
+  const createDataObject = (state, position, maximum) => {
+    const start = position + 6;
+    const end = state.skipSpacesBack(maximum, position) - 1;
+    const [optionsString, fullpathWithAtSym] = state.src
+      .slice(start, end)
+      .trim()
+      .split('](');
+
+    const fullpath = fullpathWithAtSym.replace(/^@/, rootDirectory).trim();
+    const pathParts = fullpath.split('/');
+    const fileParts = pathParts[pathParts.length - 1].split('.');
+
+    return {
+      file: {
+        resolve: fullpath,
+        path: pathParts.slice(0, pathParts.length - 1).join('/'),
+        name: fileParts.slice(0, fileParts.length - 1).join('.'),
+        ext: fileParts[fileParts.length - 1],
+      },
+      options: parseOptions(optionsString),
+      content: readFileContent(fullpath),
+      fileExists: fileExists(fullpath),
+    };
+  };
+
+  // eslint-disable-next-line no-shadow
+  const mapOptions = ({ options }) => ({
+    hasHighlight: options.highlight || false,
+    get meta() {
+      return this.hasHighlight ? options.highlight : '';
+    },
+  });
+
+  /**
+   * Custom parser function for handling code snippets in markdown.
+   *
+   * @param {object} state - The current state object of the markdown-it parser.
+   * @param {number} startLine - The line number where the code snippet starts.
+   * @param {number} endLine - The line number where the code snippet ends.
+   * @param {boolean} silent - Flag indicating whether the parser should run in silent mode.
+   * @returns {boolean} - Returns true if the code snippet was successfully parsed, false otherwise.
+   */
+  function customParser(state, startLine, endLine, silent) {
+    const fenceMarker = '@[code]';
+    const position = state.bMarks[startLine] + state.tShift[startLine];
+    const maximum = state.eMarks[startLine];
+
+    // Early return for indented blocks
+    if (state.sCount[startLine] - state.blkIndent >= 4) return false;
+
+    if (!state.src.startsWith(fenceMarker, position)) {
+      // Early return if fence marker is not present
+      return false;
+    }
+
+    if (silent) {
+      // Handle silent mode
+      return true;
+    }
+
+    const dataObject = createDataObject(state, position, maximum);
+    const optionsMapping = mapOptions(dataObject);
+
+    const token = state.push('fence', 'code', 0);
+
+    token.info =
+      (dataObject.options.lang || dataObject.file.ext) + optionsMapping.meta;
+    token.content = dataObject.content;
+    token.markup = '```';
+    token.map = [startLine, startLine + 1];
+
+    state.line = startLine + 1;
+
+    return true;
+  }
+
+  markdown.block.ruler.before('fence', 'snippet', customParser);
+};

docs/README-EDITING.md

@@ -162,7 +162,7 @@ To link to another page but for other framework (and still for the same document
 For example, to link to a file called `./content/guides/getting-started/react-methods.md` that should be accessible only for React framework, use:
 
 ```markdown
-[React methods](@/react/guides/getting-started/react-methods.md)
+[React methods](@/react/guides/getting-started/react-methods/react-methods.md)
 ```
 
 When there is no framework defined in the link URL, the generated link will be pointed to the currently viewed framework. For example, link `[Core](@/api/core.md)` for Javascript will point to `/docs/javascript-data-grid/api/core` and for chosen React framework to `/docs/react-data-grid/api/core`.
@@ -171,7 +171,7 @@ List of available frameworks: `javascript`, `react`.
 
 Follow these rules:
 * After the `@` character, provide the target's relative file path (from the current version's root directory).<br>
-  For example: `[Clipboard][@/guides/cell-features/clipboard.md]`.
+  For example: `[Clipboard][@/guides/cell-features/clipboard/clipboard.md]`.
 * After the target file's name, add the `.md` [extension](#filenames)<br>
   For example: `[Autofill](@/api/autofill.md)`.
 * To link to a specific section, use anchors.<br>
@@ -277,7 +277,7 @@ The `example` Markdown container offers the following options:
 ### Non-editable examples
 You can also embed an example without the tabbed container.
 To display just the result of the code you want to present, use the `<HandsontablePreview>` component. The code wrapped in this component and a markdown code block will be rendered with the context of the current Handsontable version.
-````js
+```js
 <HandsontablePreview>
 ```js
   // enter the Handsontable-related code here.
@@ -286,7 +286,7 @@ To display just the result of the code you want to present, use the `<Handsontab
   new Handsontable(containerElement, {});
 ```
 </HandsontablePreview>
-````
+```
 
 **Note: Remember to place all the needed HTML and `<style>` elements in the markdown file as well.**
 

docs/README.md

@@ -84,7 +84,7 @@ docs                            # All documentation files
 │   │   ├── jsdoc-convert       # JSDoc-to-Markdown converter
 │   │   ├── utils.js            # Tools utilities
 │   ├── config.js               # VuePress configuration
-│   ├── docs-links.js           # Lets us link within the currently-selected docs version and framework with `@` (e.g. [link](@/guides/path/file.md).)
+│   ├── docs-links.js           # Lets us link within the currently-selected docs version and framework with `@` (e.g. [link](@/guides/path/file/file.md).)
 │   ├── enhanceApp.js           # VuePress app-level enhancements
 │   ├── helpers.js              # Common helpers that set up sidebars and the documentation version and framework picker
 │   └── highlight.js            # Code highlight configuration

docs/content/api/introduction.md

@@ -17,7 +17,7 @@ react:
 
 Welcome to Handsontable's API reference. Our goal is to make it easy to dive in and start coding from day one.
 
-However, data grids are rather complex libraries, so we assume that you possess a certain level of expertise in JavaScript before moving forward. If you want to grab some basics, we have provided a JavaScript example in the [demo](@/guides/getting-started/demo.md) section.
+However, data grids are rather complex libraries, so we assume that you possess a certain level of expertise in JavaScript before moving forward. If you want to grab some basics, we have provided a JavaScript example in the [demo](@/guides/getting-started/demo/demo.md) section.
 
 The API enables you to control the data grid programmatically. With this API, you can: