2024-02-24 03:34:15 +00:00
# `Astro-Gists`
2024-02-24 02:44:44 +00:00
2024-02-24 03:34:15 +00:00
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
2024-02-24 02:44:44 +00:00
2024-02-24 10:37:09 +00:00
## Example
![Example of AstroGists in use ](./src/assets/example.png )
2024-02-24 02:44:44 +00:00
## Usage
### Prerequisites
2024-02-24 10:37:09 +00:00
The Only Requirement to install this package is a **Github account with a Verified Email** to be able to create a Personal Access Token.
2024-02-24 09:47:57 +00:00
This Integration uses [`Octokit` ](http://octokit.github.io/ ) by `GitHub` to Generate custom gists using [`ExpressiveCode` ](https://expressive-code.com/ ) within your Astro project!
2024-02-24 02:44:44 +00:00
### Installation
Install the integration **automatically** using the Astro CLI:
```bash
2024-02-24 03:34:15 +00:00
pnpm astro add @matthiesenxyz/astro -gists
2024-02-24 02:44:44 +00:00
```
```bash
2024-02-24 03:34:15 +00:00
npx astro add @matthiesenxyz/astro -gists
2024-02-24 02:44:44 +00:00
```
```bash
2024-02-24 03:34:15 +00:00
yarn astro add @matthiesenxyz/astro -gists
2024-02-24 02:44:44 +00:00
```
Or install it **manually** :
1. Install the required dependencies
```bash
2024-02-24 03:34:15 +00:00
pnpm add @matthiesenxyz/astro -gists
2024-02-24 02:44:44 +00:00
```
```bash
2024-02-24 03:34:15 +00:00
npm install @matthiesenxyz/astro -gists
2024-02-24 02:44:44 +00:00
```
```bash
2024-02-24 03:34:15 +00:00
yarn add @matthiesenxyz/astro -gists
2024-02-24 02:44:44 +00:00
```
2. Add the integration to your astro config
```diff
2024-02-24 09:47:57 +00:00
import { defineConfig } from "astro/config";
+import astroGist from "@matthiesenxyz/astro-gists";
2024-02-24 02:44:44 +00:00
2024-02-24 09:47:57 +00:00
// https://astro.build/config
2024-02-24 02:44:44 +00:00
export default defineConfig({
2024-02-24 09:47:57 +00:00
+ integrations: [astroGist()]
2024-02-24 02:44:44 +00:00
});
```
### Configuration
2024-02-24 09:47:57 +00:00
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!
2024-02-24 09:50:18 +00:00
```dotenv
2024-02-24 09:47:57 +00:00
GITHUB_PERSONAL_TOKEN=ghp_YOURPERSONALTOKENHERE
```
### Usage
2024-02-24 17:01:54 +00:00
#### `<GetGist>` Shows a SINGLE gist from a GistCollection
2024-02-24 09:47:57 +00:00
2024-02-24 17:01:54 +00:00
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
2024-02-24 09:47:57 +00:00
2024-02-24 09:50:18 +00:00
```astro
2024-02-24 09:47:57 +00:00
---
import { GetGist } from "@matthiesenxyz/astro-gists/components"
---
< GetGist
gistId="your-gist-id-here"
filename="name-of-desired-file-to-be-displayed.md"
/>
2024-02-24 09:50:18 +00:00
```
2024-02-24 02:44:44 +00:00
2024-02-24 17:01:54 +00:00
#### `<GetGistGroup>` Shows all of the Gists from a GistCollection
This Utility is meant to display an entire collection of Gists by ID
```astro
2024-02-25 09:06:14 +00:00
---
2024-02-24 17:01:54 +00:00
import { GetGistGroup } from "@matthiesenxyz/astro-gists/components"
2024-02-25 09:06:14 +00:00
---
2024-02-24 17:01:54 +00:00
< GetGistGroup
gistId="your-gist-id-here"
/>
```
2024-02-24 10:37:09 +00:00
## 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.
2024-02-24 02:44:44 +00:00
## Licensing
2024-02-24 03:34:15 +00:00
[MIT Licensed ](./LICENSE ). Made with ❤️ by [AdamMatthiesen ](https://github.com/AdamMatthiesen ) Under [MatthiesenXYZ ](https://github.com/MatthiesenXYZ ).
2024-02-24 02:44:44 +00:00
## Acknowledgements
2024-02-24 09:52:04 +00:00
- [`Octokit` ](http://octokit.github.io ) by GitHub
2024-02-24 10:37:09 +00:00
- [`Expressive-Code` ](https://expressive-code.com/ ) By Hippotasic
2024-02-25 09:06:14 +00:00
- [`astro-integration-kit` ](https://github.com/florian-lefebvre/astro-integration-kit ) by Florian