# Urdu Rtl Styler

> Apply Urdu typography and RTL layout logic for Docusaurus sites. Bundled Resources: Noto Nastaliq Urdu font-stack CSS, [dir=rtl] overrides, i18n scaffolding. Use when adding Urdu/RTL support to a Docusaurus project.

- Skill: `majiayu000/urdu-rtl-styler` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/urdu-rtl-styler`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/urdu-rtl-styler/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/urdu-rtl-styler

---


# Urdu RTL Styler

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

## Quick Setup

**Full automated setup (recommended):**

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

**Basic setup:**

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

**Custom font setup:**

```bash
.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:

```bash
# 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**:
```css
@import url('https://fonts.googleapis.com/css2?family=Noto+Nastaliq+Urdu:wght@400;500;600;700&display=swap');
```

**Font Stack**:
```css
: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)

```javascript
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:

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

### Step 2: Configure Docusaurus i18n

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

```javascript
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/`:

```markdown
---
sidebar_position: 1
---

# خوش آمدید

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

### Step 4: Test Locally

```bash
# 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:

```css
@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

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

## Related

- [Docusaurus i18n Docs](https://docusaurus.io/docs/i18n/introduction)
- [Google Fonts - Noto Nastaliq Urdu](https://fonts.google.com/specimen/Noto+Nastaliq+Urdu)
- [MDN RTL Styling Guide](https://developer.mozilla.org/en-US/docs/Web/CSS/direction)
- Skill: `github-pages-deploy` (for deployment with i18n)
- ADR-003: Translation & Internationalization Approach