planet-template-github

一个用于 Planet 的 GitHub 风格模板。模板把 Planet 站点渲染成类似 GitHub Profile/Repository Overview 的页面：左侧是个人资料栏，右侧是 Overview、Pinned posts、年度贡献图和文章活动列表。

样式

Demo：https://uhufoundme.sol.build/

目录结构

github/
  template.json                 # Planet 模板元信息
  assets/                       # CSS 和图标资源
  templates/
    base.html                   # 全站基础布局：顶部栏、搜索、左栏、主内容区
    index.html                  # 首页 Overview
    archive.html                # Posts 列表页
    blog.html                   # 单篇文章页
    modules/                    # 可复用模块

怎么使用

1. 将 github 文件夹放到 Planet 的模板目录 /Applications/Planet.app/Contents/Resources/PlanetSiteTemplates_PlanetSiteTemplates.bundle/Contents/Resources/Resources中。
2. 在 Planet 中选择这个模板，模板名称来自 github/template.json 里的 name 字段，目前是 GitHub。
3. 在 Planet 中设置站点名称、头像、描述、社交账号等信息。
4. 发布文章后，Planet 会用 github/templates 下的模板生成静态页面。

模板配置在 github/template.json：

{
  "name": "GitHub",
  "description": "A GitHub-style Planet theme for Planet",
  "idealItemsPerPage": 1000,
  "generateIndexPagination": false,
  "generateTagPages": false,
  "generateArchive": true
}

其中 generateArchive: true 会生成 archive.html，也就是顶部 Posts 标签页指向的页面。

页面展示逻辑

全站结构由 github/templates/base.html 控制：

• 顶部栏：GitHub 图标和搜索框。
• 左栏：modules/profile_sidebar.html。
• 右侧导航：modules/top_nav.html，包含 Overview 和 Posts。
• 主内容区：由具体页面模板填充。

首页由 github/templates/index.html 控制，展示顺序是：

1. modules/readme_panel.html：README.md 面板。
2. modules/overview_pinned_posts.html：Pinned posts。
3. modules/overview_year_posts.html：年度文章贡献图。
4. modules/overview_activity.html：按年月分组的文章活动。

文章列表页由 github/templates/archive.html 控制，支持按标签筛选。单篇文章页由 github/templates/blog.html 控制。

左栏内容分别用的是什么

左栏文件是 github/templates/modules/profile_sidebar.html。

当前左栏内容来源如下：

展示内容	使用变量或写死内容	修改位置
头像	has_avatar、avatar.png	Planet 站点头像
名称	planet.name	Planet 站点名称
GitHub handle	planet.githubUsername	Planet 设置里的 GitHub 用户名
简介	page_description_html	Planet 站点描述
Follow 按钮	rss.xml	模板中固定指向 RSS
位置	Zhengzhou, China	profile_sidebar.html 中写死
时区	Asia/Shanghai、UTC +08:00	profile_sidebar.html 中写死
邮箱	leon6line@gmail.com	profile_sidebar.html 中写死
网站	https://www.lazydaily.cn/	profile_sidebar.html 中写死
Podcast	has_podcast、podcast.xml	Planet 是否有播客
Twitter	planet.twitterUsername	Planet 设置
GitHub	planet.githubUsername	Planet 设置
Telegram	planet.telegramUsername	Planet 设置
Farcaster	planet.farcasterUsername	Planet 设置
Discord	planet.discordLink	Planet 设置
Juicebox	planet.juiceboxEnabled、planet.juiceboxProjectID、planet.juiceboxProjectIDGoerli	Planet 设置

如果要改左栏的固定信息，例如位置、邮箱、个人网站、时区，直接改 github/templates/modules/profile_sidebar.html。如果要改样式，改 github/assets/style.css 中 .profile-* 相关样式。

README.md 展示逻辑

首页的 README 面板在 github/templates/modules/readme_panel.html。

它的标题显示为 README.md，但内容不是读取本仓库的 README.md 文件，而是读取 Planet 文章列表中标题精确等于 README 的文章：

{% for article in articles where article.title == "README" %}
  {{ article.contentRendered }}
  {% break %}
{% empty %}
  ...
{% endfor %}

因此，站点首页想展示 README 内容时，需要在 Planet 中发布一篇标题为 README 的文章。文章正文会通过 article.contentRendered 渲染到首页 README 面板中。

注意：

• 标题必须是 README，不是 README.md。
• 只展示第一篇匹配的文章，因为模板里用了 {% break %}。
• 普通文章列表、贡献图、活动列表会排除标题为 README 的文章，避免 README 被当作博客文章展示。
• archive.html 还额外排除了标题为 README.md 的文章。

如果你想让首页读取标题为 README.md 的文章，可以把 readme_panel.html 中的条件改成：

{% for article in articles where article.title == "README.md" %}

如果想同时支持 README 和 README.md，需要改成普通循环并在循环内部判断标题。

Pinned Posts 如何实现

Pinned posts 面板在 github/templates/modules/overview_pinned_posts.html。

模板会先遍历所有文章，给每篇文章输出一个卡片，并把 Planet 的置顶状态写到 data-pinned：

<article class="pinned-post-card" data-pinned="{{ article.pinned }}">

页面加载后，前端脚本读取 data-pinned。如果值为空、0、false、nil 或 null，就删除这张卡片；否则保留：

const value = (card.dataset.pinned || '').trim().toLowerCase();
const isPinned = value && value !== '0' && value !== 'false' && value !== 'nil' && value !== 'null';

所以 Pinned Posts 使用的是 Planet 的文章变量：

article.pinned

实现置顶的方法是在 Planet 中把文章标记为 pinned/置顶。模板不通过标签、标题或日期判断置顶，只认 article.pinned。

如何修改

常见修改位置：

想修改	文件
首页模块顺序	github/templates/index.html
全站布局、顶部搜索、左栏挂载位置	github/templates/base.html
左栏个人资料	github/templates/modules/profile_sidebar.html
README 面板逻辑	github/templates/modules/readme_panel.html
Pinned posts 逻辑	github/templates/modules/overview_pinned_posts.html
年度贡献图	github/templates/modules/overview_year_posts.html
文章活动列表	github/templates/modules/overview_activity.html
Posts 列表页	github/templates/archive.html
单篇文章页	github/templates/blog.html
样式	github/assets/style.css
模板名称、生成选项	github/template.json

改模板逻辑时优先使用 Planet 已提供的变量，例如 planet.name、articles、article.title、article.link、article.created、article.tags、article.pinned。改静态信息时，直接修改对应模块中的 HTML。

鸣谢

本模板样式大多参考了github-style，再次特别鸣谢！