avatar

大兜

右手寫程式,左手寫音樂

將 Octopress Page 依照標題自動索引

用法懶人包

  1. 下載 Indexer for Octopress
  2. indexer.rb 複製到 plugins 目錄下。
  3. 新增 source\_includes\custom\asides\indexer.html

    {% if page.indexer == true %}
      <section>
      <h1>Catalog</h1>
      {{ page.indexer_aside }}
      </section>
    {% else %}
      {% if site.page_asides.size %}
        {% include_array default_asides %}
      {% endif %}
    {% endif %}
    
  4. 編輯 _config.yml

    # Each layout uses the default asides, but they can have their own asides instead. Simply uncomment the lines below
    # and add an array with the asides you want to use.
    # blog_index_asides:
    # post_asides:
    page_asides: [custom/asides/indexer.html] # 加上這個
    
  5. 完成!之後只要在你需要索引的 page 上方 YAML 區塊加上 indexer: true,右方欄位就會自己索引了。

為什麼有這種需求?

有想過用 Octopress 寫說明文件,雖然用 Markdown 可以很方便的杜撰,但文章只要一長了,要找標題特定的內容不用滑鼠滾輪一個一個找,就得用搜尋的,而且無法一次觀看到整篇文章的大綱。這時候最適合用索引來解決這個問題,而索引的優點之多,我想有寫過教學文件或是 wiki 的人應該是最清楚不過了。

但是 Octopress 如果要做到這樣,你要嘛用 Textile 取代 Mardown,如果用 Markdown 就還要徒手寫 tag,例如:

<h2 id="getting-start">起步走</h2>

這會讓寫作的爽度降低。

但有人可能會說改用 Textile 就好了,確實,但麻煩的在後面:就算你用 Textile 好了,你還得為你的文件特地寫一個 aside,裡面有個兩層的 list,每個標題都有 <a> 包起來,還得自己寫 href="#xxx"

這更讓寫作的爽度降到冰點。

好吧,萬一你是個很有耐心的人,你確實的在文章的 heading 都加上了 ID,且也自己寫了一個 asides 放在 source\_includes\custom\asides\ 之下。但當你要設定 _config.yml 時發現:

page_asides: [custom/asides/xxx.html]

原來 page asides 是全局的,意思是接下來要處理的問題:你要怎麼在不影響其他的 page 的情況下,在特定 page 顯示特定 page?

這時候我就期望尋求一個方法,讓寫作只要專心在 heading 的編排就好,不用理會索引這樣瑣碎的工作。

你寫這個幹麼?

當然是為了解決自己問題(但也有可能同時是別人的問題)。

因為翻譯 Rails Guide 的關係,這幾天常常光顧 docrails,以及 Rails 的倉庫。對 Rilas Guide 生成文件的方式感到好奇,以 Getting Start with Rails 這篇為例吧,右方的索引全部對應到左方的 h3 和 h4,也就是如果有個 heading 長這樣:

<h3 id="guide-assumptions">1 Guide Assumptions</h3>

那麼右方所有就會有對應的

<li>[Guide Assumptions](#guide-assumptions)</li>

但實際上,在 Textile 文件中 他們實際是這樣寫的:

h3. Guide Assumptions

研究了他們的原始碼,發現 Rails Guide 的 generator 在 render 之前做了這兩件事情:

  1. 將所有的 heading 賦予同名 id。

    也就是將 h3. Guide Assumptions 替換成 h3(#guide-assumptions). Guide Assumptions

  2. 遞迴的方式產生清單。

    可以分析 <h3> 下的 <h4>,做出最多兩層的索引清單放在右方。

我馬上想到的一件事情就是,這功能可以用在 Octopress 上。