ISSUE BLOG

English / 中文

An easy-to-use, serverless-deploying, github-based blog theme.

Features

• Modern responsive design.
• Fully LaTex math support.
• Print friendly.
• SEO friendly.
• Use Github issues to organize your blog.
• No need for a server to host or deploy the blog pages.
• Login with Github accounts and comment to the posts.
• Well-designed resume page.
• Build your personal homepage in 3 minutes.

Why ISSUE BLOG?

With ISSUE BLOG, a web browser is the only tool you need to use to setup, deploy and write your personal blog.

How to Use

Below are just some of the methods for installing ISSUE BLOG. Do not follow all of these instructions; just pick your favorite one.

Simple Installation (without Fork)

.github
 |- workflows
    |- custom.js # site config
    |- cv.md # resume config
    |- main.yml # github actions config

1. Create the above files in your github.io repo, you can find the templates of these files at ./template;
2. Edit custom.js and cv.md according to Config Reference;
3. Edit main.yml, replace all <your-github-name> placeholder to your github account id.

Common Installation (with Fork)

1. Fork this project, and rename it to <your-github-name>.github.io;
2. Edit /src/.vuepress/custom.js to config your site, follow Config Reference.

Custom Installation

If you don't want to override your existing github.io repo, you can push the code to the source branch of your repo.

# 1. clone this project
git clone https://github.com/Yidadaa/Issue-Blog-With-Github-Action.git

# 2. change the remote url
git remote set-url origin your-remote-github.io-repo.git

# 3. push code
git push origin -u source

Then go to Settings -> Branches, and change Default branch to source branch, we host the source code in source branch and deploy the static pages to master branch.

Finally, edit /src/.vuepress/custom.js to config your site, please follow this section.

Config Reference

vssueConfig

Config for comment system, we use Vssue, so this part is same as Vssue doc.

{
  repo: String, // your github.io repo name
  owner: String, // your github id
  clientId: String,
  clientSecret: String
}

repoConfig

Config for push repo, here is the example:

{
  repo: String, // same as vssueConfig.repo
  owner: String, // same as vssueConfig.owner
  pushBranch: String, // which branch to deploy static pages, default is 'master' or 'main'
  email: String, // your email of github account, just for commit message
  filterUsers: Array<String> // filter issues according to github account ids
}

title

Your site's name.

description

Your site's description.

customDomain

Your personal domain, if you do not have a domain, fill it with empty string.

base

Root path for your site, refer vuepress guide for details.

slogan

Decorative texts in your home page.

{
  main: String, // top line
  sub: String // bottom line
}

themeConfig

Config for site theme.

{
  nav: [{
    name: String,
    link: String
  }], // navigation
  headTitle: [String], // Decorative texts in site header
  friendLinks: [{
    name: String,
    link: String
  }], // friend links in bottom footer
  extraFooters: [{
    title: String,
    text: String
  }], // extra texts in bottom footer
  pageCount: true // whether to show page report on footer or not
}

head

Please refer vuepress guide for details.

Hints: you can define the icon of the site here.

How to Develop

You need to create a new token here to develop and debug in local machine.

# 1. write your token to ./tools/config.js
cp ./tools/config.template.js ./tools/config.js
# edit ./tools/config.js with your favorite text editor, and copy your token to the file

# 2. install depencies
yarn install
yarn global add vuepress

# 3. fetch issues and save them to files
yarn run local

# 4. start to develop
yarn run dev

You can refer vuepress doc for more details.

FAQ

1. How to prevent others from publishing issues to the site?

You can set a white-list by setting repoConfig.filterUsers to ['Your Github ID', 'Another Friend's ID'], default setting allows everyone to post a blog to your site.

2. When updating the configuration, why GitHub Actions did not automatically run?

You can check the .github/workflows/main.yml file in your repository and ensure that the on->push->branches section corresponds to the branch where your code changes are made. Default branch was master, but now is main on GitHub.

3. GitHub Actions run successfully, but the repository code is not updated, and static page files are not added?

Please check the logs of your GitHub Actions and verify if the GITHUB_TOKEN has write permissions. If it does not, please refer to the official documentation about GITHUB_TOKEN and grant read and write permissions to your repository in .github/workflows/main.yml. Template file ./template/main.yml define read or write access for all of the available scopes.

Acknowledgment

• This project is based on vuepress.
• Visitor report is powered by busuanzi.