docs: add PartialsComponent to handle Docusaurus Markdown Imports in …

…librarium DOC-1189 (#2887) * docs: add PartialsComponent to handle Docusaurus Markdown Imports in librarium DOC-1189 docs: prototype partials DOC-1159 docs: add comments to component docs: add partial categories docs: add partial categories docs: add frontmatter approach docs: add duplicate key validation docs: add generate-partials script docs: add more error handling docs: add generate-partials to build docs: add partials to npm run docs: adjust build with partials docs: demo docs: demo docs: done docs: done docs: done docs: add VersionedLink docs:add final version of partials importer DOC-1189 docs: fix formatting DOC-1189 docs: fix eslint docs: add kubernetes version downgrade warning and hello-universe pack version DOC-1165 DOC-1174 (#2786) * docs: add kubernetes version downgrade warning and hello-universe pack version DOC-1165 DOC-1174 This patch makes the following changes: - Adds Kubernetes downgrade warning to cluster update and Kubernetes packs - Adds version 1.1.2 to the hello-universe pack * docs: fix formatting * Apply suggestions from code review Co-authored-by: caroldelwing <carolina.delwing@spectrocloud.com> * docs: fix formatting * docs: fix broken table * docs: add warning to microk8s, k3s and rke2 --------- Co-authored-by: caroldelwing <carolina.delwing@spectrocloud.com> docs: 4.3 API Docs (#2807) Co-authored-by: Karl Cardenas <karl@spectrocloud.com> docs: update hardware-requirements.md (#2809) Co-authored-by: Karl Cardenas <karl@spectrocloud.com> docs: DOC-1150 deprecated packs clarification (#2682) * docs: DOC-1150 * chore: final touches * Apply suggestions from code review Co-authored-by: caroldelwing <carolina.delwing@spectrocloud.com> * chore: prettier --------- Co-authored-by: caroldelwing <carolina.delwing@spectrocloud.com> docs: DOC-1162 DOC-1078 DOC-1136 Rhel pxk fips (#2728) * docs: DOC-1162 * docs: fixed BYOOS issue * chore: updated table * docs: added BYOOS table * docs: FIPS draft-1 * docs: fips steps * docs: added non-fips workflow * Apply suggestions from code review Co-authored-by: Adelina Simion <43963729+addetz@users.noreply.github.com> * Optimised images with calibre/image-actions * Optimised images with calibre/image-actions * Optimised images with calibre/image-actions * docs: feedback * Optimised images with calibre/image-actions * Optimised images with calibre/image-actions * chore: update to URL --------- Co-authored-by: Adelina Simion <43963729+addetz@users.noreply.github.com> Co-authored-by: vault-token-factory-spectrocloud[bot] <133815545+vault-token-factory-spectrocloud[bot]@users.noreply.github.com> chore: fix tf code (#2830) docs: DOC-1166 image update (#2773) * docs: DOC-1166 image update * Optimised images with calibre/image-actions * Optimised images with calibre/image-actions * Optimised images with calibre/image-actions * Optimised images with calibre/image-actions * docs: language touch-up * Update docs/docs-content/architecture/orchestration-spectrocloud.md * Apply suggestions from code review Co-authored-by: caroldelwing <carolina.delwing@spectrocloud.com> * chore: updated language --------- Co-authored-by: vault-token-factory-spectrocloud[bot] <133815545+vault-token-factory-spectrocloud[bot]@users.noreply.github.com> Co-authored-by: caroldelwing <carolina.delwing@spectrocloud.com> docs: update crossplane provider version (#2837) chore: bump eslint-plugin-react from 7.33.2 to 7.34.1 (#2734) Bumps [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) from 7.33.2 to 7.34.1. - [Release notes](https://github.com/jsx-eslint/eslint-plugin-react/releases) - [Changelog](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/CHANGELOG.md) - [Commits](jsx-eslint/eslint-plugin-react@v7.33.2...v7.34.1) --- updated-dependencies: - dependency-name: eslint-plugin-react dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Lenny Chen <55669665+lennessyy@users.noreply.github.com> docs: DOC-1149 airgap Support VM custom SSL Certs (#2846) * docs: DOC-1149 * chore: updated SSL cert message * Apply suggestions from code review Co-authored-by: Yuliia Horbenko <31223054+yuliiiah@users.noreply.github.com> * chore: fix format * chore: fix typo --------- Co-authored-by: Yuliia Horbenko <31223054+yuliiiah@users.noreply.github.com> docs: cluster profile resource usage computation (#2802) * Cluster profile resource usage computation Every version of the profile has a unique identifier and gets counted towards the profile resource usage. * chore: style update * chore: fixed page location --------- Co-authored-by: Karl Cardenas <karl@spectrocloud.com> chore: bump @commitlint/cli from 17.8.1 to 19.3.0 (#2733) Bumps [@commitlint/cli](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/cli) from 17.8.1 to 19.3.0. - [Release notes](https://github.com/conventional-changelog/commitlint/releases) - [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/cli/CHANGELOG.md) - [Commits](https://github.com/conventional-changelog/commitlint/commits/v19.3.0/@commitlint/cli) --- updated-dependencies: - dependency-name: "@commitlint/cli" dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Lenny Chen <55669665+lennessyy@users.noreply.github.com> docs: rename local mgmt api (#2845) * docs: rename local mgmt api * docs: incorprate feedback --------- Co-authored-by: Lenny Chen <lenny.chen@spectrocloud.com> chore: bump @commitlint/config-conventional from 17.8.1 to 19.2.2 (#2735) * chore: bump @commitlint/config-conventional from 17.8.1 to 19.2.2 Bumps [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/config-conventional) from 17.8.1 to 19.2.2. - [Release notes](https://github.com/conventional-changelog/commitlint/releases) - [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/config-conventional/CHANGELOG.md) - [Commits](https://github.com/conventional-changelog/commitlint/commits/v19.2.2/@commitlint/config-conventional) --- updated-dependencies: - dependency-name: "@commitlint/config-conventional" dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> * resolve conflicts * Resolve conflicts --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Lenny Chen <55669665+lennessyy@users.noreply.github.com> Co-authored-by: Lenny Chen <lenny.chen@spectrocloud.com> docs: PAD-219 chore: update validator URL (#2875) docs: DOC-1188 (#2878) chore: fix path release date (#2880) docs: make minor fixes to local ui docs (#2854) * docs: make minor fixes to local ui docs * Update docs/docs-content/clusters/edge/edge-configuration/installer-reference.md Co-authored-by: Karl Cardenas <karl@spectrocloud.com> --------- Co-authored-by: Lenny Chen <lenny.chen@spectrocloud.com> Co-authored-by: Karl Cardenas <karl@spectrocloud.com> docs: change fix build branch (#2884) * docs: change fips build branch * docs: remove main --------- Co-authored-by: Lenny Chen <lenny.chen@spectrocloud.com> docs: make frontmatter anonymous class DOC-1189 docs: fix formatting docs: fix last lints ci: updated logic to enable Netlify previews for release branch PRs (#2888) docs: add readme instructions and extra tests DOC-1189 * docs: add partial example DOC-1189
spectrocloud · May 23, 2024 · 045b892 · 045b892
1 parent 9263541
commit 045b892
Show file tree

Hide file tree

Showing 18 changed files with 348 additions and 4 deletions.
diff --git a/.gitignore b/.gitignore
@@ -61,3 +61,6 @@ tests/screenshot.spec.ts-snapshots/
 test-results/
 playwright-report/
 artifact.zip
+
+# Ignore _partials/index.ts
+_partials/index.ts
diff --git a/Makefile b/Makefile
@@ -58,6 +58,7 @@ init: ## Initialize npm dependencies
 	npx husky install
 
 start: ## Start a local development server
+	make generate-partials
 	npm run start
 
 build: ## Run npm build
@@ -199,6 +200,11 @@ format-images: ## Format images
 	@echo "formatting images in /static/assets/docs/images/ folder"
 	./scripts/compress-convert-images.sh
 
+###@ Generate _partials/index.ts required to automatic partials usage.
+
+generate-partials: ## Generate
+	./scripts/generate-partials.sh
+
 ###@ Aloglia Indexing
 
 update-dev-index: ## Update the Algolia index for the dev environment

diff --git a/README.md b/README.md
@@ -530,6 +530,64 @@ scheme. The rows of cards are dynamically created according to the list of speci
 />
 ```
 
+## Partials Component
+
+This is a custom component that allows you to create and use
+[Import Markdown](https://docusaurus.io/docs/3.2.1/markdown-features/react#importing-markdown).
+
+Partials must be created under the `_partials` folder. They must be named using an `_` prefix and the `*.mdx` filetype.
+Partials may be organised in any further subfolders as required. For example, you could create
+`_partials/public-cloud/_palette_setup.mdx`.
+
+In order to aid with organisation and categorization, partials must have a `partial_category` and `partial_name` defined
+in their frontmatter:
+
+```mdx
+---
+partial_category: public-cloud
+partial_name: palette-setup
+---
+
+This is how you set up Palette in {props.cloud}.
+```
+
+Partials are customized using properties which can be read using the `{props.field}` syntax.
+
+Once your partial has been created, run the `make generate-partials` command to make your partial available for use.
+This command will also be invoked during the `make start` and `make build` commands.
+
+Finally, you can reference your partial in any `*.md` file by using the `PartialsComponent`, together with the specified
+category and name of the partial:
+
+```md
+<PartialsComponent
+  category="public-cloud"
+  name="palette-setup"
+  cloud="AWS"
+/>
+```
+
+Note that the `cloud` field corresponds to the `{props.cloud}` reference in the `*.mdx` file.
+
+### Internal Links
+
+Due to the complexities of Docusaurus plugin rendering, links do not support versioning in `*.mdx` files. If you want to
+add an internal link you will have to use the `VersionedLink` component inside the `*.mdx` file.
+
+```mdx
+---
+partial_category: public-cloud
+partial_name: palette-setup
+---
+
+This is how you set up Palette in {props.cloud}.
+
+This is an <VersionedLink name="Internal Link" url="/getting-started/additional-capabilities"/>.
+```
+
+The path of the link should be the path of the destination file from the root directory, without any back operators
+`..`. External links can be referenced as usual.
+
 ## Netlify Previews
 
 By default Netlify previews are enabled for pull requests. However, some branches do not require Netlify previews. In

diff --git a/_partials/_partial_example.mdx b/_partials/_partial_example.mdx
@@ -0,0 +1,8 @@
+---
+partial_category: example-cat
+partial_name: example-name
+---
+
+This is an example partial with an example property. {props.message}
+
+Read more about how to use partials in our [README](https://github.com/spectrocloud/librarium/blob/master/README.md).
diff --git a/docs/docs-content/getting-started/getting-started.md b/docs/docs-content/getting-started/getting-started.md
@@ -33,7 +33,7 @@ The first step towards adopting Palette in your organization is to
 We have curated the pages in the Getting Started section to give you a gradual introduction to the fundamental concepts
 and workflows you need to deploy and manage Kubernetes clusters through Palette.
 
-<div class="desktop-only-display">
+<div className="desktop-only-display">
 
 ![Overview of the getting started journey rocket](/getting-started/getting-started_getting-started_journey-overview.webp)
 

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -7,6 +7,7 @@ const darkCodeTheme = themes.dracula;
 const redirects = require("./redirects");
 const { pluginPacksAndIntegrationsData } = require("./plugins/packs-integrations");
 const { pluginImportFontAwesomeIcons } = require("./plugins/font-awesome");
+import path from "path";
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -378,3 +379,13 @@ const config = {
     },
 };
 module.exports = config;
+
+export default function (context, options) {
+  return {
+    name: "@docusaurus/plugin-content-docs",
+    getPathsToWatch() {
+      const contentPath = path.resolve(context.siteDir, options.path);
+      return [`${contentPath}/_partials/*/*.{mdx}`];
+    },
+  };
+}
diff --git a/package.json b/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "start": "docusaurus start --host 0.0.0.0 --port 9000",
-    "build": "npm run generate-api-docs && docusaurus build",
+    "build": "npm run generate-api-docs && npm run generate-partials && docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
@@ -18,6 +18,7 @@
     "generate-api-docs": "npm run run-api-parser && docusaurus gen-api-docs palette",
     "clean-api-docs": "docusaurus clean-api-docs palette",
     "run-api-parser": "node utils/api-parser/index.js",
+    "generate-partials": "./scripts/generate-partials.sh",
     "lint": "eslint . --ext .js,.ts,.jsx,.tsx",
     "lint:fix": "npm run lint -- --fix",
     "format": "prettier --write \"**/*.{js,jsx,json,ts,tsx,md,mdx,css}\"",

diff --git a/scripts/generate-partials.sh b/scripts/generate-partials.sh
@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# Enable error handling
+set -e
+
+echo "Starting generation of _partials/index.ts."
+
+# # Remove the index.ts file if it exists already.
+rm -f _partials/index.ts
+
+# Make the _partials folder an index.ts file
+mkdir -p _partials
+touch _partials/index.ts
+
+# Create the file and add the generated warning.
+echo "// This file is generated. DO NOT EDIT!" >> _partials/index.ts
+
+# Find all the MDX files recursively in the _partials folder.
+# Loop through each file.
+find _partials -name "*.mdx" -print0 | while read -d $'\0' path
+do
+    module_name=$(basename ${path} .mdx | tr -d '_' | tr -d '-')
+    echo "export * as ${module_name}${RANDOM} from '@site/${path}';" >> _partials/index.ts
+done
+
+echo "Completed generation of _partials/index.ts."
diff --git a/src/components/PartialsComponent/PartialsComponent.test.tsx b/src/components/PartialsComponent/PartialsComponent.test.tsx
@@ -0,0 +1,41 @@
+import React, { FunctionComponent } from "react";
+import { render, screen } from "@testing-library/react";
+
+let category = "testCat1";
+let name = "nameCat1";
+let propValue = "testValue1";
+
+const Partial: React.FunctionComponent<{}> = ({}) => (
+  <div>
+    <p>{category}</p>
+    <p>{name}</p>
+    <p>{propValue}</p>
+  </div>
+);
+
+jest.mock("./PartialsImporter", () => {
+  return jest.fn(() => {
+    const mapKey = category.concat("#").concat(name);
+    const pmap: PartialsMap = {};
+    pmap[mapKey] = Partial as FunctionComponent;
+    return pmap;
+  });
+});
+
+import PartialsComponent from "./PartialsComponent";
+import { PartialsMap } from "./PartialsImporter";
+
+describe("Partials Component", () => {
+  it("partial exists", () => {
+    render(<PartialsComponent category={category} name={name} propTest={propValue} />);
+    expect(screen.getByText(category)).toBeInTheDocument();
+    expect(screen.getByText(name)).toBeInTheDocument();
+    expect(screen.getByText(propValue)).toBeInTheDocument();
+  });
+
+  it("partial does not exist", () => {
+    expect(() => render(<PartialsComponent category="unknownCat" name="unknownName" propTest={propValue} />)).toThrow(
+      "No partial found for name unknownName in category unknownCat."
+    );
+  });
+});
diff --git a/src/components/PartialsComponent/PartialsComponent.tsx b/src/components/PartialsComponent/PartialsComponent.tsx
@@ -0,0 +1,30 @@
+import React from "react";
+import ImportPartials from "./PartialsImporter";
+
+interface ComponentProperties {
+  [key: string]: string;
+}
+
+const AllPartials = ImportPartials();
+
+export default function PartialsComponent(details: ComponentProperties): React.ReactElement {
+  const mapKey = details.category.concat("#").concat(details.name);
+
+  if (!AllPartials[mapKey]) {
+    throw new Error(
+      "No partial found for name ".concat(details.name).concat(" in category ").concat(details.category).concat(".")
+    );
+  }
+
+  // Map elements to object properties
+  const propAttribute: { [key: string]: string } = {};
+  for (const key in details) {
+    // Don't send category and name to the partial
+    if (key == "category" || key == "name") {
+      continue;
+    }
+    propAttribute[key] = details[key];
+  }
+
+  return React.createElement(AllPartials[mapKey], propAttribute);
+}
diff --git a/src/components/PartialsComponent/PartialsImporter.tsx b/src/components/PartialsComponent/PartialsImporter.tsx
@@ -0,0 +1,51 @@
+import { FunctionComponent } from "react";
+// Import all the partials as one module.
+import * as PartialModules from "@site/_partials";
+
+export interface PartialsMap {
+  [key: string]: FunctionComponent;
+}
+
+interface Modules {
+  [key: string]: Module;
+}
+
+interface Module {
+  frontMatter: {
+    partial_category: string;
+    partial_name: string;
+  };
+  default: FunctionComponent;
+}
+
+export default function ImportPartials(): PartialsMap {
+  const pmap: PartialsMap = {};
+  const allPartialModules: Modules = PartialModules;
+
+  // The keys are the names of each exported module in _partials/index.ts
+  const partialKeys: string[] = Object.keys(allPartialModules);
+  partialKeys.map(function (pkey) {
+    const currentPartial: Module = allPartialModules[pkey];
+    const catFrontMatter = currentPartial.frontMatter.partial_category;
+    const nameFrontMatter = currentPartial.frontMatter.partial_name;
+
+    if (!catFrontMatter || !nameFrontMatter) {
+      throw new Error("Please specify partial_category and partial_name for ".concat(pkey).concat("."));
+    }
+
+    const mapKey = catFrontMatter.concat("#").concat(nameFrontMatter);
+    if (pmap[mapKey]) {
+      throw new Error(
+        "Duplicate partial defined for name "
+          .concat(nameFrontMatter)
+          .concat(" in category ")
+          .concat(catFrontMatter)
+          .concat(".")
+      );
+    }
+
+    pmap[mapKey] = currentPartial.default;
+  });
+
+  return pmap;
+}
diff --git a/src/components/PartialsComponent/index.ts b/src/components/PartialsComponent/index.ts
@@ -0,0 +1,3 @@
+import PartialsComponent from "./PartialsComponent";
+
+export default PartialsComponent;
diff --git a/src/components/VersionedLink/CheckVersion.tsx b/src/components/VersionedLink/CheckVersion.tsx
@@ -0,0 +1,14 @@
+import { useActivePluginAndVersion } from "@docusaurus/plugin-content-docs/client";
+
+export default function GetVersionPath() {
+  const activePlugin = useActivePluginAndVersion();
+  if (
+    activePlugin != undefined &&
+    activePlugin.activeVersion != undefined &&
+    activePlugin.activeVersion.name != "current"
+  ) {
+    return activePlugin.activeVersion.path;
+  }
+
+  return "";
+}
diff --git a/src/components/VersionedLink/VersionedLink.test.tsx b/src/components/VersionedLink/VersionedLink.test.tsx
@@ -0,0 +1,59 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import VersionedLink from "./VersionedLink";
+
+let prevVersionPath = "";
+jest.mock("./CheckVersion", () => {
+  return jest.fn(() => {
+    return prevVersionPath;
+  });
+});
+
+describe("Versioned link", () => {
+  it("latest version", () => {
+    prevVersionPath = "";
+    const text = "Test link";
+    const url = "/path/url";
+    render(<VersionedLink text={text} url={url} />);
+    const link = screen.getByText(text).getAttribute("href");
+    expect(link).not.toBeNull();
+    expect(link).toBe(url);
+  });
+
+  it("previous version", () => {
+    prevVersionPath = "/v4.3.1";
+    const text = "Test link";
+    const url = "/path/url";
+    render(<VersionedLink text={text} url={url} />);
+    const link = screen.getByText(text).getAttribute("href");
+    expect(link).not.toBeNull();
+    expect(link).toBe(prevVersionPath.concat(url));
+  });
+
+  it("url with back dots", () => {
+    prevVersionPath = "";
+    const text = "Test link";
+    const url = "../path/url";
+    expect(() => render(<VersionedLink text={text} url={url} />)).toThrow(
+      "Versioned links should provide the path of the destination URL from root, without any `./` or `..` references."
+    );
+  });
+
+  it("url with back relative reference", () => {
+    prevVersionPath = "";
+    const text = "Test link";
+    const url = "./path/url";
+    expect(() => render(<VersionedLink text={text} url={url} />)).toThrow(
+      "Versioned links should provide the path of the destination URL from root, without any `./` or `..` references."
+    );
+  });
+
+  it("url with external domain", () => {
+    prevVersionPath = "";
+    const text = "Test link";
+    const url = "https://google.com";
+    expect(() => render(<VersionedLink text={text} url={url} />)).toThrow(
+      "Versioned links should not be used for external URLs. Please use the default markdown syntax instead."
+    );
+  });
+});
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		import PartialsComponent from "./PartialsComponent";

		export default PartialsComponent;