Imported from FAIQahm/hackathon_I_book (.claude/skills/urdu-rtl-styler/SKILL.md). Install upstream with npx skills add FAIQahm/hackathon_I_book --skill urdu-rtl-styler. Copyright stays with the author.

Urdu RTL Styler

Apply proper Urdu typography and RTL (Right-to-Left) layout to Docusaurus sites.

Quick Setup

Full automated setup (recommended):

.claude/skills/urdu-rtl-styler/scripts/setup.sh --auto-config --scaffold

Basic setup:

.claude/skills/urdu-rtl-styler/scripts/setup.sh

Custom font setup:

.claude/skills/urdu-rtl-styler/scripts/setup.sh \
  --font "Jameel Noori Nastaleeq" \
  --source local \
  --line-height 2.4 \
  --auto-config \
  --scaffold

Command Options

Option	Description	Default
`--font FONT`	Primary Urdu font	`Noto Nastaliq Urdu`
`--fallback FONTS`	Fallback fonts (comma-separated)	`Jameel Noori Nastaleeq, ...`
`--source SOURCE`	Font source: `google` or `local`	`google`
`--line-height N`	Line height for Urdu text	`2.2`
`--auto-config`	Auto-update docusaurus.config.js	off
`--scaffold`	Create i18n/ur/ directory structure	off
`-h, --help`	Show help message	-

What It Does

1. CSS Styles (always)

Adds RTL CSS to src/css/custom.css
Configures font stack with your chosen font
Sets up Docusaurus component overrides

2. Auto-Config (--auto-config)

Detects existing i18n configuration
Adds Urdu locale with direction: 'rtl' if missing
Preserves existing configuration

3. i18n Scaffolding (--scaffold)

Creates complete Urdu content structure:

i18n/ur/
├── code.json                    # UI string translations
├── docusaurus-theme-classic/
│   ├── navbar.json              # Navbar translations
│   └── footer.json              # Footer translations
└── docusaurus-plugin-content-docs/current/
    ├── intro.md                 # Welcome page in Urdu
    ├── chapter-1/index.md
    ├── chapter-2/index.md
    └── chapter-3/index.md

Manual Setup (Alternative)

If you prefer manual setup, run from your Docusaurus project root:

# Create custom CSS directory if not exists
mkdir -p src/css

# Add RTL styles to custom.css
cat << 'EOF' >> src/css/custom.css

/* ===========================================
   Urdu RTL Styles - Generated by urdu-rtl-styler
   =========================================== */

/* Google Fonts Import - Noto Nastaliq Urdu */
@import url('https://fonts.googleapis.com/css2?family=Noto+Nastaliq+Urdu:wght@400;500;600;700&display=swap');

/* Urdu Font Stack */
:root {
  --ifm-font-family-urdu: 'Noto Nastaliq Urdu', 'Jameel Noori Nastaleeq', 'Urdu Typesetting', serif;
  --ifm-line-height-urdu: 2.2;
  --ifm-font-size-urdu-base: 1.1rem;
}

/* RTL Document Styles */
[dir='rtl'] {
  font-family: var(--ifm-font-family-urdu);
  line-height: var(--ifm-line-height-urdu);
  text-align: right;
}

/* RTL Typography Adjustments */
[dir='rtl'] h1,
[dir='rtl'] h2,
[dir='rtl'] h3,
[dir='rtl'] h4,
[dir='rtl'] h5,
[dir='rtl'] h6 {
  font-family: var(--ifm-font-family-urdu);
  line-height: 1.8;
}

[dir='rtl'] p,
[dir='rtl'] li,
[dir='rtl'] td,
[dir='rtl'] th {
  font-family: var(--ifm-font-family-urdu);
  font-size: var(--ifm-font-size-urdu-base);
  line-height: var(--ifm-line-height-urdu);
}

/* ===========================================
   Docusaurus Navigation RTL Overrides
   =========================================== */

/* Navbar RTL */
[dir='rtl'] .navbar__items {
  flex-direction: row-reverse;
}

[dir='rtl'] .navbar__item {
  margin-right: 0;
  margin-left: var(--ifm-navbar-item-padding-horizontal);
}

[dir='rtl'] .navbar__brand {
  margin-right: 0;
  margin-left: 1rem;
}

[dir='rtl'] .navbar__toggle {
  margin-right: 0;
  margin-left: auto;
}

/* Dropdown RTL */
[dir='rtl'] .dropdown__menu {
  right: auto;
  left: 0;
}

[dir='rtl'] .dropdown__link {
  text-align: right;
}

/* ===========================================
   Docusaurus Sidebar RTL Overrides
   =========================================== */

/* Sidebar Container */
[dir='rtl'] .theme-doc-sidebar-container {
  border-right: none;
  border-left: 1px solid var(--ifm-toc-border-color);
}

/* Sidebar Menu Items */
[dir='rtl'] .menu__link {
  padding-right: var(--ifm-menu-link-padding-horizontal);
  padding-left: 0;
}

[dir='rtl'] .menu__list-item-collapsible > .menu__link {
  padding-right: var(--ifm-menu-link-padding-horizontal);
}

/* Sidebar Caret/Arrow */
[dir='rtl'] .menu__caret {
  transform: rotate(180deg);
}

[dir='rtl'] .menu__caret::before {
  transform: rotate(90deg);
}

[dir='rtl'] .menu__list-item--collapsed .menu__caret::before {
  transform: rotate(0deg);
}

/* Nested Menu Items */
[dir='rtl'] .menu__list .menu__list {
  padding-right: var(--ifm-menu-link-padding-horizontal);
  padding-left: 0;
  margin-right: 0.5rem;
  margin-left: 0;
  border-right: 1px solid var(--ifm-menu-color-background-active);
  border-left: none;
}

/* ===========================================
   Docusaurus Content RTL Overrides
   =========================================== */

/* Breadcrumbs */
[dir='rtl'] .breadcrumbs {
  flex-direction: row-reverse;
}

[dir='rtl'] .breadcrumbs__link::before {
  transform: rotate(180deg);
}

/* Pagination Navigation */
[dir='rtl'] .pagination-nav {
  flex-direction: row-reverse;
}

[dir='rtl'] .pagination-nav__link--prev .pagination-nav__label::before {
  content: ' →';
}

[dir='rtl'] .pagination-nav__link--next .pagination-nav__label::after {
  content: '← ';
}

/* Table of Contents */
[dir='rtl'] .table-of-contents {
  padding-right: 0;
  padding-left: var(--ifm-toc-padding-horizontal);
  border-right: none;
  border-left: 1px solid var(--ifm-toc-border-color);
}

[dir='rtl'] .table-of-contents__link {
  text-align: right;
}

/* ===========================================
   Code Blocks - Keep LTR
   =========================================== */

/* Code stays LTR even in RTL context */
[dir='rtl'] pre,
[dir='rtl'] code,
[dir='rtl'] .prism-code {
  direction: ltr;
  text-align: left;
  font-family: var(--ifm-font-family-monospace);
}

[dir='rtl'] .codeBlockTitle_node_modules-\@docusaurus-theme-classic-lib-theme-CodeBlock-Content-styles-module {
  direction: ltr;
  text-align: left;
}

/* ===========================================
   Admonitions RTL
   =========================================== */

[dir='rtl'] .admonition {
  border-right: 0.2rem solid var(--ifm-alert-border-color);
  border-left: none;
}

[dir='rtl'] .admonition-icon {
  margin-right: 0;
  margin-left: 0.75rem;
}

/* ===========================================
   Footer RTL
   =========================================== */

[dir='rtl'] .footer__links {
  flex-direction: row-reverse;
}

[dir='rtl'] .footer__col {
  text-align: right;
}

[dir='rtl'] .footer__title {
  text-align: right;
}

/* ===========================================
   Search RTL
   =========================================== */

[dir='rtl'] .DocSearch-Button {
  flex-direction: row-reverse;
}

[dir='rtl'] .DocSearch-Button-Placeholder {
  padding-right: 0;
  padding-left: 8px;
}

EOF

echo "✅ Added Urdu RTL styles to src/css/custom.css"

Bundled Resources

1. Complete RTL Stylesheet

File: src/css/custom.css (append to existing)

The stylesheet includes:

Component	RTL Adjustments
Typography	Noto Nastaliq Urdu font, increased line-height (2.2)
Navbar	Reversed item order, adjusted margins
Sidebar	Border on left, reversed padding, rotated carets
Breadcrumbs	Reversed direction
Pagination	Swapped arrows (← →)
TOC	Border on left side
Admonitions	Border on right side
Code blocks	Keep LTR direction
Footer	Right-aligned text

2. Noto Nastaliq Urdu Font

Google Fonts Import:

@import url('https://fonts.googleapis.com/css2?family=Noto+Nastaliq+Urdu:wght@400;500;600;700&display=swap');

Font Stack:

:root {
  --ifm-font-family-urdu: 'Noto Nastaliq Urdu', 'Jameel Noori Nastaleeq', 'Urdu Typesetting', serif;
}

3. Docusaurus i18n Configuration

File: docusaurus.config.js (add to i18n section)

i18n: {
  defaultLocale: 'en',
  locales: ['en', 'ur'],
  localeConfigs: {
    en: {
      label: 'English',
      direction: 'ltr',
      htmlLang: 'en-US',
    },
    ur: {
      label: 'اردو',
      direction: 'rtl',  // ⚠️ CRITICAL: Enables RTL rendering
      htmlLang: 'ur-PK',
    },
  },
},

4. Input Variables

Variable	Required	Default	Description
`font_source`	No	`google`	Font source (google/local)
`primary_font`	No	`Noto Nastaliq Urdu`	Primary Urdu font
`fallback_fonts`	No	`Jameel Noori Nastaleeq, ...`	Fallback fonts

Usage Instructions

Step 1: Add RTL Styles

Copy the CSS from Quick Setup or run the setup script:

.claude/skills/urdu-rtl-styler/scripts/setup.sh

Step 2: Configure Docusaurus i18n

Ensure docusaurus.config.js has RTL direction for Urdu:

ur: {
  label: 'اردو',
  direction: 'rtl',  // This triggers [dir='rtl'] styles
  htmlLang: 'ur-PK',
},

Step 3: Create Urdu Content

Create translated docs in i18n/ur/docusaurus-plugin-content-docs/current/:

---
sidebar_position: 1
---

# خوش آمدید

یہ اردو میں مواد ہے۔

Step 4: Test Locally

# Build and serve with Urdu locale
npm run build
npm run serve

# Visit: http://localhost:3000/<repo>/ur/

Verification Checklist

src/css/custom.css contains RTL styles
docusaurus.config.js has direction: 'rtl' for Urdu locale
Noto Nastaliq Urdu font loads (check Network tab)
Navbar items are reversed in RTL mode
Sidebar is on the right side with proper borders
Code blocks remain LTR
Pagination arrows are swapped (← previous, next →)
Text is right-aligned in RTL mode
Line height is comfortable for Nastaliq script (~2.2)

Troubleshooting

Issue	Solution
Font not loading	Check Google Fonts import is first in CSS file
Styles not applying	Verify `direction: 'rtl'` in locale config
Navbar not reversed	Clear browser cache, rebuild site
Code blocks RTL	Ensure `[dir='rtl'] pre, code` rules are present
Sidebar on wrong side	Check `.theme-doc-sidebar-container` border rules
Text cramped	Increase `--ifm-line-height-urdu` to 2.4 or higher
Mixed content issues	Use `dir="ltr"` attribute on specific LTR elements

Local Font Installation (Optional)

If Google Fonts is blocked, use local fonts:

@font-face {
  font-family: 'Noto Nastaliq Urdu';
  src: url('/fonts/NotoNastaliqUrdu-Regular.woff2') format('woff2'),
       url('/fonts/NotoNastaliqUrdu-Regular.woff') format('woff');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

Place font files in static/fonts/ directory.

Typography Best Practices for Urdu

Line Height: Nastaliq script needs 2.0-2.4 line height due to vertical stacking
Font Size: Slightly larger (1.1rem+) for readability
Letter Spacing: Avoid - Nastaliq letters connect naturally
Word Spacing: Default is usually fine
Paragraph Spacing: Use generous margins (1.5rem+)

Docusaurus i18n Docs
Google Fonts - Noto Nastaliq Urdu
MDN RTL Styling Guide
Skill: github-pages-deploy (for deployment with i18n)
ADR-003: Translation & Internationalization Approach

urdu-rtl-styler

About