✨ What is README.jsx?

🚀 Why use it?

• � Lightning Fast - Write documentation at the speed of thought.
• 🛠️ Component-Based - Build reusable UI patterns for your READMEs.
• ✅ Type-Safe - Full IntelliSense support for your documentation elements.
• 🎨 Rich Visuals - Easily embed animated SVGs and styled badges.

🛠️ Creating Custom Components

Creating your own components is easy! Just define a function that returns a string or other UI elements:

const MyBadge = ({ text }) => (
  <UI.Badge leftText="Status" rightText={text} rightColor="green" />
);

export default (
  <UI.Center>
    <MyBadge text="Online" />
  </UI.Center>
);

Usage

Quick Start

Create a README.jsx file:

import { UI } from "readme.jsx";

export default (
  <>
    <UI.Heading text="My Awesome Project" />

    <UI.Alert type="TIP" text="This README was written in JSX!" />

    <UI.List list={["Easy to write", "Type-safe", "Maintainable"]} />

    <UI.Code code={`console.log("Hello, README.jsx!")`} lang="javascript" />
  </>
);

Transpile to Markdown:

npx readme.jsx ./README.jsx

🧱 Available UI Components

Explore the built-in components you can use to build your documentation.

Name

Code

Preview

Bold

<UI.Bold text='Hello' />

Hello

Italic

<UI.Italic text='Hello' />

Hello

Strikethrough

<UI.StrikeThrough text='Hello' />

~~Hello~~

Inline Code

<UI.Code inline code='console.log()' />

console.log()

Code Block

<UI.Code lang='js' code='const x = 1;' />

const x = 1;

Link

<UI.Link link='#hello' description='Click me' />

Click me

Heading

<UI.Heading text='Title' order={2} />

Title

List

<UI.List list={['Item 1', 'Item 2']} />

• Item 1
• Item 2

Ordered List

<UI.List list={['First', 'Second']} ordered />

1. First
2. Second

Image

<UI.Image src='logo.png' width='100px' />

Alert Note

<UI.Alert type='NOTE' text='Note info' />

[!NOTE] Note info

Alert Important

<UI.Alert type='IMPORTANT' text='Important info' />

[!IMPORTANT] Important info

Alert Caution

<UI.Alert type='CAUTION' text='Cautious note' />

[!CAUTION] Important info

Alert Warning

<UI.Alert type='WARNING' text='Be careful!' />

[!WARNING] Be careful!

Alert Tip

<UI.Alert type='TIP' text='Pro tip here' />

[!TIP] Pro tip here

Tasks

<UI.Tasks list={[{content: 'Done', done: true}]} />

• [x] Done
• [ ] Todo

Keyboard Key

<UI.Kbd text='Ctrl+C' />

Ctrl+C

Subscript

<UI.Sub text='2' />

2

Supscript

<UI.Sup text='2' />

Emoji

<UI.Emoji emjoji=':smile:' />

:smile:

Horizontal Rule

<UI.Hr />

Line Break

<UI.Br />

↵ (new line)

Center Align

<UI.Center>Content</UI.Center>

Boxed Content

<UI.Boxed>Content</UI.Boxed>

Badge

<UI.Badge leftText="The badge" rightText="Suffix" leftColor="white" rightColor="red" />

Terminal

<UI.Terminal code="npx example" />

Paypal

<UI.Paypal id="YOUR_ID" />

Accordion

<UI.Accordion title="Title"> <UI.Bold text="Content" /> </UI.Accordion>

Tag

<UI.Tag type="wordpress" />

💎 Advanced Showcase

Documentation doesn't have to be boring. Use advanced UI.Svg features to create interactive-feeling elements.

Animated Feature Card

<UI.Svg
  distUrl="./assets/feature-card.svg"
  viewBox="0 0 800 240"
  keyframes={[
    {
      name: "pulse",
      frames: [
        { percent: "0%", style: { transform: "scale(1)", opacity: "0.5" } },
        { percent: "50%", style: { transform: "scale(1.05)", opacity: "0.8" } },
        { percent: "100%", style: { transform: "scale(1)", opacity: "0.5" } },
      ],
    },
  ]}
  style={{
    card: {
      background: "linear-gradient(135deg, #6366f1 0%, #a855f7 100%)",
      borderRadius: "20px",
      padding: "30px",
      color: "white",
      fontFamily: "system-ui",
      display: "flex",
      alignItems: "center",
      gap: "20px",
    },
    icon: {
      width: "80px",
      height: "80px",
      background: "rgba(255,255,255,0.2)",
      borderRadius: "50%",
      display: "flex",
      alignItems: "center",
      justifyContent: "center",
      fontSize: "40px",
      animation: "pulse 2s infinite ease-in-out",
    },
    content: { display: "flex", flexDirection: "column" },
    badge: {
      background: "#facc15",
      color: "#1e1b4b",
      padding: "4px 10px",
      borderRadius: "6px",
      fontSize: "12px",
      fontWeight: "bold",
      width: "fit-content",
      marginBottom: "8px",
    },
  }}
  html={`
        <div id="card">
            <div id="icon">✨</div>
            <div id="content">
                <div id="badge">NEW FEATURE</div>
                <h2 style="margin: 0; font-size: 32px">Dynamic SVG Components</h2>
                <p style="margin: 8px 0 0; opacity: 0.9; font-size: 18px">
                    Inject raw HTML and CSS into your README with full
                    animation support and responsive layouts.
                </p>
            </div>
        </div>
    `}
/>

Import package.json values

import packageJson from "./package.json" with { type: "json" };

<UI.Badge leftText="version" rightText={packageJson.version} />;

Configuration

Add these scripts to your package.json:

{
  "scripts": {
    "readme": "npx readme.jsx README.jsx",
    "readme:watch": "npx readme.jsx README.jsx --watch"
  }
}

Benefits

• 🔧 IDE Support - Full IntelliSense and autocomplete
• ♻️ Reusability - Create custom components and templates
• 🎨 Rich Styling - Advanced layouts and animations
• 📱 Responsive - Built-in responsive design patterns
• ⚡ Fast - Efficient compilation to standard Markdown

Contributing

We welcome contributions! Here's how you can help:

• [x] 🍴 Fork the repository
• [x] 🌿 Create a feature branch
• [ ] 💡 Add your amazing feature
• [ ] ✅ Write tests
• [ ] 📝 Update documentation
• [ ] 🚀 Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.