hyperf| 快速搜索 hyperf.wiki

平時使用 hyperf wiki 比較多, 一直有一個需求: 怎麼快速搜索?

目前的路徑是: 打開網頁 -> 搜索欄 -> 結果顯示只有側邊欄

hyperf.wiki 生成 dash docset

最近用 dash 比較多, 查文檔還是蠻方便的, 就打算看能不能結合起來

• docsify -> dash docset ? 一番搜索無果, 此路不通
• dash docset 官網 -> Any HTML Documentation, 貌似可以, docsify 的 markdown 文件可以轉爲 html 文件
  • dashing: 基於 go 語言, 看 readme 中 example 的示例, 可以將文件夾下所有 html 文件轉爲 docset
  • dash-docset-builder: 基於 PHP 語言, 看 readme 和 源碼, 這東東是真的牛逼, 可以直接一個 url 把文檔的 html 網站爬完, 真屠龍寶刀 -- 可惜我這就文檔搜索, 折騰爬蟲萬一掉坑裏了...
• markdown -> html, 折騰了不少工具, 悲劇的發現直接 文件夾 -> 文件夾 並不行
  • pandoc: 社區小夥伴推薦, 長長的 readme...
  • gomd: 搜索到的工具, readme 非常簡單, 基本就 一行用法
  • other: 喵了一眼不太「簡單」就 pass 了
• 文件夾 -> 文件夾, 這個就比較簡單了, PHP 畢竟用的很 6, 直接掏出 模板
  • 把模板中的 // file 的部分替換爲業務邏輯即可

// 基於 readdir() 的目錄遞歸訪問文件
function readdir_r($path) {
    $fd = opendir($path);
    while (($f = readdir($fd)) !== false) {
        if ($f == '.' || $f == '..') continue;
        $t = $path . '/' . $f;
        if (is_dir($t)) { // dir
            readdir_r($t);
            continue; // be care
        }
        // file
    }
}

// 基於 scandir() 的目錄遞歸訪問文件
function scandir_r($path) {
    $a = scandir($path);
    foreach ($a as $v) {
        if ($v == '.' || $v == '..') continue;
        $t = "$path/$v";
        if (is_dir($t)) { // dir
            scandir_r($t);
            continue; // be care
        }
        // file
    }
}

• 調試後的完整代碼

$from = '/Users/dayday/hub/hyperf/docs/en';
$to = '/Users/dayday/hub/tmp/docset';

function gomd($from, $to) {
    $a = scandir($from);
    foreach ($a as $v) {
        if ($v == '.' || $v == '..') continue;
        $md = "$from/$v";
        $html = "$to/" . str_replace('.md', '.html', $v);
        if (is_dir($md)) {
            if (!is_dir($html)) mkdir($html);
            gomd($md, $html);
            continue;
        }
        $cmd = "gomd $md -o $html";
        echo "$cmd \n"; // 先調試這裏, OK 了再開 shell_exec()
        shell_exec($cmd);
    }
}
gomd($from, $to);

• 使用 dashing

dashing init # 生成配置文件, 根據 readme 修改, 這裏有知識點: css selector

dashing build # 根據配置文件生成 docset

• dash 中驗證: 遺憾的發現, 並沒有達到要求
  • 中文文檔會亂碼, 打開 chrome 訪問找到問題: charset(字符集) 並沒有使用 utf-8
  • 英文文檔不會有亂碼問題, 但是英文文檔不全
  • 搜索 依賴 索引構建, 上面的 css selector 可以起部分作用, 製作麻煩且離理想狀態甚遠

命令行下搜索其實也還行

平時開發過程中, 其實也經常使用搜索, 主要有 2 類

• 命令行下使用 ag, 不用管那麼多花裏胡哨的, 常用就這幾個

ag xxx # 當前文件夾下遞歸搜索文件內容
ag --html xxx # 限制文件類型
ag -g xxx # 查找文件名

• ag 還可以, 不過多一次 cd 操作, 速度就慢下來了, 當然 cd 也有快捷工具 z-jump

cd xxx # 一波 cd 操作後
z xxx # 會根據使用使用習慣, 跳轉到最常用的目錄, 如果不對, 加個 tab 也能很快找到

• 看起來 ag+z-jump 似乎滿足要求了, 但是命令行下有缺陷: 刷屏 + 快速打開查找到的文件

vscode 的搜索其實很香

仔細一想, vscode 纔是平時搜索體驗拉滿的狀態:

• F1 打開 command 面板, 使用 add folder to workspace, 添加 hyperf/docs/zh-cn (中文版是最全的)
• cmd+p 搜索文件名, 對於熟悉 hyperf.wiki 的我而言, 這個是最常用的方法
• cmd+shift+f 全局搜索, 記憶力也不是一直 有效, 全局搜索+模糊搜索 就可以派上用場, 這裏還有很多相關功能可以使用

寫在最後

• 因爲最近使用 dash 比較多, 典型的 心理誤區+路徑依賴: 手裏拿着錘子, 看啥都是釘子
• 一個新的問題, 不斷調用現有的知識, 能快速判斷所有的分支/選項, 不斷的尋找最優解
• 儘可能多利用「知識」來做決策, 而非「猜」 -- 後者需要花費的時間太不可控, 成功的概率非常低
• 準確和效率往往是一對反義詞, 用生物學來解釋 -- 數萬年的進化讓大腦形成的節能模式 + 身體的非條件反射(條件反射的自己去面壁)

link:

• hyperf wiki
• docsify: 使用 markdown 編寫開發文檔
• dash docset
  • Any HTML Documentation
    • dashing
    • dash-docset-builder
• ag, the_silver_searcher
• z jump