https://github.com/lacymorrow/react-github-readme-md
Render any GitHub README inside a React app — GFM alerts, heading anchors, dark mode
https://github.com/lacymorrow/react-github-readme-md
component documentation gfm github github-readme markdown marked md npm react reactjs readme renderer typescript viewer
Last synced: 23 days ago
JSON representation
Render any GitHub README inside a React app — GFM alerts, heading anchors, dark mode
- Host: GitHub
- URL: https://github.com/lacymorrow/react-github-readme-md
- Owner: lacymorrow
- License: mit
- Created: 2023-09-25T01:34:37.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-05-14T23:08:35.000Z (29 days ago)
- Last Synced: 2026-05-14T23:36:44.421Z (29 days ago)
- Topics: component, documentation, gfm, github, github-readme, markdown, marked, md, npm, react, reactjs, readme, renderer, typescript, viewer
- Language: SCSS
- Homepage: https://www.npmjs.com/package/react-github-readme-md
- Size: 2.4 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Render any GitHub README inside a React app ➔ GitHub styling, dark mode, GFM alerts, heading anchors, fuzzy links.
---
> [!IMPORTANT]
> GFM alerts work too! Like this one. Notes, warnings, tips — they all render with the same styling you see on GitHub.
## Features
- Render any Markdown file with **GitHub native styling**
- **Light + dark** modes
- [`marked`](https://github.com/markedjs/marked)-powered with plugins for **GFM alerts**, **heading anchors**, and **fuzzy links**
- Works on both the client and server (SSR-safe)
- TypeScript types included
- Tiny API: one component, two ways to load content
## Install
```bash
npm install react-github-readme-md
```
## Usage
### From a GitHub repo
```jsx
import { GitHubReadme } from "react-github-readme-md";
;
```
### From a path or URL
```jsx
// or
```
> [!TIP]
> Live, interactive demo on [Chromatic / Storybook](https://main--6528a9ef83709c394594fc93.chromatic.com).
> [!NOTE]
> `.markdown-body` is `width: 100%` by default so `
` blocks don't overflow. Override via the `className` prop or your own CSS.
## API
### ``
| Prop | Type | Default | Description |
|---|---|---|---|
| `username` | `string` | | GitHub user/org. **Required** if `src` is not provided. |
| `repo` | `string` | | GitHub repo name. **Required** if `src` is not provided. |
| `src` | `string` | | Path or URL to a Markdown file. **Required** if `username` + `repo` aren't provided. |
| `addHeadingIds` | `boolean` | `true` | Adds `id` attributes to headings (via [marked-gfm-heading-id](https://www.npmjs.com/package/marked-gfm-heading-id)) so anchor links work. |
| `linkify` | `boolean` | `false` | Auto-link bare URLs in text (via [marked-linkify-it](https://www.npmjs.com/package/marked-linkify-it)). |
| `className` | `string` | | Forwarded to the rendered container. |
## Plugins
shipped with the box:
- **GFM alerts** — `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`. Via [marked-alert](https://github.com/bent10/marked-extensions/tree/main/packages/alerts). The bundled GitHub styles cover the alert blocks — no Tailwind required.
- **Heading anchors** — Auto-generated `id` slugs. Via [marked-gfm-heading-id](https://www.npmjs.com/package/marked-gfm-heading-id).
- **Fuzzy links** — Bare URLs (e.g. `google.com`) become clickable. Via [marked-linkify-it](https://www.npmjs.com/package/marked-linkify-it).
## Playground
➔ **[Open in StackBlitz](https://stackblitz.com/github/lacymorrow/react-github-readme-md/tree/main/examples/stackblitz)** — a tiny Vite + React + TS app with editable `username` / `repo` inputs that re-renders the chosen README live.
Local copy: [`examples/stackblitz/`](./examples/stackblitz)
## Related
- Other utilities by the author: [shipx](https://github.com/lacymorrow/shipx) · [react-is-online-context](https://github.com/lacymorrow/react-is-online-context).
## Acknowledgments
- [@sindresorhus](https://github.com/sindresorhus) for [generate-github-markdown-css](https://github.com/sindresorhus/generate-github-markdown-css) — the source of the bundled GitHub styles.
- [marked](https://github.com/markedjs/marked) — the markdown parser.
- [marked-alert](https://github.com/bent10/marked-extensions), [marked-gfm-heading-id](https://www.npmjs.com/package/marked-gfm-heading-id), [marked-linkify-it](https://www.npmjs.com/package/marked-linkify-it) — the plugin trifecta.
## License
[MIT](./LICENSE) © [Lacy Morrow](https://lacymorrow.com)