mdxgists.net

A minimal, beautiful viewer for GitHub Gists. Replace gist.github.com with mdxgists.net in any gist URL. That's it.

mdxgists.net

Usage

gist.github.com/user/abc123  →  mdxgists.net/user/abc123

Every file type gets the best possible rendering:

• Markdown - proper typography, GFM alerts, frontmatter tables, auto table of contents, heading anchors
• Code - syntax highlighting via Shiki (same engine as VS Code), with copy buttons on every block
• JSON / GeoJSON - collapsible tree viewer
• YAML - parsed and displayed as a navigable tree
• CSV / TSV - sortable, searchable data table
• ICS / iCal - calendar event cards with dates, locations, and recurrence

Multi-file gists get tabs. Toggle between "Pretty" and "Raw" views on structured files. Everything looks clean.

URL parameters

Customize how any gist renders by appending query params:

Param	Effect
?theme=dark	Force dark mode
?theme=light	Force light mode
?noheader	Hide title, tabs, and copy buttons
?nofooter	Hide author info and footer
?mono	Monospace font for all text
?file={filename}	Show a specific file from multi-file gists

Combine them: mdxgists.net/user/abc123?theme=dark&noheader&nofooter

Raw content

Fetch raw file content with proper Content-Type headers via the API:

mdxgists.net/api/raw/{gist_id}
mdxgists.net/api/raw/{gist_id}?file={filename}

Optimized for MDX / Next.js technical blogs

Embed any GitHub Gist directly into your MDX articles as a custom component. The gist is fetched server-side at build time, rendered inline with syntax highlighting, and linked back to mdxgists.net for the full viewer experience.

// mdx-components.tsx
import GitHubGist from '@/components/GitHubGist';

export function useMDXComponents(components) {
  return { ...components, GitHubGist };
}

// article.mdx
<GitHubGist id="your_gist_id" figCaptionText="Example config" />

The component:

• Fetches gist content from the GitHub API server-side (ISR, 1hr revalidation)
• Detects language and applies syntax highlighting via react-syntax-highlighter
• Renders a header bar with the language badge and copy button
• Links out to mdxgists.net/{user}/{gist_id} for the full viewer
• Degrades gracefully with an inline error state if the gist is unavailable

A read-only GitHub fine-grained PAT set as GITHUB_TOKEN raises the API rate limit from 60 to 5,000 requests/hour.

Agent skill

Teach your coding agent to use mdxgists.net links whenever it creates or shares gists. Works with Claude Code, Codex, Cursor, and any agent that supports skills.

npx skills add linuz90/gists.sh

Self-hosting

pnpm install
cp .env.local.example .env.local  # add your GITHUB_TOKEN
pnpm dev

A GitHub personal access token with the gist scope raises your API rate limit from 60 to 5,000 requests/hour. Note: the gist scope grants read access to all gists on the account, including secret ones. If that's a concern, use a token from a dedicated account with no sensitive gists.

Stack

Next.js 15, Tailwind CSS v4, react-markdown, Shiki, deployed on Vercel.

Author

Built by Abdullah Muhammad (@CodingAbdullah).