141 lines
3.4 KiB
Markdown
141 lines
3.4 KiB
Markdown
# `Astro-Gists`
|
|
|
|
This is an [Astro integration](https://docs.astro.build/en/guides/integrations-guide/) that allows the user to import GitHub Gists by ID through an Astro Component and Octokit
|
|
|
|
## Example
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
### Prerequisites
|
|
|
|
The Only Requirement to install this package is a **Github account with a Verified Email** to be able to create a Personal Access Token.
|
|
|
|
This Integration uses [`Octokit`](http://octokit.github.io/) by `GitHub` to Generate custom gists using [`ExpressiveCode`](https://expressive-code.com/) within your Astro project!
|
|
|
|
This Integration currently includes `@astrojs/mdx` and is enabled by default.
|
|
|
|
### Installation
|
|
|
|
Install the integration **automatically** using the Astro CLI:
|
|
|
|
```bash
|
|
pnpm astro add @matthiesenxyz/astro-gists
|
|
```
|
|
|
|
```bash
|
|
npx astro add @matthiesenxyz/astro-gists
|
|
```
|
|
|
|
```bash
|
|
yarn astro add @matthiesenxyz/astro-gists
|
|
```
|
|
|
|
Or install it **manually**:
|
|
|
|
1. Install the required dependencies
|
|
|
|
```bash
|
|
pnpm add @matthiesenxyz/astro-gists
|
|
```
|
|
|
|
```bash
|
|
npm install @matthiesenxyz/astro-gists
|
|
```
|
|
|
|
```bash
|
|
yarn add @matthiesenxyz/astro-gists
|
|
```
|
|
|
|
2. Add the integration to your astro config
|
|
|
|
```diff
|
|
import { defineConfig } from "astro/config";
|
|
+import astroGist from "@matthiesenxyz/astro-gists";
|
|
|
|
// https://astro.build/config
|
|
export default defineConfig({
|
|
+ integrations: [astroGist({
|
|
// OPTIONAL CONFIG OPTIONS
|
|
// Enable the Astrojs/MDX Integration - Default: true
|
|
MDXIntegration: true
|
|
+ })]
|
|
});
|
|
```
|
|
|
|
### Configuration
|
|
|
|
Setup your `.env` file with the following secret from github:
|
|
|
|
Github Personal Access Token (Classic)
|
|
- No Special Permissions required
|
|
- Octokit recommends creating an empty token for this!
|
|
|
|
```dotenv
|
|
GITHUB_PERSONAL_TOKEN=ghp_YOURPERSONALTOKENHERE
|
|
```
|
|
|
|
*Note: Without this token, you will be HEAVILY limited by quantity of requests made with Octokit.*
|
|
|
|
### Usage
|
|
|
|
#### `<GetGist>` Shows a SINGLE gist from a GistCollection
|
|
|
|
This Utility is meant to display a single Gist as Codeblocks using ExpressiveCode for Astro instead of Scripted Elements using the default Gist method by calling the ID and Filename
|
|
|
|
```astro
|
|
---
|
|
import { GetGist } from "@matthiesenxyz/astro-gists/components"
|
|
---
|
|
<GetGist
|
|
gistId="your-gist-id-here"
|
|
filename="name-of-desired-file-to-be-displayed.md"
|
|
/>
|
|
```
|
|
|
|
#### `<GetGistGroup>` Shows all of the Gists from a GistCollection
|
|
|
|
This Utility is meant to display an entire collection of Gists by ID
|
|
|
|
```astro
|
|
---
|
|
import { GetGistGroup } from "@matthiesenxyz/astro-gists/components"
|
|
---
|
|
<GetGistGroup
|
|
gistId="your-gist-id-here"
|
|
/>
|
|
```
|
|
|
|
## Contributing
|
|
|
|
This package is structured as a monorepo:
|
|
|
|
- `playground` contains code for testing the package
|
|
- `package` contains the actual package
|
|
|
|
Install dependencies using pnpm:
|
|
|
|
```bash
|
|
pnpm i --frozen-lockfile
|
|
```
|
|
|
|
Start the playground:
|
|
|
|
```bash
|
|
pnpm playground:dev
|
|
```
|
|
|
|
You can now edit files in `package`. Please note that making changes to those files may require restarting the playground dev server.
|
|
|
|
## Licensing
|
|
|
|
[MIT Licensed](./LICENSE). Made with ❤️ by [AdamMatthiesen](https://github.com/AdamMatthiesen) Under [MatthiesenXYZ](https://github.com/MatthiesenXYZ).
|
|
|
|
## Acknowledgements
|
|
|
|
- [`Octokit`](http://octokit.github.io) by GitHub
|
|
- [`Expressive-Code`](https://expressive-code.com/) By Hippotasic
|
|
- [`@astrojs/mdx`](https://docs.astro.build/en/guides/integrations-guide/mdx/) by withAstro
|
|
- [`astro-integration-kit`](https://github.com/florian-lefebvre/astro-integration-kit) by Florian
|