feat: examples infrastructure

Close #24

Author: molant

.markdownlint.json

@@ -23,5 +23,6 @@
       "br_spaces": 0
     },
     "single-h1": false,
-    "no-inline-html": false
+    "no-inline-html": false,
+    "ul-style": false
   }

.vscode/launch.json

@@ -15,7 +15,8 @@
       ],
       "skipFiles": [
         "<node_internals>/**"
-      ]
+      ],
+      "console": "integratedTerminal"
     },
     {
       "type": "pwa-node",

README.md

@@ -6,6 +6,13 @@ This repository contains the code and contents of https://crossplatform.dev.
 
 It is built using [Docusaurus 2](https://docusaurus.io/) and deployed on Netlify.
 
+Table of contents:
+
+* [Installation](#installation)
+* [Local development](#local-development)
+* [Writing code examples](#writing-code-examples)
+* [Adding a new technology](#adding-a-new-technology)
+
 ## Installation
 
 To install it locally, you will need to:
@@ -47,6 +54,58 @@ npm start
 Most changes, like markdown modifications, `sidebars.js`, etc. are
 reflected live without having to restart the server.
 
+## Writing code examples
+
+The website also has a couple remark plugins that make it easier to have examples side by side.
+They live under the [`/src/transformers`][transformers] folder:
+
+- `import-code` allows you to reference a code file an "import" it automatically when building
+  the website. This is useful to separate the code from the text. You can use it as follows:
+
+  ````md
+  Look at this JavaScript code:
+
+  ```js (./path/to/code.js)
+  ```
+  ````
+
+  The contents of `./path/to/code.js` will be loaded and place inside the codeblock using the
+  indicated language. There is no need to have any content in the codeblock.
+
+- `partial-content` allows you to include the contents of a markdown file into another file. That
+  way you can have a markdown file per technology:
+
+  ```md
+  # This is an example
+
+  {@import ./path/to/example.pmd}
+  ```
+
+  Although the extension is `.pmd` (Partial MarkDown), the contents are the same as a regular
+  markdown file. The reason to change the extension is to avoid building it with Docusaurus.
+  When using it in combination with [Docusaurus tabs] and writting MDX, you can end up with
+  something like the following:
+
+  ```jsx
+  import Tabs from '@theme/Tabs';
+  import TabItem from '@theme/TabItem';
+
+  <Tabs>
+    <TabItem value="electron" label="Electron" default>
+      {@import ./electron.pmd}
+    </TabItem>
+    <TabItem value="pwa" label="PWA">
+      {@import ./pwa.pmd}
+    </TabItem>
+    <TabItem value="wv2" label="WebView2">
+      {@import ./wv2.pmd}
+    </TabItem>
+  </Tabs>;
+   ```
+
+`partial-content` files can also make use of `import-code`.
+
+
 ## Adding a new technology
 
 To create a new technology overview, run the following command:
@@ -57,10 +116,10 @@ npm run add-technology
 
 You will be prompted the technology name and once provided:
 
-* a new folder will be created under `/docs/` with its name
-* the folder will have a few markdown files for you to complete
-* `sidebars.js` will be updated to include the new technology
-* a new file will be created under `/data/technologies/TECHNOLOGY.js`
+- a new folder will be created under `/docs/` with its name
+- the folder will have a few markdown files for you to complete
+- `sidebars.js` will be updated to include the new technology
+- a new file will be created under `/data/technologies/TECHNOLOGY.js`
   for you to complete
 
 ![video of "npm run add-technology" running](./static/img/add-technology.webp)
@@ -175,9 +234,10 @@ and it will generate a table using the property names of the 1st
 object as the column names, adding a new line per item in the Array:
 
 ```markdown
-| Version | Date |
-| --- | --- |
-| vX.Y.Z | 2021/10/01 |
+| Version | Date       |
+| ------- | ---------- |
+| vX.Y.Z  | 2021/10/01 |
+
 ...
 ```
 
@@ -191,10 +251,15 @@ and the output will be:
 
 ```markdown
 | Version |
-| --- |
-| vX.Y.Z |
+| ------- |
+| vX.Y.Z  |
+
 ...
 ```
 
+<!-- Reference links -->
+
+[Docusaurus tabs]: https://docusaurus.io/docs/markdown-features/tabs
 [git]: https://git-scm.com/downloads
-[node.js]: https://nodejs.org/en/download/
+[node.js]: https://nodejs.org/en/download/
+[transformers]: https://github.com/crossplatform-dev/crossplatform.dev/tree/main/src/transformers

docusaurus.config.js

@@ -1,4 +1,6 @@
 const interpolateData = require('./src/transformers/interpolate-data');
+const importCode = require('./src/transformers/import-code');
+const partialContent = require('./src/transformers/partial-content');
 
 /** @type {import('@docusaurus/types').DocusaurusConfig} */
 module.exports = {
@@ -101,7 +103,7 @@ module.exports = {
           // Please change this to your repo.
           editUrl:
             'https://github.com/crossplatform-dev/crossplatform.dev/edit/main/',
-          remarkPlugins: [interpolateData],
+          remarkPlugins: [importCode, partialContent, interpolateData],
         },
         // blog: {
         //   showReadingTime: true,

package-lock.json

@@ -53,6 +53,7 @@
     "markdownlint-cli": "^0.28.1",
     "pluralize": "^8.0.0",
     "prettier": "^2.3.2",
-    "semver": "^7.3.5"
+    "semver": "^7.3.5",
+    "unist-util-visit-children": "^1.1.4"
   }
 }

package.json

@@ -0,0 +1,57 @@
+// Initial code from https://github.com/unlight/remark-sources/blob/8b4ca174d276c2b66ae98c817f87f9ab3fc1b3a5/index.js
+// Licensed under MIT
+
+const fs = require('fs').promises;
+const { resolve } = require('path');
+
+const visitChildren = require('unist-util-visit-children');
+
+const regExp = new RegExp(/^[^\(]*\(([^\)]+)\)$/);
+
+const replace = async (node, filePath) => {
+  try {
+    const content = await fs.readFile(filePath, { encoding: 'utf-8' });
+    if (content !== undefined) {
+      node.value = content.trim();
+
+      return true;
+    }
+  } catch (e) {
+    node.value = `Failed to read file: ${filePath}`;
+
+    return false;
+  }
+};
+
+/**
+ * Replaces all the codeblock instances on a markdown document that point
+ * to a file with the contents of that file.
+ */
+const attacher = () => {
+  const transformer = async (tree, file) => {
+    const replacements = [];
+
+    const visitor = visitChildren((node) => {
+      if (node && node.type === 'code' && node.meta) {
+        const filePath = (regExp.exec(node.meta) || [])[1];
+
+        // Regular codeblock with no information between parenthesis
+        if (!filePath) {
+          return;
+        }
+
+        const absPath = resolve(file.dirname, filePath);
+
+        replacements.push(replace(node, absPath));
+      }
+    });
+
+    visitor(tree);
+
+    await Promise.all(replacements);
+  };
+
+  return transformer;
+};
+
+module.exports = attacher;

src/transformers/import-code.js

@@ -0,0 +1,77 @@
+// Initial code from https://github.com/unlight/remark-sources/blob/8b4ca174d276c2b66ae98c817f87f9ab3fc1b3a5/index.js
+// Licensed under MIT
+
+const fs = require('fs').promises;
+const { resolve } = require('path');
+
+const unified = require('unified');
+const visitChildren = require('unist-util-visit-children');
+const toMDAST = require('remark-parse');
+const vfile = require('vfile');
+const importCode = require('./import-code');
+
+const regExp = /{@import (.*?\.pmd)}/;
+const processor = unified().use(toMDAST).use(importCode);
+
+const replace = async (node, filePath) => {
+  try {
+    const content = await fs.readFile(filePath, { encoding: 'utf-8' });
+    if (content !== undefined) {
+      const file = vfile({
+        path: filePath,
+        contents: content,
+      });
+
+      const partialTree = processor.parse(file);
+      const doc = await processor.run(partialTree, file);
+
+      node.children = doc.children;
+    }
+  } catch (e) {
+    node.children[0].value = `Failed to read file: ${filePath}`;
+  }
+};
+
+/**
+ * This is a unified plugin that Transforms all the instances
+ * of `{@import ./relative/path.pmd}` with the contents of
+ * `./relative/path.pmd`, which has to be a regular markdown file.
+ *
+ * Additionally, it also uses the plugin import-code in this same
+ * repository.
+ */
+const attacher = () => {
+
+  const transformer = async (tree, file) => {
+    const replacements = [];
+
+    const visit = visitChildren((node) => {
+      if (!node || node.type !== 'paragraph') {
+        return;
+      }
+
+      if (!node.children[0] || node.children[0].type !== 'text') {
+        return;
+      }
+
+      const filePath = (regExp.exec(node.children[0].value) || [])[1];
+
+      // No import statement in the paragraph
+      if (!filePath) {
+        return;
+      }
+
+      const absPath = resolve(file.dirname, filePath);
+
+      replacements.push(replace(node, absPath))
+    });
+
+    visit(tree);
+
+    await Promise.all(replacements);
+  };
+
+  return transformer;
+};
+
+module.exports = attacher;