djyde/sairin

Generate a blog from GitHub Issue

Sairin

Generate a blog from GitHub issue.

One Click Deploy

Get started

1. Clone the starter template

$ git clone https://github.com/djyde/sairin-starter.git your_blog

$ cd your_blog && rm .git

# install dependencies

$ npm i

2. Run the blog

Before running, you need to set these environment variable by creating a .env:

• REPO: The GitHub repo name. Like user/repo
• GITHUB_TOKEN: The personal access token

# run the blog

$ npm run dev

3. Export the blog as a static site

$ npm run export

The static site will be ouput to /out

Documentation

sairin.config.ts

• siteConfig
  • title (required) Your blog title
  • author The author name of your blog. The repo owner login id will be set by default
  • url The URL of your blog. Start with http:// or https://. This field is required if you want to enable RSS.
• theme (required)
• themeConfig A config object passed to the theme
• allowUsers string[] An array of GitHub user login id that allowed to publish blog post. By default, only issues created by the repo owner will be published on the blog.

Environment Variables

• GITHUB_TOKEN (required) Personal Access Token to call GitHub API
• REPO The repository which will be fetch blog posts from (e.g owner/repo). By default it will use the repo that created by Vercel.

RSS Support

Sairin support RSS out of the box. You need to set url on the sairin.config.ts to enable it:

// sairin.config.ts

export default {
  siteConfig: {
    title: 'Sairin',
+   url: 'http://your-site.com'
  },
} as SairinConfig;

The RSS feed is on http://your-site.com/rss.xml.

FAQ

Need I redeploy the Vercel project after the issue updated?

No.

How long will take to update the latest content after the issue content update?

Blog will be updated every 1 minute.

Theme Development

Sairin supports custom theme. But the API is not stable now. If you still want to try to develope a theme, you could see the source code of the built-in theme sairin-theme-minimal.

Build

Development

Sairin use pnpm to organize the packages, you need to install pnpm first.

Install the dependencies:

$ pnpm i

Create a .env file on example/:

GITHUB_TOKEN= # need to provide a GitHub access token when developing, or it will reach the API request rate limit.
REPO=djyde/sairin # you can change to any repo for debugging

Run dev command:

$ pnpm run dev --filter "*" --parallel

This command will run a blog on localhost.

sairin's Issues

lihailihai

xiexiexiexie

vercel中构建失败

1、新建一个sairin项目
2、在新建项目中将title更改为自己的，自动构建就会失败如下图。

[23:06:22.482] Running build in Washington, D.C., USA (East) – iad1
[23:06:23.181] Cloning github.com/lingPoint/Zerox (Branch: main, Commit: aac8095)
[23:06:23.641] Cloning completed: 460.055ms
[23:06:25.376] Restored build cache
[23:06:25.430] Running "vercel build"
[23:06:25.910] Vercel CLI 33.5.3
[23:06:26.264] Installing dependencies...
[23:06:26.556] yarn install v1.22.17
[23:06:26.575] warning package.json: No license field
[23:06:26.585] info No lockfile found.
[23:06:26.590] warning @sairinjs/[email protected]: No license field
[23:06:26.592] [1/4] Resolving packages...
[23:06:29.502] [2/4] Fetching packages...
[23:06:37.044] [3/4] Linking dependencies...
[23:06:38.568] [4/4] Building fresh packages...
[23:06:38.573] success Saved lockfile.
[23:06:38.576] Done in 12.03s.
[23:06:38.606] Detected Next.js version: 12.3.4
[23:06:38.608] Running "yarn run build"
[23:06:38.788] yarn run v1.22.17
[23:06:38.807] warning package.json: No license field
[23:06:38.818] $ next build
[23:06:39.381] info - Linting and checking validity of types...
[23:06:41.703] info - Creating an optimized production build...
[23:06:51.673] info - Compiled successfully
[23:06:51.674] info - Collecting page data...
[23:06:52.193] Error: The provided path / does not match the page: /[...path].
[23:06:52.193] at /vercel/path0/node_modules/next/dist/build/utils.js:629:23
[23:06:52.194] at Array.forEach ()
[23:06:52.194] at buildStaticPaths (/vercel/path0/node_modules/next/dist/build/utils.js:615:17)
[23:06:52.194] at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
[23:06:52.194] at async /vercel/path0/node_modules/next/dist/build/utils.js:886:115
[23:06:52.194] at async Span.traceAsyncFn (/vercel/path0/node_modules/next/dist/trace/trace.js:79:20)
[23:06:52.194]
[23:06:52.194] > Build error occurred
[23:06:52.194] Error: Failed to collect page data for /[...path]
[23:06:52.195] at /vercel/path0/node_modules/next/dist/build/utils.js:916:15
[23:06:52.195] at process.processTicksAndRejections (node:internal/process/task_queues:95:5) {
[23:06:52.195] type: 'Error'
[23:06:52.195] }
[23:06:52.223] error Command failed with exit code 1.
[23:06:52.224] info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
[23:06:52.246] Error: Command "yarn run build" exited with 1
[23:06:52.503]

A Blog Engine Based on GitHub Issue With the Power of Next.js ISR

---

path: introducing-sairin

TLDR: Step by step guide

Background

Many people are using GitHub Issue for blogging. Because you can just create an issue and write some markdown to post some content. When you want to inject an image, just paste an image on the editor and it can be uploaded to GitHub. No need to worry about the static files hosting.

Some tools use GitHub API to generate a static blog. This is fine but when a post is updated, we need to redeploy the whole project (although we usually have automation to do this).

I came up with an idea that using Next.js to generate a blog, fetch blog posts from GitHub issues from a repository. But the problem is: if we put the GitHub API call on every blog post page request to fetch the issue content, it will reach the API rate limit soon. It doesn't scale.

Fortunately, Next.js has a special data fetching policy called Incremental Static Regeneration, it means we can generate static pages first, and update them on demand.

For example, we can set the post page update in every 1 minutes by using revalidate in getStaticProps:

export async function getStaticProps() {
  const res = await fetch('https://api.github.com/xxx')
  const posts = await res.json()

  return {
    props: {
      posts,
    },
    // Next.js will attempt to re-generate the page:
    // - When a request comes in
    // - At most once every 1 minutes
    revalidate: 60, // In seconds
  }
}

It means that suppose we have 50 posts, every hour will call the API 3600s / 60 * 50 issues = 3000 times, which is under the 5000 request per hour rate limit.

The benefit of using GitHub issue as the content base over markdown files on project is GitHub issue comes with reaction and comments that we can show on the blog post (this feature is still working in progress).

Step by step guide

Before creating a Sairin blog, you need to generate a personal access token with the repo scope:

Then click the deploy button below:

This button will direct you to create a new project on Vercel based on Sairin template.

Enter a project name and click create, then enter the personal access token you generated before and click deploy, it will begin to deploy your blog.

After building you can open the repo that was created by Vercel on the dashboard, all your blog posts will be fetched on this repo:

Publish your first post 🚀

To publish a post, just create an issue on the repo. Notice that you need to add a frontmatter on the top of the content, to specify a permalink of your post, for example:

---
path: introducing-sairin
---

Issues on the repo would not be published by default unless you add a label published to the issue:

Now, the first post should be published. You can go to the domain that Vercel gave to your project to see your blog post. No need to redeploy the project.

Read the full document on https://github.com/djyde/sairin

Pagination

Is that possible to provide the pagination?
(btw, thanks for this awesome project :))

你这本地跑不起来呀，大仓没有package.json？是不是漏了？

还是说这packages/ 下的都是独立的，主题需要自己发布包？

Links for prev/next articles

Will there be links for prev/next articles? It's convenient for reader to navigate between articles if there's prev/next article links.

Styling

Hi Randy

First off, this project is awesome... how can i style this project?

using on-demand ISR for real time update

see https://nextjs.org/blog/next-12-1#on-demand-incremental-static-regeneration-beta

Images in the article are not displayed due to 404 errors

Hello,

I noticed that the images in the article are not being displayed correctly, and they are showing 404 errors. It seems that GitHub might have made some updates that affect the image URLs.

Could you please look into this issue and update the image URLs or find an alternative solution to display the images properly? This would greatly improve the readability of the article and provide a better user experience.

Thank you for your attention to this matter.

Best regards,
Tim

Update: Reactions and Comments support

---

path: reactions-and-comments

As you can see on this blog post page, reactions to the issue post were displayed above the blog content, and comments to the issue were displayed below the blog content.

How to upgrade?

Just redeploy your Sairin blog on Vercel.

support issue labels for blog tag

we may use the issue label for blog tag, it should be pretty!

Still show the hiding comment

I can hide some comment ：

However when I hide the comments, in my Blog, it still shows up.

This is amazing, I can build a blog post by using Github Issues

add .prettierrc for better code style consistency