template - SilverBlog/silverblog GitHub Wiki

模板製作簡介

綜述

SilverBlog 採用了 Jinja2 模板引擎來渲染頁面。關於 Jinja 的模板語言，可以通過查閱 Jinja 的文檔來了解，本知識庫僅介紹與 SilverBlog 模板有關的特定內容。

SilverBlog 的模板其實非常容易製作，只要提前寫好 HTML，套用對應的模板標記語言，一個 SilverBlog 模板就製作完成了。

入口

在製作模版時，你只需要考慮兩個入口：

  • index.html：博客的首頁（文章列表）
  • post.html：博客的文章頁

其餘的頁面部分（頭部和尾部等），均可使用 include 語句自由引用，但是路徑前面務必要包含 system_config.Theme。

{# 引用了主題根目錄的 /include/header.html #}
{% include system_config.Theme+"/include/header.html" %}

通用參數

為了便於開發模板，SilverBlog 會傳輸一些參數給模板引擎，這些可用的參數有：

變量名稱 用途 來源 適用範圍
system_config{} SilverBlog 配置項目 config/system.json 全局
template_config{} 主題配置項目 templates/你的主題名稱/config.json 全局
menu_list[] 菜單列表 config/menu.json 全局
template_config{} 主題配置項目 templates/你的主題名稱/config.json 全局
page_list[] 文章列表（已分頁的） config/page.json（分頁後的列表） index
now_page 當前頁數 程序 index
page_row 總計頁數 程序 index
page_info{} 當前文章詳情 config/page.json（單一列表項） post
content 當前文章內容 document/當前文章.md post

用戶自定義頭部和尾部

用戶可能需要在主題的頭部和尾部插入一些自定義代碼（網站統計、網頁特效、挂件等），那麼在開發主題時需要在合適的位置進行引用。

{# 用戶自定義頭部 HTML，建議放於 </head> 之前 #}
{% include "include/head.html" ignore missing %}
{# 用戶自定義尾部 HTML，建議放於 </body> 之前 #}
{% include "include/foot.html" ignore missing %}

同樣是include 語句，但是與主題內其它頁面部分的引用不同，這裡多了ignore missing 參數，因為自定義頭部和尾部作為一項可選配置，應該在引用時考慮到它們不存在的情況。

i18n 實現

您可以將配置檔放至於主題目錄下的i18n目錄下。SilverBlog採用 Market Codes 作為 i18n 的json文件命名標準。默認配置檔為 en-US。（system.json中未配置時）當無法找到en-US檔的時，將返回鍵名。

您可以使用 {{i18n|get_i18n_value("")}} 來獲取鍵值。i18n是一個傳入的字典變量。

常見用例

輸出頁面標題和介紹

{# 針對不同頁面輸出適合它們的標題和介紹，這樣就可以安心的把整個網站的 header 寫在一個單一的文件內 #}
{% if page_info.title=="index" %}
    {% set title=system_config.Project_Name %}
    {% set description=system_config.Project_Description %}
{% else %}
    {% set title=page_info.title %}
    {% set description=page_info.excerpt %}
{% endif %}
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>{{ title }}</title>
    <meta name="description" content="{{ description }}">
    {% include "include/head.html" ignore missing %}
</head>

輸出本頁文章列表

{# 對本頁每一篇文章信息進行渲染 #}
{% for page_info in page_list %}
<article>
    {# 輸出單項的標題 #}
    <h1 class="title">
        <a href="/post/{{ page_info.name }}">{{ page_info.title }}</a>
    </h1>
    {# 輸出單項的時間 #}
    <time data-date="{{ page_info.time }}">{{ page_info.time }}</time>
    {# 輸出單項的文章摘要 #}
    <div class="content">{{ page_info.excerpt }}</div>
</article>
{% endfor %}

輸出導航菜單

<ul>
    {% for item in menu_list %}
        {% if "absolute" in item %}
            {% set url = item.absolute %}
        {% else %}
            {% set url = "/post/"+item.name %}
        {% endif %}
        <li><a href="{{url}}">{{ item.title }}</a></li>
    {% endfor %}
</ul>

輸出頁碼

<nav class="pagination" role="navigation">
    {% if now_page !=1 %}
        <a class="newer-posts"
           href="/index/{{ now_page - 1 }}">&larr;
            上一頁</a> {% endif %}
    <span class="page-number">第 {{ now_page }} 頁 ⁄ 共 {{ page_row }} 頁</span>
    {% if now_page != page_row and page_row != 1 %}
        <a class="older-posts"
           href="/index/{{ now_page + 1 }}">下一頁 &rarr;</a> {% endif %}
</nav>

輸出文章

<article>
    <h1 class="title">{{ page_info.title }}</h1>
    <time>{{ page_info.time }}</time>
    <div class="content">{{ content|safe }}</div>
    <section class="comment">{% include "include/comment.html" ignore missing %}</section>
</article>

輸出版權信息

<footer>
    <div class="wrap clearfix">
        <span class="left">© {{ now_time|format_datetime("%Y") }} <a href="/">{{ system_config.Project_Name }}</a></span>
        <span class="right">Powered by <a href="http://github.com/SilverBlogTeam/SilverBlog" target="_blank">SilverBlog</a></span>
    </div>
</footer>

加入 SilverBlogTheme 組織的主題要求

  • 符合W3C標準，能夠在 FireFox 上正常運行。
  • 引入Bplayer或者能夠兼容Bplayer標準之音樂播放器(可以選擇不引入，使用瀏覽器默認播放器。請確保播放器在無法載入資源文件時能夠使用。)
  • 符合SilverBlog主題規範，能夠正確加入用戶自定義載入點的配置。
  • SPA主題將不予以收錄。
⚠️ **GitHub.com Fallback** ⚠️