命令行微博客,可订阅RSS,可自定义模板发布静态网站

命令行微博客,可订阅RSS,可自定义模板发布静态网站

Property
Aug 23, 2022 08:50 PM
地址
https://github.com/ahui2016/pypelago
notion image

notion image

ipelago (in Python)

CLI personal microblog (命令行个人微博客)
纯命令行操作,包括两方面功能:
  1. 写微博客并生成静态网站 (HTML 和 RSS)
  1. 订阅别人的 RSS

ipelago 之名

ipelago 源于群岛的英文 archipelago, 如果我们每一个人是一座孤岛,那么当我们搭建自己的微博客,大家的微博客聚在一起就可以形成群岛。

主要功能 (写微博客、订阅 RSS)

写自己的微博客

  • 多种方式方便写博文(包括命令行输入、获取剪贴板内容、获取文件内容、通过简陋的 GUI 窗口输入)。
  • 可生成静态网站 (包括 HTML 和 RSS), 这些静态文件可通过 GitHub Pages 或类似的免费服务搭建你的私人微博客供别人浏览、订阅。
  • 生成 HTML 的模板、样式可以自定义(自带一个简单模板)。
  • 可区分公开消息与隐私消息,只有公开消息才会对外发布,隐私消息只能本地浏览。
  • 有简单的 #标签 功能与搜索功能。

订阅别人的微博客

  • 可通过 RSS 订阅别人的微博客。
  • 只支持微博客(一条消息只有一两句话),不支持正常博客(长文章),因此数据库体积不会暴涨,长期使用也能一直保持很小的体积。
  • 有限订阅(意思是不保存全部订阅消息,看到特别喜欢的内容可执行收藏命令,收藏的消息才会永久保存)。有限订阅可避免储存大量无用信息,避免数据库体积暴涨,减少信息焦虑。
  • 可设置 proxy, 方便与翻墙软件搭配使用。

减少烦躁和焦虑

一般通过 App 或网页浏览消息时,会一目十行,快速上下滑动消息列表,这种操作有可能使烦躁和焦虑感变得更严重。
ipelago 也可一次列举多条消息,但更提倡使用逐条浏览功能,每次只显示一条消息,并且可以记住位置,随时离开去做别的事情,回头继续从上次中断的地方接着阅读。
因此,有助于减少烦躁与焦虑。

安装与初始化

ipelago 使用了 Python 3.10 的新特性,比如 type union operator, pattern matching 等,因此,如果你的系统中未安装 Python 3.10, 推荐使用 pyenvminiconda 来安装最新版本的 Python。
例如,安装 miniconda 后,可以这样创建 3.10 环境:
$ conda create --name py310 python=3.10
$ conda activate py310
安装非常简单,只要 pip install ipelago 即可。
安装后,第一次正式使用前,必须执行 'ago init name' 进行初始化,其中 name 是你的微博客名称,对外发布时别人可以看到。

帮助

  • ago -h (查看帮助消息)
  • ago post -h (每个子命令也有详细的帮助消息)

初始化

  • ago init 别有洞天 (初始化,设定微博客名称为“别有洞天”)

写博文

  • ago post Hello World! (写一条公开消息, 可通过 HTML 及 RSS 对外发布)
  • ago post -pri/--private My password is abcd (写一条隐私消息, 仅本地可见)
  • ago post (发送剪贴板的内容)
  • ago post -g/-gui (弹出一个简陋的 GUI 窗口方便输入)
  • ago post -f/--file ./abc.txt (发送文件 abc.txt 的内容)

切换与删除

  • ago toggle id (切换公开/隐私,其中 id 是消息的 id)
  • ago delete id (删除一条消息)
注意,切换公开/隐私、或删除消息后,要重新 publish 发布消息,才能反映到静态网站中(关于发布静态网站,请看后面关于 publish 的章节)。

Timeline (阅读自己微博客)

  • ago tl (阅读下一条消息, 完全等同于 ago tl -next)
  • ago tl -zen (阅读下一条消息,专注模式)
  • ago tl -first (阅读最新一条消息)
  • ago tl -next (阅读下一条消息)
  • ago tl -go/--goto 2022-03-15 (跳到 2022年3月15日 或最接近这天的消息)
  • ago copy id (复制指定 id 的博文内容)
以上命令包括(且只包括)公开消息与隐私消息。 以下命令可区分公开/隐私/收藏 (其中 '-today' 与 '-yesterday' 不可与 '-fav' 搭配使用) ('-date' 与 'count' 可与 '-fav' 搭配使用)。
  • ago tl -today (阅读今天的消息,包括公开与隐私,不包括收藏)
  • ago tl -yesterday (阅读昨天的消息,包括公开与隐私,不包括收藏)
  • ago tl -today -pub/--public (阅读今天的消息, 限定公开消息)
  • ago tl -today -pri/--private (阅读今天的消息, 限定隐私消息)
  • ago tl -fav/--favorite (阅读最近几条收藏消息)
  • ago tl -date 2022-03-15 (阅读 2022年3月15日 的消息, 默认上限 9 条)
  • ago tl -date 2022-03 (阅读 2022年3月 的消息, 默认上限 9 条)
  • ago tl -date 2022 -pri -limit 20 (阅读 2022年 的隐私消息, 最多只显示上限 20 条)
  • ago tl -count 2022-03 (统计 2022年3月 的消息条数)
  • ago tl -count all (统计全部消息条数,包括公开与隐私,不包括收藏)
  • ago tl -count all -pub (统计公开消息的条数)

订阅 RSS

  • ago news -follow https://douchi.space/@mtfront.rss (订阅长毛象)
  • ago news -follow https://m.cmx.im/@guobetty.rss (一般来说,长毛象的 rss 地址就是在用户地址后面直接加 '.rss' 即可) (注意,这个源要翻墙,可参考下面 Proxy 章节设置代理)
  • ago news -follow https://v2ex.com/feed/create.xml -p HasTitle (订阅V站的“分享创造”节点)
  • ago news -follow https://geeknote.net/Rei/feed.atom -p HasSummary (订阅 geeknote)
  • ago news -follow https://sspai.com/feed --parser HasTitle (订阅少数派)
  • ago news -l/--list (查看已订阅的 RSS 列表)
  • ago search -feeds (完全等同 ago news -l)
  • ago search -feeds keyword (查找源标题里包含 keyword 的源)

关于 parser

默认采用 '--parser Base' 解析 RSS 内容,舍弃每篇博文的 title (因为有时 title 与正文重复)。
建议先看看 RSS 源文件,看 title 有没有必要显示,如果需要保留 title, 可使用以下命令订阅:
  • ago news -follow [url] -p/--parser HasTitle
在订阅后,也可更改解析器:
  • ago news -u/--update [id] -p/--parser HasTitle
有的 RSS 源文件在提供 <content> 的同时也提供 <summary>, 对于这种情况,建议采用 '--parser HasSuammry'。

Proxy (代理)

  • ago -i/--info 查看当前 proxy 设定。
  • ago --set-proxy [url] 设置代理网址(有些 rss feed 需要翻墙才能订阅)
  • ago --set-proxy true 启用代理。
  • ago --set-proxy false 不使用代理。
例如: ago --set-proxy http://127.0.0.1:1081 (注意网址要以 http 开头)

改名

改名可以让消息看起来更清晰(显示每条消息时,都会注明源的名称)。
$ ago news -follow https://v2ex.com/feed/create.xml -p HasTitle

[R9DX70] 分享创造
https://v2ex.com/feed/create.xml

$ ago news -feed r9dx70 --set-name 分享创造-V2EX

[R9DX70] 分享创造-V2EX
https://v2ex.com/feed/create.xml

改 ID

改 ID 可以方便后续操作(比如指定阅读一个源的消息、强制更新指定的源,都需要用到 ID)。
$ ago news -follow https://sspai.com/feed -p HasTitle

[R9ELEZ] 少数派
https://sspai.com/feed

ago news -feed r9elez --set-id sspai

[sspai] 少数派
https://sspai.com/feed

更新

默认每个源每 24 小时只能更新一次,可使用 '-force' 参数强制更新,但为了尊重源站节约资源及减少焦虑,建议不要频繁更新。
    • 每次只能强制更新一个源,不可强制批量更新
    • 而且也不是自动更新,需要手动执行以下命令才会更新
    • 一旦更新,未收藏的消息就会被新消息覆盖(即,不保留旧消息)。
    • 遇到特别喜欢的消息可使用命令 'ago like id' 收藏,永久保存。
    • ago news -u/--update all (批量更新全部源)
    • ago news -u sspai (更新 feed id 为 sspai 的源)
    • ago news -force -u id (强制更新指定 id 的源)

阅读消息

    • ago news (阅读下一条消息, 完全等同 ago news --next)
    • ago news -first (阅读最新一条消息)
    • ago news -next (阅读下一条消息)
    • ago news -zen (阅读下一条消息, 专注模式)
    • ago news -go/--goto 2022-03 (跳到 2022年3月1日 或最接近这天的消息)
    • ago news -feed id (阅读指定 id 的源的消息,默认上限 9 条)
    • ago news -feed id -limit 3 (阅读指定 id 的源的消息,最多显示 3 条)
    • ago news -like id (收藏指定 id 的消息)
    • ago like id (完全等同于 ago news -like id)
    • ago news --toggle-link (显示/隐藏消息本身的链接)
    • ago copy id -link (复制指定 id 的消息的链接)

删除(源/消息)

  • ago news -delete id (删除一个源及与其相关的消息,已收藏的消息不会被删除,其中 id 是指用 'ago news -l' 看到的 id)
  • ago delete id (删除一条消息,其中 id 是指 消息的 id)

发布微博客

使用 'ago publish' 命令可生成 HTML 文件及 RSS 文件,通过 GitHub Pages 或类似的免费服务即可创建你的个人微博客网站。
第一次发布时,需要填写微博客名称、作者名称等信息。
    • ago publish -info (显示微博客信息)
    • ago publish -g (打开 GUI 窗口填写微博客信息)
    • ago publish --set-title ([必填] 设置 RSS 的标题,即你的微博客名称)
    • ago publish --set-author ([必填] 设置作者名)
    • ago publish --set-link ([必填] 设置 RSS 的链接)
    • ago publish --set-website ([选填] 设置任意网址, 通常是你的个人网站或博客的网址)
    • ago publish (默认输出静态文件到当前目录的 'public' 文件夹,默认每页 50 条消息)
    • ago publish -out /path/to/dir -n 25 (输出静态文件到指定文件夹, 每页显示 25 条消息)
title, author, link 这三项信息都必须有内容,才能执行 ago publish 命令生成网站文件。但可以先随便填,生成后看看效果,以后可以随时修改这些信息。
其中 link 是指别人通过 RSS 订阅这个微博客的网址,请务必后续发布到到网上后找到正确的网址,再回头修改。
生成文件后,双击其中的 'index.html' 即可预览效果(我用了很简单的样式,懂前端的朋友可自行修改样式)。

自定义模板

由于 ipelago 只处理微博客(每篇博文一两句话),不处理正常博客(长文章),因此 HTML 模板可以非常简单,自带的模板一共只有 62 行。可见,这个模板是非常容易看懂的,如果有不满意的地方,也就非常容易修改。
执行 'ago publish' 命令,可以看到默认模板 (Templates) 文件夹的位置,把这个文件夹复制粘贴到另一个地方,就可以自由修改了。修改后,使用参数 '-tmpl' (或 '--templates') 指定 templates 文件夹的位置:
  • ago publish -tmpl ..my_tmpl ('-tmpl' 后面的文件夹可以使用相对路径、也可以使用绝对路径)
注意,模板文件夹内必须包含 'index.html' 和 'atom.xml' 这两个模板文件,内容采用 Jinja2 语法。

Tags and Search (标签与搜索)

标签必须以“井号”开头,以空格结尾,并且不超过 TagSizeLimit (注意:并不是加了井号就一定能形成标签,必须以 "#" 开头,以空格结尾,并且不超过长度上限才能形成标签。)
例:以下命令发表了一条消息,同时关联了标签 'cde', 由于 '#' 是特殊字符,因此消息内容需要用半角双引号括住。推荐使用 'ago post -g' 打开 GUI 窗口方便输入(在 GUI 窗口中不需要用双引号括住内容,可随意输入任何特殊字符)。
ago post "abc #cde efg"
  • ago search keyword (自动优先采用 '-tag' 方式搜索,如果没有结果再自动改成 '-contain' 方式搜索)
  • ago search -tag/--by-tag [tag] (通过标签搜索消息,效率较高)
  • ago search -contain keyword (搜索内容包含 keyword 的消息,效率较低)
以上命令默认包括 公开(public)/隐私(private)/收藏(fav)/订阅(news) 四种消息,但都可以加 '-bucket' 参数限定只搜索其中一的消息,例如:
  • ago search abc -bucket fav (在收藏消息中查找包含 'abc' 的消息)
  • ago search cde -bucket public (在我的公开消息在查找包含 'cde' 的消息)
以上命令默认最多列出 9 条结果,可加参数 '-limit' 更改上限,例如:
  • ago search keyword -limit 30
以上命令是搜索消息内容的,以下命令可搜索源与标签本身。
ago search --all-tags 列出全部标签 ago search --all-tags keyword 在全部标签中查找包含 keyword 的标签名 ago search --all-feeds 列出全部已订阅的源,等同 ago news --list ago search --all-feeds keyword 查找源名称中包含 keyword 的源
例如 ago search --all-tags java 可以找到标签 'Java' 和 'JavaScript', 而不是查找与这些标签关联的消息。

特殊技巧

特殊的订阅方法

我遇到了一些 rss feed 受到 Cloudflare 的保护而无法通过 python requests 访问,但可以用浏览器直接访问,比如这个 https://mstdn.jp/@nekodayo.rss
对于这种情况,可以用浏览器访问,按 Ctrl+S 保存 rss 到本地,建议保存到一个固定的文件夹,比如我保存在 D:\rss_feeds 里。
然后就可以这样订阅 ago news -follow D:\rss_feeds\@nekodayo.rss
但问题也很明显,后续需要手动下载 rss 覆盖同名文件才能更新内容,先这样应付吧,以后再想别的办法。

Zen Mode (专注模式)

我自己很喜欢这个模式,简单来说只是自动清屏而已,效果是减少浮躁,使人宁静。 'ago tl' 系列命令与 'ago news' 系列命令可使用专注模式,例如:
  • ago tl -zen
  • ago news -zen
也可以使用命令 'ago -zen/--toggle-zen' 切换默认开启/默认关闭 zen mode。

Info (软件信息)

使用命令 'ago -i/--info' 可查看程序位置、版本、数据库文件位置、zen mode 是否默认打开、代理 等信息,例如:
$ ago -i/--info

[ago] D:\ComputerScience\Python\myprojects\pypelago\src\ipelago\main.py
[version] 0.0.1
[database] C:\Users\ahui\AppData\Local\github-ahui2016\pypelago\pypelago.db
[Zen Mode Always ON] False
[http_proxy] http://127.0.0.1:1081
[use_proxy] False
[repo] https://github.com/ahui2016/pypelago

参考:我的微博客

我用这个程序生成的微博客,采用自带的极简模板(我实在不擅长前端,但懂前端的人可以看上面 "自定义模板" 的章节,很容易修改)。

更新日志

v0.0.6

  • feature 新增了 ago tl -count all -pub 统计公开消息的条数,方便使用 ago publish 命令时决定每页显示多少条消息。

v0.0.5

  • fix 修复了订阅 news.ycombinator.com/rss 时解析日期格式失败的问题。
  • fix 修复了 'ago search -feeds' 无结果时提示消息的一个小 bug。

v0.0.4

  • fix 在订阅某个博客时 (https://blog.gimo.me/index.xml) 发现了 <a> 链接的文字描述里含有 <svg> 并因此导致提取纯文本后产生多个换行符的问题,已修复。

v0.0.3

  • fix 修复了 HTML 与 atom.xml 的更新日期问题(原本以执行 'ago publish' 命令的时间为准,现在以最新一条公开消息的发表日期为准)