静态博客程序gitsite

GitSite.org是一个复古建站系统，它可以把Git管理的Markdown文档转换为纯静态的HTML网站，再非常便利地部署到GitHub Page、GitLab Page、CloudFlare Page、AWS S3、Vercel等。

为什么要用Git来管理Markdown文档呢？因为一个传统的CMS系统，例如WordPress，文档都是存储在数据库里的，因此，必须提供一个后台编辑系统，让用户能写文档 / 更新 / 发布，这就涉及到后台系统的增删改查、版本管理、权限管理、在线编辑器、图片上传……等等。

而Git天生就可以跟踪版本，本地可以用任何编辑器编写文档，也可以在GitHub上实时编辑，可以说直接替代了CMS的后台功能。

因为GitSite站点没有数据库，所以就不存在维护数据库/备份等问题了，Git仓库天生就是分布式备份。

因为是纯静态网站，所以也不存在搭建应用服务器的问题，不想自己维护可以扔到GitHub Page、S3上托管，想自己维护也就是一个Nginx就能跑起来。

通过Markdown扩展，GitSite目前支持图表，数学公式，二维码，甚至乐谱。

为了解决搜索问题，GitSite直接用Flexsearch生成静态索引文件，在浏览器前端直接实现实时搜索。

当然，传统的CMS也是非常有用的，因为GitSite是专为开源站点设计的，它仅适合规模不大的文档 / 博客 / 书籍 / 公众号备份等。

访问https://gitsite.org
https://gitsite.org/books/gitsite-guide/introduction/index.html
https://github.com/michaelliao/gitsite

--------------------------------------------------

Install and Deploy

Install GitSite command line tool

Use npm to install GitSite command line tool:

$ npm install -g gitsite-cli

Setup a new site

First create an empty directory which will be used as your site's root directory and also a git repo. Let's name it as awesome:

$ mkdir awesome

Run gitsite-cli init under the awesome directory:

$ cd awesome
$ gitsite-cli init

The GitSite command line tool does the following job to initialize your new site:

1. Check if current directory is an empty directory;
2. Download sample site from GitHub;
3. Unzip the sample site.

Now you can find the following files and directories under your awesome directory:

awesome/
├── themes/       <-- all themes
│   └── default/  <-- a theme named 'default'
│
└── source/       <-- contains all markdown docs
    │
    ├── books/            <-- all books
    │   ├── user-guide/   <-- a book
    │   │   ├── book.yml  <-- book name, author and description
    │   │   ├── 10-introduction/  <-- chapter order and short name
    │   │   │   ├── README.md     <-- chapter content
    │   │   │   └── test.png      <-- static resources used in the chapter
    │   │   ├── 20-installation/  <-- chapter
    │   │   │   ├── README.md
    │   │   │   ├── 10-create-repo/  <-- sub chapter
    │   │   │   │   └── README.md
    │   │   │   ├── 20-workflow/     <-- sub chapter
    │   │   │   │   └── README.md
    │   │   │   └── 30-deploy/       <-- sub chapter
    │   │   │       └── README.md
    │   │   └── ...  <-- more chapters
    │   └── ...  <-- more books
    │
    ├── blogs/     <-- all blogs
    │   ├── tech/  <-- tag
    │   │   ├── 2024-01-01-hello/  <-- blog date and short name
    │   │   │   ├── README.md      <-- blog content
    │   │   │   └── hello.jpg      <-- static resources used in the blog
    │   │   └── ...                <-- more blogs
    │   └── ... <-- more tags
    │
    ├── pages/             <-- all pages
    │   ├── license/       <-- about page
    │   │   └── README.md  <-- page content
    │   └── ...            <-- more pages
    │
    ├── 404.md       <-- display as 404 page if not found
    ├── README.md    <-- display as home page
    ├── favicon.ico  <-- favorite icon
    ├── site.yml     <-- site config
    └── static/      <-- static resources
        ├── custom.css
        ├── logo.png
        └── ...

Preview site on local

Run gitesite-cli serve to start a local HTTP server to serve the site:

$ gitsite-cli serve

Then you can visit your site on http://localhost:3000:

Update site settings

The site settings are stored in source/site.yml. You should update the settings:

• Set your site's name, description, etc;
• Set your site's navigation menus;
• Set your Disqus, Google analytics ID, or just remove it.

Deploy to GitHub page

To deploy site to GitHub page, first create a repo on GitHub and push your local files to the remote.

To enable GitHub page, go to repo - Settings - Pages - Build and deployment: select GitHub Actions.

Make a new push to trigger the Action for deployment.

The workflow script file is .github/workflows/gitsite.yml. Check the sample gitsite.yml.

Deploy to CloudFlare page

To deploy site to CloudFlare page, create application from GitHub repo, then open application settings - Builds & deployments - Build configurations - Edit configurations:

• Framework preset: None
• Build command: npm install gitsite-cli -g && gitsite-cli build -o _site -v
• Build output directory: /_site
• Root directory: leave empty.

Deploy to Vercel

To deploy site to Vercel, create a new project by import GitHub repo, then configure project:

• Framework Preset: Other
• Root Direction: ./

Build and Output Settings:

• Build Command: npm install -g gitsite-cli && gitsite-cli build -o dist -v
• Output Directory: dist
• Install Command: leave empty.

Deploy to Self-hosted Nginx

GitSite generates pure HTML files by command gitsite-cli build. You can specify the output directory (default to dist) by --output or -o:

$ gitsite-cli build -o dist -v

Copy all files in dist to Nginx www directory, edit the server configuration:

server {
    listen       80;
    server_name  change.to.your.server.name;
    root         /path/to/gitsite/dist;
    index        index.html;
    error_page   404 /404.html;

    location / {
        try_files $uri $uri/ =404;
    }
} 

from https://gitsite.org/books/gitsite-guide/install/index.html