Permalink
Fetching contributors…
Cannot retrieve contributors at this time
229 lines (143 sloc) 8.85 KB

HubPress

什么是HubPress?

editor

HubPress 是一款在Github 上基于 AsciiDoc 建立个人博客的优秀的开源工具。

Anthonny Quérouil (twitter @anthonny_q) 开发和维护.

Note
HubPress目前是预览版本,如果您发现了Bug请及时告知我们.

在项目不断开发升级的过程中说明文档也会很快的更新,请定期查询以便得到最新说明。如果你发现了一些问题,请作为 bug 提交,我们感谢你在每一个方面的帮助,而且将会*永远*期待您的合作(pull requests)。

浏览器兼容性

HubPress 目前兼容 Chrome 桌面版, Firefox 桌面版和 Chrome Android 版.

Chrome Beta 的 Android 版将会很快兼容, 实际上是因为现在使用 IndexedDB 遇到了一些Bug, 预览的话请使用 Chrome 的 Android版。

快速上手

安装

Fork the repository

点击Fork图标 Fork 复制这个 repository 到你的 Github 账号下.

使用github.io的域名

如果你从来都没用过 Github 的个人静态主页,你可以通过以下方法来快速建立 HubPress 博客。只需要一些简单的步骤就可以实现博客的配置发布。

Important
如果你现在你的 username.github.io 的个人主页用于其他项目,或者你想用其他域名,请跳过以下步骤。
  1. 把repository重命名为 <username>.github.io

  2. 更改配置文件 hubpress/config.json

    Edit config

    以下的参数是必须的 :

    • username, 是你的GitHub用户名(username)。

    • repositoryName, 是你的folk的repository的名字, 如: <username>.github.io

  3. Commit所有更改, 然后打开你的GitHub主页: https://<username>.github.io/.

  4. 如果出现了这样的画面就说明你配置成功了。

    Install complete

使用其他域名或者当GitHub主页已被占用

如果你想让你的博客在自定义域名上使用,或者你已经用Github主页配置其他项目了,你需要做一些额外的配置。

  1. 在repository的settings选项中, 把默认branch设为 gh-pages :

    Settings gh-pages
  2. 现在设定当前repository的branch为 gh-pages

    Install complete

  3. 更新配置文件 hubpress/config.json

    Edit config

    以下的参数是必须的:

    • username, 是你的GitHub用户名(username)。

    • repositoryName, 是你的folk的repository的名字, 如: <username>.github.io

  4. Commit所有更改, 然后打开你的GitHub主页: https://<username>.github.io/<repositoryName>;.

  5. 如果出现了这样的画面就说明你配置成功了。

    Install complete

管理后台

你可以通过 /hubpress 进入管理后台

登陆管理后台

Install complete

输入你的GitHub账号密码来登陆HubPress的后台.

你登陆之后,一个个人的token(标记)会建立,在之后Hubpress调用Github API时将会用到。

这将同步用于Hubpress的所有session(会话)如你先在电脑上登录管理后台,然后在平板上登陆,所有的设备上都会使用这一个相同的token。

设置

你可以调整一下基础的设置(如CNAME和分页)和一些你希望链接到博客的社交账号。

基本设置

这部分包含一些配置 /hubpress/config.json 文件的基本信息.

以下选项可供更改:

Git CNAME

你可以更改*Git CNAME*给你的博客设定一个自己的域名,详细参见 Github官方 上设定CNAME的步骤。

Live Preview Render Delay(刷新延迟)

控制实时刷新的频率,以milliseconds(毫秒)计。对于打字快的人来说,设定到2000(2秒)就可以得到比较流畅的编辑体验,实时预览也不至于更新太快。虽然设定到2000以下可以更新的更快,但是可能在打字时导致游标的一些延迟。

网站设置

站名和介绍

Title(站名)和*Description*(介绍)项允许你设定自己的博客名,并且给出一个关于博客内容大致的介绍。

Logo and Cover Image(封面图片)的配置方法如下:

  • 可以用HTML链接到一个图片托管服务,比如 gravatar

  • 一个路径,指向你repository下的 /image 文件夹内的图片.

Note
请参照`/images/README.adoc` 里的提示来在你的博客中插入图片。
主题风格

Theme(主题)可以从 /themes 文件夹下的主题中进行选择。你可以通过文件夹的名称进行选择。

Google Analytics

Google Analytics (谷歌分析) 这里你填入Google Analytics生成的代码。

Disqus Shortname

Disqus shortname 这里你可以填入Disqus的URL或者shortnamere关联到你在Disqus上注册的站点。你需要填入shortname而不是到你Disqus个人主页的链接。

社交账号

这个组内的所有项都需要填入完整的URL账号以连接你的社交账号主页,这些参数的显示方式根据主题的选择而有所不同。

管理博文

当你初次进入Hubpress的时候,Posts(博文)一栏是空的。 当你创建博客的时候,左边一栏是博文列表,右边可以实时预览当前编辑的博文。

在HubPress写第一篇博客

Note
如果你从来没有用过AsciiDoc,推荐你首先去 AsciiDoctor Writer’s Guide 上提前感受一下。那里有各种基础和进阶的使用例子供你使用。

HubPress编辑器的左边是AsciiDoc代码,右边是实时预览。

博文名和标题

博文名(blog title)在AsciiDoc里是1级标题。比如说: = Blog Title 就是设定博文名为 Blog Title.

要想保存编辑的内容,博文名是必须的。

如果你想使用1级大标题,你可以使用如 == First Level Heading 来创建各级不同的标题(由“=”的数量决定)。

HubPress参数

HubPress 允许你通过参数改变每篇博文的设置。

:hp-image: 博文的封面图片

如果你想改变某篇博文的封面图片,请设置 hp-image 参数。

  1. :hp-image: 例子

= Blog Title
:hp-image: https://<repositoryName>/images/a-cover-image.jpg
Note
Hubpress默认的图片根文件夹为 /images ,所以只需要指定图片的名字就可以。你可以在repository下建立一个 /covers 文件夹来归档所有的封面图片。保持封面图片命名方法的一致可以让你的管理更方便。此外,在向读者提供关于博文的直观信息上,封面图片是一个很好的选择。

现在支持在博文中插入封面图片的主题有:

  • Saga

:published_at: 改变发布日期

发布日期默认是你创建博文的日期,你可以通过设定添加 :published_at: 参数来强制改变它。

  1. :published_at: 例子

= Blog Title
:published_at: 2015-01-31
:hp-tags: 元数据标签
Note
这里不支持 Categories(类别)标签

Add tags by using the hp-tags attribute. 通过使用 hp-tags 参数来增加标签

  1. :hp-tags: 例子

= Blog Title
:hp-tags: HubPress, Blog, Open Source,
:hp-alt-title: 设定第二名称

通过 hp-alt-title 给博文指定一个第二名称。

Hubpress就可以用该名称来作为文件名创建博文,从而避免因为其他语言导致的问题。

  1. :hp-alt-title: 例子

= 大千世界
:hp-alt-title: My English Title

故障解决

如果出现了问题,下面的一些建议可能会有用:

在Android上重新建立博客数据库

有时Hubpress可能不能及时更新你发布的博文,这可能是因为你在PC上写了博文,然后又在平板上更改造成的。

HubPress使用的浏览器原生的数据库,所以如果你频繁的转换使用设备,浏览器之间的同步可能就会出现问题。

如果暂时不能查看HubPress刚发布的博客,你可以在 Settings > Apps 里清空浏览器的缓存和数据,让浏览器就会重置数据库,以显示最新博文。

鸣谢

Thanks to Jared Morgan for initially tidying up the README you see here, and continuing to be the "docs guy" for HubPress.

中文: Hanwen Cheng