Gekyll - GitApk 的静态网站生成程序

Gekyll 的命名来源于 Jekyll，一个使用 Ruby 编写的静态博客网站生成器

Jekyll：将纯文本转换为静态博客网站

而 Gekyll 则是一个 Crystal 程序，类似于 Jekyll，它生成静态网站，不过，它为 GitApk - 基于 Gitea 等服务的 GeekApk 网站生成静态页面

Gekyll：将 Markdown、纯文本和 YAML 元数据 渲染为静态 GeekApk 网站

GitApk 对于大部分可以静态生成的数据，包括客户端索引，进行静态渲染。而对于无法静态的页面则使用 r.html 重定向到其真正的实现（实际上，内部进行的大多数跳转都会使用 r.html），完成了解藕合的任务

Gekyll 只需要渲染 主页、分类页、用户页，生成查询数据即可

GitApk package tree 结构类似于这样

系统工具/ # 分类
  dir/ # 将作为应用的「简单名」使用
    README.md # readme
    screenshots.yml # screenshots
    metadata.yml # metadata
    latest # latest reversion
    issue # comment board issue no
    updates/ # app updates
      0.1.0/ # version 0.1.0
        reversion # reversion
        metadata.yml # metadata
        README.md # updates
Foo/ # 另一个分类
  bar/ # bar 应用
  # ...
gekyll.yml # 包含各种选项的文件

对于应用来说，它支持 aid、package、description、author、name、readme、icon、screenshots、created、updated、issue、latest 字段

aid、package、name 是必须的，生成结果作为 默认 Tree

对于更新，支持 reversion、minsdk、install、created 字段，reversion 是必须的

GitApk 会占用一个源作为自己的「默认 Tree」，这个源要包含 /r.html 文件来进行重定向 GitApk 也会占用每个用户的一个源作为自己的「用户元数据源」

GitApk 渲染时要能分「获取 Gitea Comments 统计数据」、「生成 App 视图」、「生成应用别名跳转」、「生成分类」、「生成 rank 排行分类」、「生成分类索引」、「生成主页」、「生成索引」、「生成元数据」、「生成 r.html」阶段

用户元数据

$MR 默认为 GitApk-Metadata

/:username/$MR/raw/branch/master/README.md
/:username/$MR/raw/branch/master/nickname
/:username/$MR/raw/branch/master/avatar

/:username/$MR/raw/branch/master/stars

/:username/$MR/issues/1

生成结果

/packages/:package # 重定向
/:simplename # 重定向
/apps/:aid
/categories
/categories/:name
/categories.rank/:name
/main

生成元数据

/metadata/reversion.csv
/metadata/package.csv
/metadata/name.csv
/metadata/author.csv
/metadata/description.csv
/metadata/apps.json
/metadata/app/:package.json
/metadata/updates.json
/metadata/updates/:package/:reversion.json

默认 Tree 的 index.html 应该重定向到 r.html?type=index

其他操作都必须由 r.html 进行，动态的重定向到需要的 HTML 那里

r.html 接受 url 参数 type 来基于 JavaScript 进行动态重定向到指定视图

钦定有这些默认派发视图

about
doc
index
comments(aid)
user(username)
userlist
category(name)
categories
main
package(aid)
timeline(username)
notifications
timeline
stargazers
followers(username)
following(username)
update(aid, reversion)
updates(aid)
comment(aid, nth)
plugins
plugin_install(gist_id)
plugin_remove(name)
redir_plugin(gist_id)
redir(url)

Gekyll 配置文件

# gekyll.yml gekyll.yaml config.yml config.yaml .gekyll.yml .gekyll.yaml

fake_version:
  gekyll: 0.1.0
  crystal: 0.25.1

url:
  base: https://gitapk.popf.rip/o_o/gitapk
  api: https://gitapk.popf.rip/api/v1
  api_render:

name:
  tree: o_o/gitapk
  user: GitApk-Metadata
  nickname: nickname
  bio: README.md
  avatar: avatar
  stars: stars
  issue: 1
  redir: r.html

default_values:
  description:
  author:
  readme:
  icon:
  screenshots:
  created:
  updated:
  issue:
  latest:
  minsdk:
  install:
  update_created:

input: src
output: out
# 0: normal -1: quiet 1: verbose 2: debug
verbose: 0

supress: false

categories:
  sysadmin: 系统工具

outputs:
  metadata:
  categories:
  category:
  category_rank:
  apps:
  package:
  short_links:
  main:

no_meta:
  - reversion
  - name

recpies:
  - all
  - clean

coding: utf8
timezone: Asia/Shanghai
safe: false

copy: true

simplename: dir # file

template: erb # ehtml # cmdline # dlopen

templates:
  app: app.ehtml
  main: generate_main
  categories: categories.so
  category:
  redir:

plugins:
  - foo.so

Gekyll 项目结构

项目的根目录（src dir）

CategoryA/
CategoryB/
# 优先级排序
gekyll.yml
gekyll.yaml
config.yml
config.yaml
.gekyll.yml
.gekyll.yaml
# 可能会有
r.html
# 其他文件被拷贝到输出目录下，如果允许

你可以在 gekyll.yml 中覆盖分类的名字

分类目录（in-cateogry dir）

dir/
mat/
fooApp/
barApp/
# 其他文件被拷贝到分类输出目录下，如果允许

分类目录下每个目录都是应用文件夹，文件夹的名字是默认的简单名

可以通过 simplename: file 切换为 simplename 文件模式，如果没有 simplename 文件会报错

应用目录（app dir）

README.md
screenshots.yml
metadata.yml
latest
issue
updates/
# 其他文件被拷贝到应用输出目录下，如果允许

更新目录（update dir）

0.1.0/
0.1.1/
0.2.0/

版本目录（version dir）

reversion
metadata.yml
README.md
# 其他文件被拷贝到输出目录下，如果允许

Gekyll 使用帮助

# Usage: gekyll [options] [recipes]
# 命令行参数将覆盖 yml 文件参数

gekyll -src src
gekyll -dst destination
gekyll -host 127.0.0.1 -port 8080 -unix ga.socket
gekyll -config a.yml
gekyll -plugin a.so
gekyll -safe

gekyll -version
gekyll -help [license | tree | server | plugins | usage | config | init]
gekyll -licnese
gekyll -showconfig
gekyll -tree [dir] [size|detail|bare]
gekyll -init [dir]

# recipes
gekyll fetch app alias categories categories.rank categories.index main indexes metadata redir all build clean watch serve server b s

Gekyll 插件

Gekyll 支持在能够 动态加载 的平台上（目前几乎是 100%，因为 ~~Crystal 还不支持 Windows~~）可以进行插件动态链接，插件当然是原生代码的，它支持使用 C 语言 编写插件

Gekyll lifecycle（recipe）插件

void a(char *config) {
    // ...
}

void Gekyll_addLifecycle(void (*add)(const char *, void (*)(char *))) {
    add("foo", &a);
}

Gekyll Preprocessor 插件

#define PROCESS_MAX 1024 * 1024 * 1

#define GA_README 0

#define GA_SHOTS 1

#define GA_MD 2

#define GA_LATEST 3

#define GA_ISSUE 4

#define GA_REVERSION 5

#define GA_UPDATE_MD 6

#define GA_UPDATE_README 7

char buffer[PROCESS_MAX];

// Executes in serial
char *Gekyll_Preprocessor(unsigned char type, char *app, char *file);

Gekyll Markdown 渲染器插件

#define MARKDOWN_MAX 1024 * 1024 * 2

char buffer[MARKDOWN_MAX];

// Executes in serial
char *Gekyll_markdownRender(char *markdown);

Gekyll config processor 插件

#define CONFIG_YAML_MAX 1024 * 1024 * 1

char buffer[CONFIG_YAML_MAX];

// Executes in serial
char *Gekyll_configProcessor(char *config);

duangsuse/gitapk.md