Skip to content

Dead simple gist rendering buddy for your Astro blog

License

Notifications You must be signed in to change notification settings

kotosha-real/astro-gist

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

15 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Astro Gist

Dead simple yet powerful gist rendering buddy for your Astro blog.

Features

✅ Uses the standard gist embed script and wraps it in an iframe to avoid blocking the main thread

✅ Lazy loads the gist using IntersectionObserver to improve performance

✅ Allows you to style the gist using your own stylesheet

✅ Fails gracefully when the gist fails to load, showing a link to the gist

✅ Supports rendering a specific file from the gist

✅ Supports adding a caption to the gist

✅ Zero dependencies

✅ Less than 1.5 kB of client JavaScript

Installation

# pnpm
pnpm add @kotosha/astro-gist

# npm
npm install @kotosha/astro-gist

# yarn
yarn add @kotosha/astro-gist

Usage

You can use it in your Astro blog both in .astro and .mdx files. Just import the component and use it with the id prop:

// YourComponent.astro
---
import Gist from '@kotosha/astro-gist'
---

<div>
    <Gist id="your-gist-id" />
</div>
// YourPost.mdx
import Gist from '@kotosha/astro-gist'

Awesome gist here:

<Gist id="your-gist-id" />

You can also pass additional props to customize the component behavior:

Name Type Default Description Required
id string - Gist ID ✔️
caption string - Caption to display below the gist. If not provided, no caption will be displayed. Caption will only be displayed if the gist is loaded successfully
className string - Additional class to add to the figure. Useful for styling
file string - File to display from the gist. If not provided, the whole gist will be displayed
gistStylesUrl string - URL to the stylesheet to use for styling the gist
lazy boolean true Whether to lazy load the gist. Use IntersectionObserver to load the gist when it comes into view. If IntersectionObserver is not supported, the gist will be loaded immediately
observerRootMargin number 150 Margin around the root of the IntersectionObserver. The more the margin, the earlier the iframe will be loaded
showGistLinkOnError boolean true Whether to show the link to the gist when the gist fails to load

Customization

Gist is rendered as a figure with an optional figcaption. You can style it using the className prop:

<Gist className="cls" id="your-gist-id" />

<style>
    .cls {
        /* Basic styles here */
    }

    .cls figcaption {
        /* Figcaption styles here */
    }
</style>

You can also apply styles based on the loading status using the data-loading-status attribute:

.cls[data-loading-status='success'] {
    /* Success styles here */
}

.cls[data-loading-status='error'] {
    /* Error styles here */
}

To style the gist itself, pass the URL to the stylesheet you want to use as the gistStylesUrl prop:

<Gist id="your-gist-id" gistStylesUrl="/gist-theme.css" />

It might be convenient to use a wrapper component to pass the gistStylesUrl prop to all gists in your blog:

// GistWrapper.astro
---
import Gist from '@kotosha/astro-gist'

const props = Astro.props;
---

<Gist gistStylesUrl="/gist-theme.css" {...props} />

Astro Gist uses the srcdoc iframe attribute: when the gist is ready to be rendered, it composes the appropriate srcdoc and passes it to the iframe. Any HTML attributes added to that iframe's html tag are preserved, so it's really easy to style your gists according to your app's theme:

// gist.css
html[data-theme="light"] ... {
    /* Light theme styles here */
}
html[data-theme="dark"] ... {
    /* Dark theme styles here */
}

// Your page
<Gist gistStylesUrl="/gist.css" {...props} />

// Your theme provider
onThemeChange = (theme) => {
    document.querySelectorAll('[data-astro-gist-iframe]').forEach(iframe => {
        const iframeDocument =  iframe.contentWindow?.document || iframe.contentDocument;

        // Could be classes. Just anything you can work with from your CSS
        iframeDocument.documentElement.dataset.theme = theme
    })
}

License

MIT

About

Dead simple gist rendering buddy for your Astro blog

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages