feat: add support for right-to-left languages (#101)

chrispcampbell · web-flow · commit a99e72b89402 · 2025-08-26T13:28:48.000-07:00
Fixes #100
diff --git 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/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;
diff --git a/examples/sample-docs/projects/_shared/src/template-complete.html b/examples/sample-docs/projects/_shared/src/template-complete.html
@@ -23,7 +23,7 @@
   </style>
 </head>
 
-<body>
+<body dir="${LANG_DIR}">
 
 <div class="content-container complete">
   <div class="content" id="content">
diff --git a/examples/sample-docs/projects/_shared/src/template-default.html b/examples/sample-docs/projects/_shared/src/template-default.html
@@ -37,7 +37,7 @@
   </script>
 </head>
 
-<body>
+<body dir="${LANG_DIR}">
 
 <div class="sidebar ${BASE_NAME}">
   <div class="sidebar-scroll-container">
diff --git a/examples/sample-docs/projects/_shared/src/template-simple.html b/examples/sample-docs/projects/_shared/src/template-simple.html
@@ -19,7 +19,7 @@
   <link rel="stylesheet" href="${ASSET-project.css}">
 </head>
 
-<body>
+<body dir="${LANG_DIR}">
 
 <div class="content-container">
   <div class="content-inner-container">
diff --git 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/packages/docs-builder/src/build.ts b/packages/docs-builder/src/build.ts
@@ -5,6 +5,8 @@ import { fileURLToPath } from 'node:url'
 
 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'
@@ -67,8 +69,19 @@ export async function buildDocs(options: BuildOptions): Promise<void> {
  * @param enContext The base (English) context.
  */
 async function buildLangs(enContext: Context): Promise<void> {
-  // Process all pages for each supported language
+  // Process the CSS files to automatically generate RTL styles
   const config = enContext.config
+  const cssFiles: Map<string, string> = 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 +101,7 @@ async function buildLangs(enContext: Context): Promise<void> {
 
     // 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 +122,13 @@ async function buildLangs(enContext: Context): Promise<void> {
  *
  * @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<void> {
+async function buildLang(
+  context: Context,
+  langConfig: LangConfig,
+  cssFiles: Map<string, string>
+): Promise<void> {
   // Check the version of the translation for this language
   const baseVersion = context.config.version
   let useSavedVersion: boolean
@@ -166,16 +184,21 @@ async function buildLang(context: Context, langConfig: LangConfig): Promise<void
     copyToBase(await moduleDir('lunr-languages'), 'lunr.stemmer.support.js')
     copyToBase(await moduleDir('mark.js', 'dist'), 'mark.min.js')
 
-    // Copy project-specific CSS
-    copyToBase(context.config.baseProjDir, 'project.css')
+    // Write the preprocessed CSS files
+    function writeCssFile(fileName: string): void {
+      const cssContent = cssFiles.get(fileName)
+      assets.writeWithHash(cssContent, fileName, context.outDir)
+    }
+    writeCssFile('base.css')
+    writeCssFile('project.css')
 
     // Copy all other assets from the "shared src" directory.  Note that glob paths
     // have forward slashes only, so convert backslashes here.
     const sharedSrcPath = context.config.sourceDir.replaceAll('\\', '/')
     const sharedSrcFiles = glob.sync(`${sharedSrcPath}/*`, { nodir: true })
     for (const f of sharedSrcFiles) {
       const relPath = f.replace(`${sharedSrcPath}/`, '')
-      if (!relPath.endsWith('.html')) {
+      if (!relPath.endsWith('.html') && !relPath.endsWith('base.css')) {
         copyToBase(context.config.sourceDir, relPath)
       }
     }
diff --git a/packages/docs-builder/src/gen-html.ts b/packages/docs-builder/src/gen-html.ts
@@ -357,6 +357,15 @@ export function writeHtmlFile(
     switch (id) {
       case 'LANG':
         return context.lang
+      case 'LANG_DIR':
+        switch (context.lang) {
+          case 'ar':
+          case 'fa':
+          case 'he':
+            return 'rtl'
+          default:
+            return 'ltr'
+        }
       case 'BASE_NAME':
         return baseName
       case 'TOP_LEVEL_TITLE':
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,6 @@`
`10`	`10`	`"ci:build": "run-s clean build"`
`11`	`11`	`},`
`12`	`12`	`"devDependencies": {`
`13`		`- "@climateinteractive/docs-builder": "^1.0.0"`
	`13`	`+ "@climateinteractive/docs-builder": "workspace:*"`
`14`	`14`	`}`
`15`	`15`	`}`