zhongwei/gh-rawveg-skillsforge-marketplace-hashnode-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:50:26 +08:00
commit 0e81d24079
7 changed files with 3879 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "hashnode-api",
"description": "Interacts with the Hashnode API.",
"version": "0.0.0-2025.11.28",
"author": {
"name": "Tim Green",
"email": "rawveg@gmail.com"
},
"skills": [
"./skills/hashnode-api"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# hashnode-api
Interacts with the Hashnode API.

56
plugin.lock.json Normal file
View File

@@ -0,0 +1,56 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:rawveg/skillsforge-marketplace:hashnode-api",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "1a1a92cfdb06732c796360449899b42aceb7aafe",
"treeHash": "e56328329dad4bc714e138514619dffa1f9a024835c645b643f2611202f514cf",
"generatedAt": "2025-11-28T10:27:51.438944Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "hashnode-api",
"description": "Interacts with the Hashnode API."
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "228fa5f0c81253f29dc3a293d849dea32ce00a090b721bebc82b829bf1cad357"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "abbd17300fd8878f69da4ed31c8f1fe8955e76c34f7f6cea985b3c83d599629d"
},
{
"path": "skills/hashnode-api/plugin.json",
"sha256": "f010b6077407f8c2ef7f5c2e1eb8176cda6f712cdc9a9a15f85b977168689384"
},
{
"path": "skills/hashnode-api/SKILL.md",
"sha256": "324630be73370d340116c502303f750526b9a4a612653de18af91754b451fbc3"
},
{
"path": "skills/hashnode-api/references/api.md",
"sha256": "9b6c81cf2f9daee65c2f4f3e3151cdbc6f7ac945ec3edf7221497c562eba45bd"
},
{
"path": "skills/hashnode-api/references/index.md",
"sha256": "a592a19108bf91c48e77bc0894521e15902aabc65649f88735aa9ef033ca920b"
}
],
"dirSha256": "e56328329dad4bc714e138514619dffa1f9a024835c645b643f2611202f514cf"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

429
skills/hashnode-api/SKILL.md Normal file
View File

@@ -0,0 +1,429 @@
---
name: hashnode-api
description: Hashnode GraphQL API documentation for creating, managing, and querying blogs, posts, publications, and user data on the Hashnode platform
---
# Hashnode API Skill
Comprehensive assistance with the Hashnode GraphQL API for blog management, content creation, and user interaction on the Hashnode platform.
## When to Use This Skill
This skill should be triggered when:
- Building integrations with Hashnode blogs or publications
- Querying Hashnode posts, users, or publication data
- Creating, publishing, or managing blog posts via API
- Implementing authentication with Hashnode Personal Access Tokens
- Working with GraphQL queries or mutations for Hashnode
- Debugging Hashnode API responses or error codes
- Setting up pagination (cursor-based or offset-based) for Hashnode data
- Implementing newsletter subscriptions, comments, or user interactions
- Migrating from the legacy Hashnode API to the new GQL endpoint
## Key Concepts
### API Endpoint
All Hashnode API requests go through a single GraphQL endpoint:
- **Endpoint:** `https://gql.hashnode.com` (POST only)
- **Playground:** Visit the same URL in a browser to explore the API
- **Legacy API:** `https://api.hashnode.com` is discontinued - migrate to new endpoint
### Authentication
- Most queries work without authentication
- Sensitive fields (drafts, email, etc.) require authentication
- All mutations require authentication
- **Authentication method:** Add `Authorization` header with your Personal Access Token (PAT)
- **Get your PAT:** https://hashnode.com/settings/developer → "Generate New Token"
### Rate Limits
- **Queries:** 20,000 requests per minute
- **Mutations:** 500 requests per minute
### Caching
- Almost all query responses are cached on the Edge
- Cache is automatically purged when you mutate data
- Check cache status in playground (bottom right: HIT/MISS)
- **Important:** Always request the `id` field to avoid stale data
### Error Codes
Common GraphQL error codes:
- `GRAPHQL_VALIDATION_FAILED` - Invalid query structure
- `UNAUTHENTICATED` - Missing or invalid auth token
- `FORBIDDEN` - Insufficient permissions
- `BAD_USER_INPUT` - Invalid input data
- `NOT_FOUND` - Resource doesn't exist
## Quick Reference
### 1. Fetch Publication Details
```graphql
query Publication {
publication(host: "blog.developerdao.com") {
id
isTeam
title
about {
markdown
}
}
}
```
Get basic information about a publication by its hostname.
### 2. Fetch Recent Blog Posts
```graphql
query Publication {
publication(host: "blog.developerdao.com") {
id
isTeam
title
posts(first: 10) {
edges {
node {
id
title
brief
url
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
```
Retrieve the latest 10 posts from a publication with cursor-based pagination support.
### 3. Fetch a Single Article by Slug
```graphql
query Publication {
publication(host: "blog.developerdao.com") {
id
post(slug: "the-developers-guide-to-chainlink-vrf-foundry-edition") {
id
title
content {
markdown
html
}
}
}
}
```
Get full content of a specific article using its slug and publication hostname.
### 4. Cursor-Based Pagination (Infinite Scroll)
```graphql
query Publication {
publication(host: "blog.developerdao.com") {
id
posts(
first: 10
after: "NjQxZTc4NGY0M2NiMzc2YjAyNzNkMzU4XzIwMjMtMDMtMjVUMDQ6Mjc6NTkuNjQxWg=="
) {
edges {
node {
id
title
brief
url
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
```
Use `endCursor` from previous response as `after` parameter to fetch next page.
### 5. Offset-Based Pagination (Traditional Pages)
```graphql
query Followers {
user(username: "SandroVolpicella") {
id
followers(pageSize: 10, page: 1) {
nodes {
id
username
}
pageInfo {
hasNextPage
hasPreviousPage
previousPage
nextPage
}
}
}
}
```
Navigate between pages using explicit page numbers.
### 6. Get Entity Count (Series Count Example)
```graphql
query SeriesCount {
publication(host: "engineering.hashnode.com") {
id
seriesList(first: 0) {
totalDocuments
}
}
}
```
Result:
```json
{
"data": {
"publication": {
"seriesList": {
"totalDocuments": 3
}
}
}
}
```
Use `totalDocuments` field to get counts without fetching all data.
### 7. Fetch Posts from a Series
```graphql
query Publication {
publication(host: "lo-victoria.com") {
id
series(slug: "graphql") {
id
name
posts(first: 10) {
edges {
node {
id
title
}
}
}
}
}
}
```
Get all posts belonging to a specific series.
### 8. Fetch Static Pages
```graphql
query Publication {
publication(host: "lo-victoria.com") {
id
staticPages(first: 10) {
edges {
node {
id
title
slug
}
}
}
}
}
```
Retrieve custom static pages like "About", "Contact", etc.
### 9. Fetch Single Static Page
```graphql
query Publication {
publication(host: "lo-victoria.com") {
id
staticPage(slug: "about") {
id
title
content {
markdown
}
}
}
}
```
Get content of a specific static page by slug.
### 10. Authentication Example - Get Drafts (Requires Auth)
```graphql
query Publication($first: Int!, $host: String) {
publication(host: $host) {
id
drafts(first: $first) {
edges {
node {
id
title
}
}
}
}
}
```
**Headers:**
```json
{
"Authorization": "your-personal-access-token-here"
}
```
Variables:
```json
{
"first": 10,
"host": "your-blog-host.hashnode.dev"
}
```
Drafts can only be queried by the publication owner with valid authentication.
## Reference Files
This skill includes comprehensive documentation in `references/`:
- **api.md** - Complete Hashnode GraphQL API documentation including:
- GQL Playground overview
- Caching behavior and best practices
- Rate limits and authentication
- Status codes and error handling
- Pagination methods (cursor-based and offset-based)
- Migration guide from legacy API
- Query and mutation examples
- Full list of available queries and mutations
Use the reference files for detailed information about specific API features, error handling patterns, and advanced query techniques.
## Working with This Skill
### For Beginners
Start by understanding the core concepts above, then explore:
1. **API Endpoint:** Test queries in the playground at https://gql.hashnode.com
2. **Authentication:** Generate your PAT at https://hashnode.com/settings/developer
3. **Basic Queries:** Try fetching publication details and blog posts first
4. **Pagination:** Start with cursor-based pagination for simple infinite scroll
### For Intermediate Users
Focus on:
1. **Authentication flows:** Implement PAT-based auth in your application
2. **Error handling:** Handle GraphQL error codes properly
3. **Pagination strategies:** Choose between cursor-based and offset-based based on your UI needs
4. **Caching considerations:** Always request `id` fields to avoid stale data
5. **Content extraction:** Work with both markdown and HTML content formats
### For Advanced Users
Explore:
1. **Mutations:** Publishing posts, managing drafts, updating content
2. **Complex queries:** Nested queries with multiple levels (publication → series → posts)
3. **Batch operations:** Optimize API calls with GraphQL field selection
4. **Webhook integration:** Handle Hashnode webhook events
5. **Rate limit optimization:** Implement efficient request batching
### Navigation Tips
- **Start broad → go deep:** Begin with publication queries, then drill into specific posts/series
- **Check authentication:** If you get `UNAUTHENTICATED` errors, verify your PAT is in the Authorization header
- **Test in playground:** Use https://gql.hashnode.com to test queries before implementing
- **Monitor cache:** Watch cache HIT/MISS status to optimize your queries
- **Read error messages:** GraphQL errors include helpful details in the `extensions.code` field
## Common Use Cases
### Building a Blog Frontend
1. Fetch publication metadata
2. Get post list with pagination
3. Display individual posts by slug
4. Implement series/category navigation
5. Show static pages (about, contact)
### Content Management Dashboard
1. Authenticate with PAT
2. List and manage drafts
3. Publish/update posts
4. Schedule content
5. Monitor analytics
### Newsletter Integration
1. Subscribe/unsubscribe users
2. Fetch subscriber counts
3. Manage email preferences
4. Track engagement metrics
### Migration from Legacy API
1. Update endpoint from `api.hashnode.com` to `gql.hashnode.com`
2. Convert REST calls to GraphQL queries
3. Update authentication mechanism (check docs)
4. Adjust pagination from old format to cursor/offset-based
5. Update error handling for new error codes
## Resources
### Official Documentation
- **API Docs:** https://apidocs.hashnode.com
- **Playground:** https://gql.hashnode.com
- **Discord:** Join for updates and community support
- **GraphQL Guide:** freeCodeCamp's beginner-friendly GraphQL guide
### references/
The `api.md` reference file contains:
- Complete API specification
- All available queries and mutations
- Detailed parameter descriptions
- Authentication requirements
- Code examples with proper syntax
- Links to original documentation
- Comprehensive error code reference
## Important Notes
- **Always request the `id` field** on objects to avoid stale cached data
- **Rate limits are generous** but respect them for production apps
- **Cache behavior:** Most responses are cached; mutations automatically purge related cache
- **Breaking changes are rare** and announced well in advance on Discord
- **Legacy API is shut down** - use `gql.hashnode.com` only
## Troubleshooting
### Getting UNAUTHENTICATED errors?
- Verify your Personal Access Token is valid
- Check the `Authorization` header is set correctly
- Ensure you're requesting fields that require auth (drafts, email, etc.)
### Not seeing latest data?
- Always request the `id` field to avoid stale cached data
- Check if response is HIT/MISS in playground
### Query validation failed?
- Verify your GraphQL syntax in the playground first
- Check required parameters are provided
- Ensure field names match the schema
### Rate limit reached?
- Queries: 20k/min is very generous - optimize your queries
- Mutations: 500/min limit - batch operations where possible
- Use caching on your end to reduce API calls
## Updating
This skill was automatically generated from official Hashnode documentation. To refresh with updated documentation, regenerate the skill using the latest docs from https://apidocs.hashnode.com.

15
skills/hashnode-api/plugin.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "hashnode-api",
"description": "Interacts with the Hashnode API.",
"version": "1.0.0",
"author": {
"name": "Tim Green",
"email": "rawveg@gmail.com"
},
"homepage": "https://github.com/rawveg/claude-skills-marketplace",
"repository": "https://github.com/rawveg/claude-skills-marketplace",
"license": "MIT",
"keywords": ["hashnode-api", "hashnode", "Claude Code"],
"category": "productivity",
"strict": false
}

3357
skills/hashnode-api/references/api.md Normal file
View File

File diff suppressed because it is too large Load Diff

7
skills/hashnode-api/references/index.md Normal file
View File

@@ -0,0 +1,7 @@
# Hashnode-Api Documentation Index
## Categories
### Api
**File:** `api.md`
**Pages:** 2