From f473c183fa57f23bcebeeed767571b2b21a9c1e5 Mon Sep 17 00:00:00 2001 From: Chris Campbell Date: Tue, 26 Aug 2025 12:48:05 -0700 Subject: [PATCH 1/4] build: add postcss and postcss-rtlcss dependencies --- packages/docs-builder/package.json | 2 + pnpm-lock.yaml | 70 +++++++++++++++++++++--------- 2 files changed, 51 insertions(+), 21 deletions(-) diff --git a/packages/docs-builder/package.json b/packages/docs-builder/package.json index 5475b5b..dbb9d05 100644 --- a/packages/docs-builder/package.json +++ b/packages/docs-builder/package.json @@ -44,6 +44,8 @@ "lunr-languages": "^1.9.0", "mark.js": "^8.11.1", "marked": "^4.0.10", + "postcss": "^8.5.6", + "postcss-rtlcss": "^5.7.1", "ps-tree": "^1.2.0", "puppeteer": "^18.2.1", "rev-hash": "^3.0.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5fc9653..da1a0bf 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -45,7 +45,7 @@ importers: examples/sample-docs: devDependencies: '@climateinteractive/docs-builder': - specifier: ^1.0.0 + specifier: workspace:* version: link:../../packages/docs-builder packages/docs-builder: @@ -80,6 +80,12 @@ importers: marked: specifier: ^4.0.10 version: 4.0.18 + postcss: + specifier: ^8.5.6 + version: 8.5.6 + postcss-rtlcss: + specifier: ^5.7.1 + version: 5.7.1(postcss@8.5.6) ps-tree: specifier: ^1.2.0 version: 1.2.0 @@ -685,7 +691,7 @@ packages: dependencies: '@typescript-eslint/typescript-estree': 7.0.2(typescript@5.3.3) '@typescript-eslint/utils': 7.0.2(eslint@8.57.0)(typescript@5.3.3) - debug: 4.3.4 + debug: 4.4.1 eslint: 8.57.0 ts-api-utils: 1.2.1(typescript@5.3.3) typescript: 5.3.3 @@ -709,7 +715,7 @@ packages: dependencies: '@typescript-eslint/types': 7.0.2 '@typescript-eslint/visitor-keys': 7.0.2 - debug: 4.3.4 + debug: 4.4.1 globby: 11.1.0 is-glob: 4.0.3 minimatch: 9.0.3 @@ -1173,7 +1179,6 @@ packages: optional: true dependencies: ms: 2.1.3 - dev: false /deep-eql@4.1.3: resolution: {integrity: sha512-WaEtAOpRA1MQ0eohqZjpGD8zdI0Ovsm8mmFhaDN8dvDZzyoUMcYDnf5Y6iu7HTXxf8JDS23qWa4a+hKCDyOPzw==} @@ -1349,6 +1354,11 @@ packages: '@esbuild/win32-x64': 0.19.12 dev: true + /escalade@3.2.0: + resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==} + engines: {node: '>=6'} + dev: false + /escape-html@1.0.3: resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==} dev: false @@ -2435,7 +2445,6 @@ packages: /ms@2.1.3: resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==} - dev: false /mz@2.7.0: resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==} @@ -2445,11 +2454,10 @@ packages: thenify-all: 1.6.0 dev: true - /nanoid@3.3.7: - resolution: {integrity: sha512-eSRppjcPIatRIMC1U6UngP8XFcz8MQWGQdt1MTBQ7NaAmvXDfvNxbvWV3x2y6CdEUciCSsDHDQZbhYaB8QEo2g==} + /nanoid@3.3.11: + resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==} engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1} hasBin: true - dev: true /natural-compare@1.4.0: resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==} @@ -2729,7 +2737,9 @@ packages: /picocolors@1.0.0: resolution: {integrity: sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ==} - dev: true + + /picocolors@1.1.1: + resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==} /picomatch@2.3.1: resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==} @@ -2775,14 +2785,23 @@ packages: yaml: 2.3.4 dev: true - /postcss@8.4.35: - resolution: {integrity: sha512-u5U8qYpBCpN13BsiEB0CbR1Hhh4Gc0zLFuedrHJKMctHCHAGrMdG0PRM/KErzAL3CU6/eckEtmHNB3x6e3c0vA==} + /postcss-rtlcss@5.7.1(postcss@8.5.6): + resolution: {integrity: sha512-zE68CuARv5StOG/UQLa0W1Y/raUTzgJlfjtas43yh3/G1BFmoPEaHxPRHgeowXRFFhW33FehrNgsljxRLmPVWw==} + engines: {node: '>=18.0.0'} + peerDependencies: + postcss: ^8.4.21 + dependencies: + postcss: 8.5.6 + rtlcss: 4.3.0 + dev: false + + /postcss@8.5.6: + resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==} engines: {node: ^10 || ^12 || >=14} dependencies: - nanoid: 3.3.7 - picocolors: 1.0.0 - source-map-js: 1.0.2 - dev: true + nanoid: 3.3.11 + picocolors: 1.1.1 + source-map-js: 1.2.1 /prelude-ls@1.2.1: resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==} @@ -2979,6 +2998,17 @@ packages: fsevents: 2.3.3 dev: true + /rtlcss@4.3.0: + resolution: {integrity: sha512-FI+pHEn7Wc4NqKXMXFM+VAYKEj/mRIcW4h24YVwVtyjI+EqGrLc2Hx/Ny0lrZ21cBWU2goLy36eqMcNj3AQJig==} + engines: {node: '>=12.0.0'} + hasBin: true + dependencies: + escalade: 3.2.0 + picocolors: 1.0.0 + postcss: 8.5.6 + strip-json-comments: 3.1.1 + dev: false + /run-parallel@1.2.0: resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==} dependencies: @@ -3118,10 +3148,9 @@ packages: engines: {node: '>=8'} dev: true - /source-map-js@1.0.2: - resolution: {integrity: sha512-R0XvVJ9WusLiqTCEiGCmICCMplcCkIwwR11mOSD9CR5u+IXYdiseeEuXCVAjS54zqwkLcPNnmU4OeJ6tUrWhDw==} + /source-map-js@1.2.1: + resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==} engines: {node: '>=0.10.0'} - dev: true /source-map@0.8.0-beta.0: resolution: {integrity: sha512-2ymg6oRBpebeZi9UUNsgQ89bhx01TcTkmNTGnNO88imTmbSgy4nfujrgVEFKWpMTEGA11EDkTt7mqObTPdigIA==} @@ -3285,7 +3314,6 @@ packages: /strip-json-comments@3.1.1: resolution: {integrity: sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==} engines: {node: '>=8'} - dev: true /strip-literal@2.0.0: resolution: {integrity: sha512-f9vHgsCWBq2ugHAkGMiiYY+AYG0D/cbloKKg0nhaaaSNsujdGIpVXCNsrJpCKr5M0f4aI31mr13UjY6GAuXCKA==} @@ -3552,7 +3580,7 @@ packages: hasBin: true dependencies: cac: 6.7.14 - debug: 4.3.4 + debug: 4.4.1 pathe: 1.1.2 picocolors: 1.0.0 vite: 5.1.4 @@ -3596,7 +3624,7 @@ packages: optional: true dependencies: esbuild: 0.19.12 - postcss: 8.4.35 + postcss: 8.5.6 rollup: 4.12.0 optionalDependencies: fsevents: 2.3.3 From 8cb9aeebd36963ffaf478dce65f17db2098ceed1 Mon Sep 17 00:00:00 2001 From: Chris Campbell Date: Tue, 26 Aug 2025 12:50:21 -0700 Subject: [PATCH 2/4] fix: include `LANG_DIR` parameter in HTML templates + run CSS files through postcss-rtlcss --- examples/sample-docs/package.json | 2 +- .../_shared/src/template-complete.html | 2 +- .../_shared/src/template-default.html | 2 +- .../projects/_shared/src/template-simple.html | 2 +- packages/docs-builder/src/build.ts | 36 +++++++++++++++---- packages/docs-builder/src/gen-html.ts | 9 +++++ 6 files changed, 43 insertions(+), 10 deletions(-) diff --git a/examples/sample-docs/package.json b/examples/sample-docs/package.json index b6ac7d5..97cdd26 100644 --- a/examples/sample-docs/package.json +++ b/examples/sample-docs/package.json @@ -10,6 +10,6 @@ "ci:build": "run-s clean build" }, "devDependencies": { - "@climateinteractive/docs-builder": "^1.0.0" + "@climateinteractive/docs-builder": "workspace:*" } } diff --git a/examples/sample-docs/projects/_shared/src/template-complete.html b/examples/sample-docs/projects/_shared/src/template-complete.html index ed03e64..6260b86 100644 --- a/examples/sample-docs/projects/_shared/src/template-complete.html +++ b/examples/sample-docs/projects/_shared/src/template-complete.html @@ -23,7 +23,7 @@ - +
diff --git a/examples/sample-docs/projects/_shared/src/template-default.html b/examples/sample-docs/projects/_shared/src/template-default.html index 5a67d16..ba9978a 100644 --- a/examples/sample-docs/projects/_shared/src/template-default.html +++ b/examples/sample-docs/projects/_shared/src/template-default.html @@ -37,7 +37,7 @@ - +
diff --git a/examples/sample-docs/projects/_shared/src/template-simple.html b/examples/sample-docs/projects/_shared/src/template-simple.html index 8949f94..7175117 100644 --- a/examples/sample-docs/projects/_shared/src/template-simple.html +++ b/examples/sample-docs/projects/_shared/src/template-simple.html @@ -19,7 +19,7 @@ - +
diff --git a/packages/docs-builder/src/build.ts b/packages/docs-builder/src/build.ts index 4167768..837d5e4 100644 --- a/packages/docs-builder/src/build.ts +++ b/packages/docs-builder/src/build.ts @@ -3,6 +3,9 @@ import { dirname, join as joinPath, resolve as resolvePath } from 'node:path' import { fileURLToPath } from 'node:url' +import postcss from 'postcss' +import postcssRtlCss from 'postcss-rtlcss' + import { findUp, pathExists } from 'find-up' import glob from 'glob' import semverCompare from 'semver-compare' @@ -67,8 +70,19 @@ export async function buildDocs(options: BuildOptions): Promise { * @param enContext The base (English) context. */ async function buildLangs(enContext: Context): Promise { - // Process all pages for each supported language + // Process the CSS files to automatically generate RTL styles const config = enContext.config + const cssFiles: Map = new Map() + function processCss(sourceDir: string, fileName: string): void { + const cssPath = resolvePath(sourceDir, fileName) + const srcCssContent = readTextFile(cssPath) + const outCssContent = postcss([postcssRtlCss()]).process(srcCssContent).css + cssFiles.set(fileName, outCssContent) + } + processCss(config.sourceDir, 'base.css') + processCss(config.baseProjDir, 'project.css') + + // Process all pages for each supported language const localizationDir = resolvePath(config.baseProjDir, 'localization') const langConfigs: LangConfig[] = [] langConfigs.push({ code: 'en', version: config.version }) @@ -88,7 +102,7 @@ async function buildLangs(enContext: Context): Promise { // Build the docs for this language try { - await buildLang(context, langConfig) + await buildLang(context, langConfig, cssFiles) // Generate `en/docs.po`, which contains the base English strings. // We only need to generate this if this project is translated (has @@ -109,8 +123,13 @@ async function buildLangs(enContext: Context): Promise { * * @param context The language-specific context. * @param langConfig The version configuration for the language. + * @param cssFiles The map of CSS files to be copied to the output directory. */ -async function buildLang(context: Context, langConfig: LangConfig): Promise { +async function buildLang( + context: Context, + langConfig: LangConfig, + cssFiles: Map +): Promise { // Check the version of the translation for this language const baseVersion = context.config.version let useSavedVersion: boolean @@ -166,8 +185,13 @@ async function buildLang(context: Context, langConfig: LangConfig): Promise Date: Tue, 26 Aug 2025 13:19:06 -0700 Subject: [PATCH 3/4] fix: correct CSS for responsive sidebar --- examples/sample-docs/projects/_shared/src/base.css | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/examples/sample-docs/projects/_shared/src/base.css b/examples/sample-docs/projects/_shared/src/base.css index 6ee172d..b0f37ba 100644 --- a/examples/sample-docs/projects/_shared/src/base.css +++ b/examples/sample-docs/projects/_shared/src/base.css @@ -634,10 +634,18 @@ footer { .responsive-sidebar-visible .content-container { position: fixed; - left: 300px; width: 100%; } + /* rtl:begin:ignore */ + .responsive-sidebar-visible[dir='ltr'] .content-container { + left: 300px; + } + .responsive-sidebar-visible[dir='rtl'] .content-container { + right: 300px; + } + /* rtl:end:ignore */ + .content-inner-container { margin-top: 0; padding: 0 20px; From 96923cd395f3b6614afae4b3ac0a09cf8f0e5f34 Mon Sep 17 00:00:00 2001 From: Chris Campbell Date: Tue, 26 Aug 2025 13:25:07 -0700 Subject: [PATCH 4/4] fix: organize imports --- packages/docs-builder/src/build.ts | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/packages/docs-builder/src/build.ts b/packages/docs-builder/src/build.ts index 837d5e4..38602b9 100644 --- a/packages/docs-builder/src/build.ts +++ b/packages/docs-builder/src/build.ts @@ -3,11 +3,10 @@ import { dirname, join as joinPath, resolve as resolvePath } from 'node:path' import { fileURLToPath } from 'node:url' -import postcss from 'postcss' -import postcssRtlCss from 'postcss-rtlcss' - import { findUp, pathExists } from 'find-up' import glob from 'glob' +import postcss from 'postcss' +import postcssRtlCss from 'postcss-rtlcss' import semverCompare from 'semver-compare' import { Assets } from './assets'