Skip to content

Commit 12b92a6

Browse files
fcanovaileonardocearmru
authored
docs: autoselect version (#344)
Define functions that can be used in mdx pages to dinamically choose the correct version according to the documentation page viewed. Closes #343 Signed-off-by: Francesco Canovai <[email protected]> Signed-off-by: Leonardo Cecchi <[email protected]> Signed-off-by: Armando Ruocco <[email protected]> Co-authored-by: Leonardo Cecchi <[email protected]> Co-authored-by: Armando Ruocco <[email protected]>
1 parent 612064b commit 12b92a6

File tree

9 files changed

+126
-87
lines changed

9 files changed

+126
-87
lines changed

web/docs/installation.md renamed to web/docs/installation.mdx

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@ sidebar_position: 20
44

55
# Installation
66

7-
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
8-
97
:::important
108
1. The plugin **must** be installed in the same namespace as the CloudNativePG
119
operator (typically `cnpg-system`).
@@ -56,17 +54,12 @@ Both checks are required before proceeding with the installation.
5654

5755
## Installing the Barman Cloud Plugin
5856

57+
import { InstallationSnippet } from '@site/src/components/Installation';
58+
5959
Install the plugin using `kubectl` by applying the manifest for the latest
6060
release:
6161

62-
<!-- x-release-please-start-version -->
63-
64-
```sh
65-
kubectl apply -f \
66-
https://github.com/cloudnative-pg/plugin-barman-cloud/releases/download/v0.4.0/manifest.yaml
67-
```
68-
69-
<!-- x-release-please-end -->
62+
<InstallationSnippet />
7063

7164
Example output:
7265

@@ -114,4 +107,3 @@ following command:
114107
kubectl apply -f \
115108
https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/refs/heads/main/manifest.yaml
116109
```
117-

‎web/docs/migration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ If you're currently relying on the built-in Barman Cloud integration, you can
1313
migrate seamlessly to the new **plugin-based architecture** using the Barman
1414
Cloud Plugin, with **no downtime**. Follow these steps:
1515

16-
- [Install the Barman Cloud Plugin](installation.md)
16+
- [Install the Barman Cloud Plugin](installation.mdx)
1717
- Create an `ObjectStore` resource by translating the contents of the
1818
`.spec.backup.barmanObjectStore` section from your existing `Cluster`
1919
definition

‎web/docs/usage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ sidebar_position: 30
66

77
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
88

9-
After [installing the plugin](installation.md) in the same namespace as the
9+
After [installing the plugin](installation.mdx) in the same namespace as the
1010
CloudNativePG operator, enabling your PostgreSQL cluster to use the Barman
1111
Cloud Plugin involves just a few steps:
1212

‎web/src/components/HomepageFeatures/feature.tsx‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import type {ComponentProps, ComponentType, ReactElement} from "react";
2+
import clsx from "clsx";
3+
import styles from "@site/src/components/HomepageFeatures/styles.module.css";
4+
import Heading from "@theme/Heading";
5+
6+
type FeatureItem = {
7+
title: string;
8+
Svg: ComponentType<ComponentProps<'svg'>>;
9+
description: string;
10+
};
11+
12+
function Feature({title, Svg, description}: FeatureItem): ReactElement<FeatureItem> {
13+
return (
14+
<div className={clsx('col col--4')}>
15+
<div className="text--center">
16+
<Svg className={styles.featureSvg} role="img"/>
17+
</div>
18+
<div className="text--center padding-horiz--md">
19+
<Heading as="h3">{title}</Heading>
20+
<p>{description}</p>
21+
</div>
22+
</div>
23+
);
24+
}
25+
26+
export function FeatureList(): ReactElement<null> {
27+
return (
28+
<div className="row">
29+
<Feature
30+
title={'Backup your clusters'}
31+
description={"Securely backup your CloudNativePG clusters to object storage with configurable retention " +
32+
"policies and compression options"}
33+
Svg={require('@site/static/img/undraw_going-up_g8av.svg').default}
34+
35+
/>
36+
<Feature
37+
title={'Restore to any point in time'}
38+
description={"Perform flexible restores to any point in time using a combination of " +
39+
"base backups and WAL archives."}
40+
Svg={require('@site/static/img/undraw_season-change_ohe6.svg').default}
41+
/>
42+
<Feature
43+
title={'Cloud-native architecture'}
44+
description={"Seamlessly integrate with all major cloud providers and on-premises object storage solutions."}
45+
Svg={require('@site/static/img/undraw_maintenance_rjtm.svg').default}
46+
/>
47+
</div>
48+
)
49+
}

‎web/src/components/HomepageFeatures/index.tsx‎

Lines changed: 11 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,13 @@
1-
import type {ReactNode} from 'react';
2-
import clsx from 'clsx';
3-
import Heading from '@theme/Heading';
1+
import type {ReactElement} from 'react';
42
import styles from './styles.module.css';
5-
6-
type FeatureItem = {
7-
title: string;
8-
Svg: React.ComponentType<React.ComponentProps<'svg'>>;
9-
description: ReactNode;
10-
};
11-
12-
const FeatureList: FeatureItem[] = [
13-
{
14-
title: 'Backup your clusters',
15-
Svg: require('@site/static/img/undraw_going-up_g8av.svg').default,
16-
description: (
17-
<>
18-
Securely backup your CloudNativePG clusters to object storage with
19-
configurable retention policies and compression options.
20-
</>
21-
),
22-
},
23-
{
24-
title: 'Restore to any point in time',
25-
Svg: require('@site/static/img/undraw_season-change_ohe6.svg').default,
26-
description: (
27-
<>
28-
Perform flexible restores to any point in time using a combination of
29-
base backups and WAL archives.
30-
</>
31-
),
32-
},
33-
{
34-
title: 'Cloud-native architecture',
35-
Svg: require('@site/static/img/undraw_maintenance_rjtm.svg').default,
36-
description: (
37-
<>
38-
Seamlessly integrate with all major cloud providers and on-premises object storage
39-
solutions.
40-
</>
41-
),
42-
},
43-
];
44-
45-
function Feature({title, Svg, description}: FeatureItem) {
46-
return (
47-
<div className={clsx('col col--4')}>
48-
<div className="text--center">
49-
<Svg className={styles.featureSvg} role="img" />
50-
</div>
51-
<div className="text--center padding-horiz--md">
52-
<Heading as="h3">{title}</Heading>
53-
<p>{description}</p>
54-
</div>
55-
</div>
56-
);
57-
}
58-
59-
export default function HomepageFeatures(): ReactNode {
60-
return (
61-
<section className={styles.features}>
62-
<div className="container">
63-
<div className="row">
64-
{FeatureList.map((props, idx) => (
65-
<Feature key={idx} {...props} />
66-
))}
67-
</div>
68-
</div>
69-
</section>
70-
);
3+
import {FeatureList} from './feature';
4+
5+
export default function HomepageFeatures(): ReactElement<null> {
6+
return (
7+
<section className={styles.features}>
8+
<div className="container">
9+
<FeatureList/>
10+
</div>
11+
</section>
12+
);
7113
}

‎web/src/components/Installation/index.tsx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import {ReactElement} from 'react';
2+
import CodeBlock from '@theme/CodeBlock';
3+
import {useCurrentVersion} from '@site/src/hooks/versions';
4+
5+
// InstallationSnippet is the kubectl incantation to install the lastest
6+
// available version of the Barman Cloud Plugin.
7+
export function InstallationSnippet(): ReactElement<null> {
8+
const latest = useCurrentVersion('latestReleased');
9+
return (
10+
<CodeBlock language="sh">
11+
{`kubectl apply -f \\
12+
https://github.com/cloudnative-pg/plugin-barman-cloud/releases/download/v${latest}/manifest.yaml`}
13+
</CodeBlock>
14+
);
15+
}
16+

‎web/src/hooks/versions.ts‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import {useActiveVersion, useLatestVersion, useVersions} from '@docusaurus/plugin-content-docs/client';
2+
3+
4+
export function useCurrentVersion(fallback: 'latest' | 'latestReleased' = 'latest'): string {
5+
switch (fallback) {
6+
case 'latestReleased':
7+
return useLatestReleasedVersion();
8+
case 'latest': {
9+
const version = useActiveVersion('default');
10+
return version?.name ?? useLatestVersion('default')?.name;
11+
}
12+
default:
13+
// The following line ensures that if `fallback` is not 'latest' or 'latestReleased',
14+
// an error is thrown. This can be useful for catching unexpected states.
15+
throw new Error(`Unhandled fallback type: ${fallback}`);
16+
}
17+
}
18+
19+
export function useLatestReleasedVersion(): string {
20+
const allVersions = useVersions('default');
21+
22+
// Filter out "current" to only consider versioned docs
23+
const versionedDocs = allVersions.filter(version => version.name !== 'current');
24+
25+
// Handle the case where no versioned documents are found
26+
if (versionedDocs.length === 0) {
27+
return "unknown_version";
28+
}
29+
30+
const sortedVersions = versionedDocs.sort((a, b) => {
31+
return b.name.localeCompare(a.name, undefined, { numeric: true, sensitivity: 'base' });
32+
});
33+
34+
// The latest version is the first in the sorted list since versionedDocs was not empty,
35+
return sortedVersions[0].name;
36+
}

‎web/src/pages/index.tsx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type {ReactNode} from 'react';
1+
import type {ReactElement, ReactNode} from 'react';
22
import clsx from 'clsx';
33
import Link from '@docusaurus/Link';
44
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
@@ -8,7 +8,7 @@ import Heading from '@theme/Heading';
88

99
import styles from './index.module.css';
1010

11-
function HomepageHeader() {
11+
function HomepageHeader(): ReactElement<null> {
1212
const { siteConfig } = useDocusaurusContext();
1313
return (
1414
<header className={clsx('hero hero--primary', styles.heroBanner)}>
@@ -21,7 +21,7 @@ function HomepageHeader() {
2121
);
2222
}
2323

24-
export default function Home(): ReactNode {
24+
export default function Home(): ReactElement<null> {
2525
const {siteConfig} = useDocusaurusContext();
2626
return (
2727
<Layout

‎web/tsconfig.json‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22
// This file is not used in compilation. It is here just for a nice editor experience.
33
"extends": "@docusaurus/tsconfig",
44
"compilerOptions": {
5-
"baseUrl": "."
5+
"baseUrl": ".",
6+
"strict": true
67
},
7-
"exclude": [".docusaurus", "build"]
8+
"exclude": [
9+
".docusaurus",
10+
"build"
11+
]
812
}

0 commit comments

Comments
 (0)