---

name: urdu-rtl-styler description: | 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. version: 1.1.0 inputs: font: description: Primary Urdu font family required: false default: "Noto Nastaliq Urdu" example: "Jameel Noori Nastaleeq" fallback: description: Fallback font families (comma-separated) required: false default: "Jameel Noori Nastaleeq, Urdu Typesetting, serif" source: description: Font source (google or local) required: false default: "google" line_height: description: Line height for Urdu text (Nastaliq needs 2.0-2.4) required: false default: "2.2" auto_config: description: Auto-update docusaurus.config.js with i18n settings required: false default: "false" scaffold: description: Create i18n/ur/ directory with sample content required: false default: "false"

Urdu RTL Styler

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

Quick Setup

Full automated setup (recommended):

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

Basic setup:

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

Custom font setup:

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

Command Options

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:

Copyi18n/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:

Copy# 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:

2. Noto Nastaliq Urdu Font

Google Fonts Import:

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

Font Stack:

Copy: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)

Copyi18n: {
  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

Usage Instructions

Step 1: Add RTL Styles

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

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

Step 2: Configure Docusaurus i18n

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

Copyur: {
  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/:

Copy---
sidebar_position: 1
---

# خوش آمدید

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

Step 4: Test Locally

Copy# 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

Local Font Installation (Optional)

If Google Fonts is blocked, use local fonts:

Copy@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
• Google Fonts - Noto Nastaliq Urdu
• MDN RTL Styling Guide
• Skill: github-pages-deploy (for deployment with i18n)
• ADR-003: Translation & Internationalization Approach