diff --git a/contributing/single-sourcing-content.md b/contributing/single-sourcing-content.md index 2b8a82dfb81..537980ebdfb 100644 --- a/contributing/single-sourcing-content.md +++ b/contributing/single-sourcing-content.md @@ -132,94 +132,6 @@ $ dbt test --models [...] --defer --state path/to/artifacts ``` -## Using global variables - ---- - -Global variables can be configured for use throughout the docs. - -Using a global variable requires two steps: - -1. Set the variable in the `website/dbt-global-variables.js` file. -2. Use the **Var** component to add the global variable to a page. - -```jsx -// The dbtCore property is the identifier for the variable, -// while the name property is the value shown on the page. - -exports.dbtVariables = { - dbtCore: { - name: "dbt Core" - } -} -``` - -```markdown -// is converted to dbt Core - -You can install on the command line by using one of these recommended methods: -``` - -### Versioning global variables - -It is possible to version global variables as well. This creates the ability to show different variations of a string based off the current version a visitor has selected. - -To extend our `dbt-global-variables.js` file above, we can add a new variable: *note - these versions are not accurate and only shown for this example.* - -```jsx -// A new variable called dbtCloud is added below -// This variable includes a versions array -// "Sinter" will replace "dbt Cloud" for versions 0.21 or lower - -exports.dbtVariables = { - dbtCore: { - name: "dbt Core" - }, - dbtCloud: { - name: "dbt Cloud", - versions: [ - { - "name": "Sinter", - "version": "0.21" - } - ] - } -} -``` - -```markdown -You can get started with by [Signing up](https://www.getdbt.com/signup/). -``` - -In the above example, the **dbtCloud** property has a default name of “dbt Cloud”. The naming for variables cascade down, meaning “dbt Cloud” will show for all versions, until version **0.21** or lower is selected. At that point “Sinter” will replace “dbt Cloud”. - -### Global variables properties - -**name** (required): Expects the identifier for a global variable. - -### Global variables example - -The global `` component can be used inline, for example: - -```markdown -This piece of markdown content explains why is awesome. -``` - -However, a Var component cannot start a new line of content. Fortunately, a workaround exists to use the Var component at the beginning of a line of content. - -To use the component at the beginning of a sentence, add a non-breaking space character before the component: - -```markdown -// When starting a new line with a global variable, -// a non-breaking space is required - -// Works -  is awesome! - -// Does not work - is awesome! -``` - ## Reusing content To reuse content on different pages, you can use some techniques like partial files or snippets. Partial files, a built-in Docusaurus feature, is the recommended method over snippets. diff --git a/website/dbt-global-variables.js b/website/dbt-global-variables.js deleted file mode 100644 index 8ee4499151e..00000000000 --- a/website/dbt-global-variables.js +++ /dev/null @@ -1,32 +0,0 @@ -/* - * Full Documentation at: - * https://www.notion.so/dbtlabs/Versioning-on-Docusaurus-c6a4a41a66cd4ea2970854cc42cb5b70#1803b9cb666442e5ac8885cf0bba321f - * - */ - -exports.dbtVariables = { - // Example global variable with versioning - // If version 0.21 or lower is selected - // "Old Example String" will replace "Example String" - exampleString: { - name: "Example String", - versions: [ - { - "name": "Old Example String", - "version": "0.21" - } - ] - }, - dbtTheProduct: { - name: "dbt" - }, - dbtCore: { - name: "dbt Core" - }, - dbtCloud: { - name: "dbt Cloud" - }, - dbtIDE: { - name: "dbt Cloud IDE" - }, -} diff --git a/website/dbt-versions.js b/website/dbt-versions.js index 871c3ce601e..60efef64f75 100644 --- a/website/dbt-versions.js +++ b/website/dbt-versions.js @@ -2,15 +2,15 @@ * Sets the available dbt versions available in the navigation * @type {Array.<{ * version: string, - * EOLDate: string, - * isPrerelease: boolean, + * EOLDate: string, + * isPrerelease: boolean, * customDisplay: string, * }>} * @property {string} version The version number * @property {string} EOLDate "End of Life" date which is used to show the EOL banner * @property {boolean} isPrerelease Boolean used for showing the prerelease banner * @property {string} customDisplay Allows setting a custom display name for the current version - * + * * customDisplay for dbt Cloud should be a version ahead of latest dbt Core release (GA or beta). */ exports.versions = [ @@ -30,7 +30,7 @@ exports.versions = [ version: "1.6", EOLDate: "2024-07-31", }, -] +]; /** * Controls doc page visibility in the sidebar based on the current version @@ -43,146 +43,146 @@ exports.versions = [ */ exports.versionedPages = [ { - "page": "/reference/resource-configs/target_database", - "lastVersion": "1.8", + page: "reference/resource-configs/target_database", + lastVersion: "1.8", }, { - "page": "/reference/resource-configs/target_schema", - "lastVersion": "1.8", + page: "reference/resource-configs/target_schema", + lastVersion: "1.8", }, { - "page": "reference/global-configs/indirect-selection", - "firstVersion": "1.8", + page: "reference/global-configs/indirect-selection", + firstVersion: "1.8", }, { - "page": "reference/resource-configs/store_failures_as", - "firstVersion": "1.7", + page: "reference/resource-configs/store_failures_as", + firstVersion: "1.7", }, { - "page": "docs/build/build-metrics-intro", - "firstVersion": "1.6", + page: "docs/build/build-metrics-intro", + firstVersion: "1.6", }, { - "page": "docs/build/sl-getting-started", - "firstVersion": "1.6", + page: "docs/build/sl-getting-started", + firstVersion: "1.6", }, { - "page": "docs/build/about-metricflow", - "firstVersion": "1.6", + page: "docs/build/about-metricflow", + firstVersion: "1.6", }, { - "page": "docs/build/join-logic", - "firstVersion": "1.6", + page: "docs/build/join-logic", + firstVersion: "1.6", }, { - "page": "docs/build/validation", - "firstVersion": "1.6", + page: "docs/build/validation", + firstVersion: "1.6", }, { - "page": "docs/build/semantic-models", - "firstVersion": "1.6", + page: "docs/build/semantic-models", + firstVersion: "1.6", }, { - "page": "docs/build/group-by", - "firstVersion": "1.6", + page: "docs/build/group-by", + firstVersion: "1.6", }, { - "page": "docs/build/entities", - "firstVersion": "1.6", + page: "docs/build/entities", + firstVersion: "1.6", }, { - "page": "docs/build/metrics-overview", - "firstVersion": "1.6", + page: "docs/build/metrics-overview", + firstVersion: "1.6", }, { - "page": "docs/build/cumulative", - "firstVersion": "1.6", + page: "docs/build/cumulative", + firstVersion: "1.6", }, { - "page": "docs/build/derived", - "firstVersion": "1.6", + page: "docs/build/derived", + firstVersion: "1.6", }, { - "page": "docs/build/measure-proxy", - "firstVersion": "1.6", + page: "docs/build/measure-proxy", + firstVersion: "1.6", }, { - "page": "docs/build/ratio", - "firstVersion": "1.6", + page: "docs/build/ratio", + firstVersion: "1.6", }, { - "page": "reference/commands/clone", - "firstVersion": "1.6", + page: "reference/commands/clone", + firstVersion: "1.6", }, { - "page": "docs/collaborate/govern/project-dependencies", - "firstVersion": "1.6", + page: "docs/collaborate/govern/project-dependencies", + firstVersion: "1.6", }, { - "page": "reference/dbt-jinja-functions/thread_id", - "firstVersion": "1.6", + page: "reference/dbt-jinja-functions/thread_id", + firstVersion: "1.6", }, { - "page": "reference/resource-properties/deprecation_date", - "firstVersion": "1.6", + page: "reference/resource-properties/deprecation_date", + firstVersion: "1.6", }, { - "page": "reference/commands/retry", - "firstVersion": "1.6", + page: "reference/commands/retry", + firstVersion: "1.6", }, { - "page": "docs/build/groups", - "firstVersion": "1.5", + page: "docs/build/groups", + firstVersion: "1.5", }, { - "page": "docs/collaborate/govern/model-contracts", - "firstVersion": "1.5", + page: "docs/collaborate/govern/model-contracts", + firstVersion: "1.5", }, { - "page": "reference/commands/show", - "firstVersion": "1.5", + page: "reference/commands/show", + firstVersion: "1.5", }, { - "page": "docs/collaborate/govern/model-access", - "firstVersion": "1.5", + page: "docs/collaborate/govern/model-access", + firstVersion: "1.5", }, { - "page": "docs/collaborate/govern/model-versions", - "firstVersion": "1.5", + page: "docs/collaborate/govern/model-versions", + firstVersion: "1.5", }, { - "page": "reference/programmatic-invocations", - "firstVersion": "1.5", + page: "reference/programmatic-invocations", + firstVersion: "1.5", }, { - "page": "reference/resource-configs/contract", - "firstVersion": "1.5", + page: "reference/resource-configs/contract", + firstVersion: "1.5", }, { - "page": "reference/resource-configs/group", - "firstVersion": "1.5", + page: "reference/resource-configs/group", + firstVersion: "1.5", }, { - "page": "reference/resource-properties/access", - "firstVersion": "1.5", + page: "reference/resource-properties/access", + firstVersion: "1.5", }, { - "page": "reference/resource-properties/constraints", - "firstVersion": "1.5", + page: "reference/resource-properties/constraints", + firstVersion: "1.5", }, { - "page": "reference/resource-properties/latest_version", - "firstVersion": "1.5", + page: "reference/resource-properties/latest_version", + firstVersion: "1.5", }, { - "page": "reference/resource-properties/versions", - "firstVersion": "1.5", + page: "reference/resource-properties/versions", + firstVersion: "1.5", }, { - "page": "reference/resource-configs/on_configuration_change", - "firstVersion": "1.6", - } -] + page: "reference/resource-configs/on_configuration_change", + firstVersion: "1.6", + }, +]; /** * Controls doc category visibility in the sidebar based on the current version @@ -195,11 +195,11 @@ exports.versionedPages = [ */ exports.versionedCategories = [ { - "category": "Model governance", - "firstVersion": "1.5", + category: "Model governance", + firstVersion: "1.5", }, { - "category": "Build your metrics", - "firstVersion": "1.6", - } -] + category: "Build your metrics", + firstVersion: "1.6", + }, +]; diff --git a/website/src/components/variable/index.js b/website/src/components/variable/index.js deleted file mode 100644 index 444f3203327..00000000000 --- a/website/src/components/variable/index.js +++ /dev/null @@ -1,45 +0,0 @@ -import React, { useState, useEffect, useContext } from 'react' -import { dbtVariables } from '../../../dbt-global-variables'; -import VersionContext from '../../stores/VersionContext'; - -export default function Var({ name }) { - if(!name) - return null - - const [variableName, setVariableName] = useState('') - - const { version } = useContext(VersionContext) - - const currentVariable = dbtVariables[name] - if(!currentVariable) - return null - - useEffect(() => { - if(currentVariable?.versions?.length && version) { - {/* - * If versions set for variable - * show correct variable name for current version - * - * Sort by lowest version first - * If this version is greater or equal to the active version - * Show this variable name - * If no match is found, show original variable name - * - */} - const thisVersionVariable = currentVariable.versions - .sort((item1, item2) => (parseFloat(item1.version) > parseFloat(item2.version)) ? 1 : -1) - .find(varVersion => - parseFloat(varVersion.version) >= parseFloat(version) ? true : false - ) - - !thisVersionVariable - ? setVariableName(currentVariable.name) - : setVariableName(thisVersionVariable.name) - - } else { - setVariableName(currentVariable.name) - } - }, [version]) - - return { variableName } -} diff --git a/website/src/components/versionBlock/index.js b/website/src/components/versionBlock/index.js index 01d6381c0e1..f7982d6eacf 100644 --- a/website/src/components/versionBlock/index.js +++ b/website/src/components/versionBlock/index.js @@ -1,39 +1,25 @@ import React, { useState, useEffect, useContext } from 'react' import VersionContext from '../../stores/VersionContext'; +import { availableInCurrentVersion } from '../../utils/available-in-current-version'; -export default function VersionBlock({ firstVersion = 0, lastVersion = undefined, children }) { - const { version } = useContext(VersionContext) +export default function VersionBlock({ firstVersion = "0", lastVersion = undefined, children }) { + const { version } = useContext(VersionContext); - const [loading, setLoading] = useState(true) + const [loading, setLoading] = useState(true); // Hide versionBlock components until version ready useEffect(() => { - version && setLoading(false) - }, [version]) + version && setLoading(false); + }, [version]); // Only check version if current version set - if(version) { - const currentVersionVal = parseFloat(version) - const firstVersionVal = parseFloat(firstVersion) - {/* - * If last version set, check if current version greater than last version - * Or if current version less than first version - * If either is true, hide block - * Else, if current version less than first version, hide block - */} - if(lastVersion) { - if((currentVersionVal > parseFloat(lastVersion)) - || (currentVersionVal < firstVersionVal)) - return null - } else { - if(currentVersionVal < firstVersionVal) { - return null - } - - } + if (version) { + if (!availableInCurrentVersion( + version, + firstVersion, + lastVersion + )) return null; } - return loading - ? null - : <>{children} + return loading ? null : <>{children}; } diff --git a/website/src/theme/DocRoot/Layout/Main/index.js b/website/src/theme/DocRoot/Layout/Main/index.js index 458cb9d8716..da6e29265bb 100644 --- a/website/src/theme/DocRoot/Layout/Main/index.js +++ b/website/src/theme/DocRoot/Layout/Main/index.js @@ -43,11 +43,14 @@ export default function DocRootLayoutMain({ latestStableRelease, } = useContext(VersionContext); - const { pageAvailable, firstAvailableVersion } = pageVersionCheck( - dbtVersion, - versionedPages, - currentDocRoute - ); + const { + pageAvailable, + firstAvailableVersion, + lastAvailableVersion + } = pageVersionCheck(dbtVersion, versionedPages, currentDocRoute); + + const hasFirstAvailableVersion = + firstAvailableVersion && firstAvailableVersion !== "0"; // Check whether this version is a isPrerelease, and show banner if so const [PreData, setPreData] = useState({ @@ -116,21 +119,34 @@ export default function DocRootLayoutMain({ hiddenSidebarContainer && styles.docItemWrapperEnhanced )} > - {!pageAvailable && dbtVersion && firstAvailableVersion && ( -
- -

- Unfortunately, this feature is not available in dbt Core version{" "} - {dbtVersion} -

-

- {" "} - You should upgrade to {firstAvailableVersion} or later if you - want to use this feature. -

- -
- )} + {!pageAvailable && + dbtVersion && ( +
+ +

+ Unfortunately, this feature is not available in dbt Core + version {dbtVersion} +

+ {hasFirstAvailableVersion ? ( +

+ {" "} + You should upgrade to {firstAvailableVersion} or later if + you want to use this feature. +

+ ) : null} + +
+ )} {PreData.showisPrereleaseBanner && (
diff --git a/website/src/theme/MDXComponents/index.js b/website/src/theme/MDXComponents/index.js index 66ab70a0167..d136222a0ce 100644 --- a/website/src/theme/MDXComponents/index.js +++ b/website/src/theme/MDXComponents/index.js @@ -27,7 +27,6 @@ import Snippet from '@site/src/components/snippet'; import YoutubeVideo from '@site/src/components/youtube'; import WistiaVideo from '@site/src/components/wistia'; import VersionBlock from '@site/src/components/versionBlock'; -import Var from '@site/src/components/variable'; import Term from '@site/src/components/term'; import EventsFeed from '@site/src/components/events'; import { DiscourseFeed, DiscourseHelpFeed } from '@site/src/components/discourse'; @@ -84,7 +83,6 @@ const MDXComponents = { WHCode: WHCode, YoutubeVideo: YoutubeVideo, VersionBlock: VersionBlock, - Var: Var, Term: Term, EventsFeed: EventsFeed, DiscourseFeed: DiscourseFeed, diff --git a/website/src/utils/available-in-current-version.js b/website/src/utils/available-in-current-version.js new file mode 100644 index 00000000000..e7b303e2370 --- /dev/null +++ b/website/src/utils/available-in-current-version.js @@ -0,0 +1,39 @@ +import { sortVersions } from "./sort-versions"; + +export const availableInCurrentVersion = ( + currentVersion, + firstVersion = "0", + lastVersion = undefined +) => { + // Get versions sorted from earliest to latest + const sortedVersions = sortVersions([ + currentVersion, + firstVersion, + ...(lastVersion ? [lastVersion] : []), + ]); + // Get index of current version, and first/last version props passed into component + const currentVersionIndex = sortedVersions?.indexOf(currentVersion); + const firstVersionIndex = sortedVersions?.indexOf(firstVersion); + const lastVersionIndex = sortedVersions?.indexOf(lastVersion); + { + /* + * If last version set, check if current version greater than last version + * Or if current version less than first version + * If either is true, hide block + * Else, if current version less than first version, hide block + */ + } + if (lastVersionIndex >= 0) { + if ( + currentVersionIndex > lastVersionIndex || + currentVersionIndex < firstVersionIndex + ) + return false; + } else { + if (currentVersionIndex < firstVersionIndex) { + return false; + } + } + + return true +} diff --git a/website/src/utils/category-version-check.js b/website/src/utils/category-version-check.js index bf75853cd8a..f4f263a1115 100644 --- a/website/src/utils/category-version-check.js +++ b/website/src/utils/category-version-check.js @@ -1,3 +1,5 @@ +import { availableInCurrentVersion } from "./available-in-current-version"; + export default function categoryVersionCheck(version, versionedCategories, category) { let categoryAvailableObj = { categoryAvailable: true @@ -7,30 +9,17 @@ export default function categoryVersionCheck(version, versionedCategories, categ return categoryAvailableObj const itemFound = versionedCategories.find(vcategory => vcategory.category === category) - + if (itemFound) { - const { firstVersion, lastVersion } = itemFound - const currentVersionVal = parseFloat(version) - const firstVersionVal = parseFloat(firstVersion) || 0 - - categoryAvailableObj.firstAvailableVersion = firstVersion - - // Determine if category within version range - if (lastVersion) { - const lastVersionVal = parseFloat(lastVersion) - // If lastVersion set for category, - // check if current version is higher than lastVersion - // or if current version is less than firstVersion - // If true, remove category in sidebar - if (currentVersionVal > lastVersionVal || currentVersionVal < firstVersionVal) { - categoryAvailableObj.categoryAvailable = false - } - } else if (firstVersionVal > currentVersionVal) { - // If firstVersion is greater than currentVersion - // remove category from sidebar - categoryAvailableObj.categoryAvailable = false - } + + categoryAvailableObj.firstAvailableVersion = firstVersion || "0"; + + categoryAvailableObj.categoryAvailable = availableInCurrentVersion( + version, + firstVersion, + lastVersion + ); } return categoryAvailableObj diff --git a/website/src/utils/page-version-check.js b/website/src/utils/page-version-check.js index cc2611929af..6bb9a81a50a 100644 --- a/website/src/utils/page-version-check.js +++ b/website/src/utils/page-version-check.js @@ -1,3 +1,5 @@ +import { availableInCurrentVersion } from "./available-in-current-version"; + export default function pageVersionCheck(version, versionedPages, path) { let pageAvailableObj = { pageAvailable: true @@ -13,28 +15,15 @@ export default function pageVersionCheck(version, versionedPages, path) { const itemFound = versionedPages.find(vpage => vpage.page === updatedPath) if(itemFound) { - - const { firstVersion, lastVersion } = itemFound - const currentVersionVal = parseFloat(version) - const firstVersionVal = parseFloat(firstVersion) || 0 + const { firstVersion, lastVersion } = itemFound; - pageAvailableObj.firstAvailableVersion = firstVersion + pageAvailableObj.firstAvailableVersion = firstVersion || "0"; - // Determine if sidebar item within version range - if(lastVersion) { - const lastVersionVal = parseFloat(lastVersion) - // If lastVersion set for sidebar item, - // check if current version is higher than lastVersion - // or if current version is less than firstVersion - // If true, remove item in sidebar - if(currentVersionVal > lastVersionVal || currentVersionVal < firstVersionVal) { - pageAvailableObj.pageAvailable = false - } - } else if(firstVersionVal > currentVersionVal) { - // If firstVersion is greater than currentVersion - // remove item from sidebar - pageAvailableObj.pageAvailable = false - } + pageAvailableObj.pageAvailable = availableInCurrentVersion( + version, + firstVersion, + lastVersion + ); } return pageAvailableObj diff --git a/website/src/utils/sort-versions.js b/website/src/utils/sort-versions.js new file mode 100644 index 00000000000..6e049987306 --- /dev/null +++ b/website/src/utils/sort-versions.js @@ -0,0 +1,44 @@ +// Sorts versions from earliest to latest and returns array +// For example: 1.7 will sort ahead of 1.8 +// 1.9 will sort ahead of 1.9.1 & 1.10 + +export const sortVersions = (versionsArr) => { + if (!Array?.isArray(versionsArr) || versionsArr?.length <= 0) return null + + const sortedVersions = versionsArr?.sort(function (a, b) { + // When comparing a - b: + // A negative value indicates that a should come before b. + // A positive value indicates that a should come after b. + // Zero or NaN indicates that a and b are considered equal. + + // Split versions into arrays by decimal + // split into max 3 length array (major, minor, patch versions) + const aSegments = a?.split(".", 3); + const bSegments = b?.split(".", 3); + + // Store each version part in variable to help readability below + const aMajor = aSegments[0] || "0" + const bMajor = bSegments[0] || "0" + const aMinor = aSegments[1] || "0" + const bMinor = bSegments[1] || "0" + const aPatch = aSegments[2] || "0" + const bPatch = bSegments[2] || "0" + + // Sort by major version + if (aMajor - bMajor < 0) { return -1; } + if (aMajor - bMajor > 0) { return 1; } + + // Sort by minor version + if (aMinor - bMinor < 0) { return -1; } + if (aMinor - bMinor > 0) { return 1; } + + // Sort by patch version + if (aPatch - bPatch < 0) { return -1; } + if (aPatch - bPatch > 0) { return 1; } + + // If reached, a & b are equal + return 0 + }); + + return sortedVersions +}