• Why Github?
  • Team
  • Enterprise
  • Explore
  • Marketplace
  • Pricing
Sign inSign up
Watch996
Star102.4k
Fork61.8k
Branch: working.beex.help
Switch branches/tags
Branches
Tags
  •  
K / Beex 入门教程(Getting Started).md
Go to Mobile Clone
加载中...
到移动设备上浏览
119 lines 9.76 KB
First commit on 7 Jun 2020

    为什么开发 Beex

    • 通常情况下,同样的内容,写作和发布时要转换不同的文件格式、重新排版、打包附件,很花时间,后续修订就更令人抓狂了。我想要“一次编辑,到处渲染”。如你所见,本站全站都是通过 Beex 渲染的。
    • 我的文档很多,并且有我自己的整理规则,我不能为了符合常见的配置要求把全部文件都放在同一个目录里。
    • 由于通用型静态站点生成器要严格遵守设计范式,导致几个功能很难实现,进而导致它们的目的虽然是通用,却最终只能将用户的文档集合构建成一个个精美的......博客。

    综上三点,我自己动手写了一个生成器,并给这个项目起名叫 Beex。

    通用型生成器的问题:

    1. 不支持多个根目录存储源文件。
    2. 不支持增量构建。
    3. 不支持映射标签的名字和 slug。(这个不难,但是英语母语的人不需要实现这个功能。)
    4. 文件名、标题、附件和最终生成的页面路径解耦不彻底。
    5. 构建速度慢。(有几个生成器很快,但上面的问题依然存在。)
    6. 大部分使用脚本语言编写,搭建环境和安装依赖不仅麻烦,而且占用大量空间。(Beex 0.1.0 的压缩包仅 1.39M。)

    Beex 主要针对上述问题探索解决之道,思路和细节可以参考《Beex 的设计哲学》。

    项目维护

    因为我的个人笔记系统是围绕 Beex 搭建的,所以这个项目会持续得到维护,不会烂尾。

    安装和初始化

    无需安装,下载(Download)后,双击 bx.exe 文件,会自动生成一些配置文件和文件夹,初始化就完成了。(你可能只是看到屏幕闪了一下。)

    配置

    Beex 是开箱即用的,如果你已经迫不及待了可以先跳过本节,稍后再回来设置。

    打开 _config.toml 文件(这是一个文本文件,你可以使用 Windows 自带的“记事本”打开它),你可以只编辑这三项:

    • title: 站点标题。
    • author: 作者名。
    • tagline: 站点副标题。

    注意不要误删引号,其余的参考 Beex 配置以及 BeexMeta

    三步生成一个站点

    new

    双击 start.bat,弹出控制台,你可以右键单击这个文件“发送到桌面快捷方式”(注意不是复制文件),方便使用。

    在控制台中输入下面的命令来新建一篇文章。

    bx new hello-world
    
    • hello-world 是要新建的文章名,用连字符而不是空格 space
    • 有时候因为有附件,需要同时新建一个文件夹,你可以增加 -d 标志,像这样:bx new -d my-second-article

    gen (generate)

    打开新建的文件,如果你没有 Markdown 编辑器,先用“记事本”打开它。

    你会看到一段被 <!-- BeexMeta--> 包裹起来的元信息,暂时不用管它们,在 --> 之后另起一行,随便写点什么,像下面这样:

    <!-- BeexMeta
    这里有一些元信息...
    -->
    
    # 你好,世界
    
    这是我的第一篇文章。
    

    别忘记 Ctrl + S 保存。

    回到控制台,输入:

    bx gen
    

    这将生成 HTML 文件。

    run (run server)

    继续在控制台输入:

    bx run --hot-gen
    

    这将启动一个本地 HTTP 服务。打开浏览器,在地址栏输入 localhost:5050 或者 127.0.0.1:5050,不出意外你就能看到一个本地网页了。

    --hot-gen 不是必须的,它表示如果有文件被新建或修改,则自动重建,无需再手动执行 bx gen,所以带上它比较方便。

    • 小提示

      • 如果提示你“端口已被占用”一类的错误:
        • 第一种情况是你已经开启了 bx run,直接到浏览器里查看。
        • 第二种情况是其他程序占用了 5050 端口,输入 bx run --port=5051 换用其他端口试试,也可以编辑 _config.toml 文件里的 port 修改。
      • 在下一节,我们将命令保存为一个 .bat 文件,你可以把 run.bat 文件设置为开机自启动

    快捷方式

    在与 bx.exe 同一目录下,新建一个文本文件,重命名为 start_run_1.bat,写入并保存:

    start bx run --site=1 --hot-gen
    

    现在你就可以双击这个文件来启动预览服务,不用再敲命令了。

    完全后台运行

    上面的快捷方式会开启一个 cmd 窗口,如果你嫌它碍事,你可以新建一个 start_run_1.vbs 文件,写入:

    set ws = WScript.CreateObject("WScript.Shell") 
    ws.Run "bx run --site=1 --hot-gen", 0
    

    这时双击这个文件就会在后台启动,看不到窗口,如果你想关闭该进程,要在 Windows 任务管理器中的“后台进程”中找到 bx.exe 并结束它。

    开机自启动

    1. 右键 start_run_1.vbs,创建快捷方式。
    2. 在资源管理器中进入这个目录:C:\Users\你的用户名\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup
    3. 将快捷方式移动到上面的目录中。

    以后开机时就会自动启动这个服务。

    三个命令的详细说明

    • bx new - 新建一篇文章。
    • bx gen - 生成最终用于浏览的网页文件。(generate 的缩写)
    • bx run - 启动一个本地服务器以便预览。

    搜索

    本节也可以跳过,当你文章多到必须使用搜索功能的时候再来看这里。

    如果只搜索标题,使用 Windows 资源管理器自带的搜索就可以。

    对于搜索内容,由于 ripgrep 超快,所以我推荐你下载它,大小只有 1M 多一点。

    32 位 Windows 下载 ripgrep-x.x.x-i686-pc-windows-msvc.zip
    64 位 Windows 下载 ripgrep-x.x.x-x86_64-pc-windows-msvc.zip

    解压后把 rg.exe 文件复制到 bx.exe 同样的目录下,就可以使用 rg -t md xxx 搜索 xxx 了。

    • -t md 表示只搜索 .md 文件,以免各种文件都被搜索,返回的结果太多。
    • 不区分大小写: rg -t md -i xxx
    • 带空格用引号括起来:rg -t md "x x x"
    • 使用正则表达式搜索:rg -t md "[0-9]+"
    • 支持中文。

    开始你的写作之旅

    对于不了解 Markdown 的人,可以看我写的 Markdown 简明教程,最常用的也就是:标题、列表、超链接、图片这四个标记,很简单。

    对于 Markdown 老手,Beex 使用 CommonMark 方言,外加支持 TODO 列表。如果你需要输出数学公式或流程图等,可以在主题中集成 JavaScript 解析库来实现。

    希望你喜欢。