remark-autogen-alt

A simple Remark plugin that automatically generates alt text for images in Markdown files when none is provided.

---

✨ Features

• Automatically fills in missing alt text for Markdown images.
• Converts filenames like my-cat_sitting-on-a-mat.png → my cat sitting on a mat.
• Keeps Markdown clean — no extra text injected into source files.
• Designed for clean rendering at runtime (e.g., in Astro).
• Improves accessibility (a11y) and SEO with zero manual effort.

---

📦 Installation

If using locally in an Astro or Node project:

src/
├── content/
│   └── posts/
│       └── my-article.md
├── utils/
│   └── remark-autogen-alt.mjs
└── ...

Place the plugin file at src/utils/remark-autogen-alt.mjs.

---

🛠 Usage with Astro

1. Copy the plugin file to your project:

   // src/utils/remark-autogen-alt.mjs
   import { visit } from 'unist-util-visit';
   import { extname, basename } from 'path';
   
   export default function remarkAutogenAlt() {
     return (tree) => {
       visit(tree, 'image', (node) => {
         if (!node || typeof node.url !== 'string' || node.url.trim() === '') return;
   
         // Skip if alt is already set
         if (typeof node.alt === 'string' && node.alt.trim().length > 0) return;
   
         try {
           const file = basename(node.url);
           const nameWithoutExt = file.replace(extname(file), '');
           const altText = nameWithoutExt.replace(/[-_]+/g, ' ').trim();
   
           node.alt = altText || 'image';
         } catch (err) {
           console.warn('[remarkAutogenAlt] Failed to generate alt:', err);
           node.alt = 'image';
         }
       });
     };
   }

   Register the plugin in astro.config.mjs:

   import remarkAutogenAlt from './src/utils/remark-autogen-alt.mjs';
   
   export default {
     markdown: {
       remarkPlugins: [remarkAutogenAlt],
     },
   };

✅ Example

Input:

![](images/my-cat_sitting-on-a-mat.png)

Output (runtime-rendered HTML):

<img src="images/my-cat_sitting-on-a-mat.png" alt="my cat sitting on a mat" />

If no valid text can be derived, it defaults to:

<img src="..." alt="image" />

💡 Why This Plugin?

Many content editors forget to add alt text — or use auto-generated images from tools with unhelpful filenames. This plugin ensures you always serve semantic and accessible image content — with zero effort — while keeping your Markdown files clean and minimal.

The alt formatting is handled on the frontend, so your source stays lean and human-writable.

📝 License

MIT — free to use, modify, and share.

Support

For questions, issues, or contributions, please visit our GitHub repository or contact the development team.

Donate

Love our work?

---

🙏 Credits

Built with ❤️ using unist and Remark.