Katana – 支援 Markdown 文法的 PHP 靜態網站/部落格產生器

目前已經有好幾種靜態網站產生器，如 Hexo、Jekyll等，今天發現一款使用 PHP 文法的靜態部落格產生器，支援 Markdown 文法，並且使用的是 Laravel 的 Blade 模版引擎。

Katana 的主要特點：

• 支援 Markdown 文法
• 快速安裝
• 內建 Pretty URLs
• 簡單的文章分頁
• 支援 Github Pages

一、安裝

安裝 Katana 非常簡單，你只需運行 composer create-project命令：

composer create-project themsaid/katana your-site-name

現在你已經把 Katana 安裝在了 your-site-name目錄下，然後你需要運行下面的命令來產生網站：

cd your-site-namephp katana build

之後會在檔案夾中產生一個 public 目錄，裡面就是產生的靜態檔案。

為 bulid 指定 baseURL

在產生靜態檔案時，可以通過 base_url來指定 baseUrl：

php katana build --base_url=/awesome-site

這樣做的話，當你使用 Blade 的 @url()指令產生連結的時候會產生這樣的 URLs： /awesome-site/about

二、目錄結構

當運行 build命令後，會產生如下的檔案結構：

• content：這是 Katana 尋找你網站內容的地方
• _cache：這是 Blade 儲存編譯完的視圖檔案的地方
• public：Katana 會把產生的靜態檔案儲存在這裡
• config.php：網站配置項

2.1 關於 “content”的目錄結構

這個檔案夾中儲存的是你的 Blade 視圖，靜態檔案（JS、CSS、圖片等）， _blog檔案夾以及 _include檔案夾。

_content檔案夾是儲存你 Blade 布局和基本視圖的地方，Katana 不會為這些檔案產生可訪問的頁面。

_blog檔案夾是存放部落格內容的地方。

2.2 關於 config.php

這個檔案包含了 Katana 在產生靜態檔案是需要的一些預先定義的機碼，每一個配置項都有詳細的說明，解釋它們是用來做什麼的。

你也可以在這個檔案中定義任何變數，之後可以在網站的任何視圖中調用該變數。

三、Blade 模版

如果你還不熟悉 Blade 模版的話，下面這段話是來自 Laravel 網站對它的介紹：

Blade 是一個由 Laravel 提供的簡單但功能強大的模版引擎。同其他主流的 PHP 模版引擎不同的是，Blade 並不限制你在視圖中使用純 PHP 代碼。

建議你到這裡讀一下 Blade 的文檔。

3.1 在 Blade 中使用 Markdown 文法

Katana 為 Blade 添加了一個 @markdown指令，你可以這麼使用它：

Regular HTML heading
@markdown    This is some **Markdown** content.@endmarkdown

3.2 產生 URLs

Katana 使用 Blade 的 @url()指令為頁面和靜態檔案產生 URLs，這些 URLs 會基於運行 build時指定的 base_url參數：

@('/')                // Outputs '/'@('about')            // Outputs '/about'@('assets/style.js')  // Outputs '/assets/style.js'

四、部落格產生器

使用 Katana 來產生部落格非常簡單，你只需在 /content/_blog檔案夾總建立一個檔案，並遵循下面格式命名：

2016-03-03-my-post-slug.blade.php

檔案名稱前的日期是用來在檔案系統中對檔案進行排序的，同時還用來產生部落格的 URL，上面的檔案會產生下面的 URL：

blog.com/my-post-slug-20160303

4.1 部落格文章中的變數

部落格的視圖看起來應該是下面這樣：

@section('post::title', 'Stop Trying To Be Somebody')@section('post::date', 'February 28, 2016')@section('post_body')    
@yield('post::title')
    @yield('post::date')    Post content here.@stop

以 post::開頭的 Section 會添加到叫做 $blogPosts的全域變數中，這個變數可以在所有的視圖中使用，並且它包含了文章對象的數組。

你可以使用這個變數來迴圈輸出所有的部落格文章：

@foreach($blogPosts as $blogPost)    
        path }}">            {{ $blogPost->title }} at {{ $blogPost->date }}            
@endforeach

path屬性是 Katana 自動添加的，它儲存的是文章的相對 URL。

4.2 部落格文章分頁

Katana 分頁顯示部落格的文章，你需要先在 config.php中設定 postsPerPage和 postsListView配置項。瀏覽一下設定檔就會知道每一個配置項是做什麼用的。

在分頁檢視中， $paginatedBlogPosts變數包含了該頁所有的文章，而 $nextPage和 $previousPage兩個變數分別是後一頁和前一頁的連結。

五、Github Pages

你可以把網站部署到 Github Pages上，其想法是把 public目錄作為你 Github Pages 庫的主分支或者你其他庫的 gh-pages分支。

Step 1：把 Katana 添加到除 master/gh-pages 分支之外的其他分支

我們這裡把這個分支叫做 gh-pages-source，安裝 Kanata 到該分支並按正常的步驟新增內容。

Setp 2：產生網站

當內容準備好之後就可以運行 build產生網站了：

php katana build

如果你不是使用的你的使用者名稱的項目，則需要定義 base_url，如我的 Github 使用者名稱為 9IPHP，但我沒有把 Katana 發布到 9IPHP.github.com 這個項目，而是建立了一個 Katana 的項目，則需要這樣產生網站：

php katana build --base_url=/Katana

Step 3：把檔案 Push 到 Step 1 中建立的分支

首先需要移除 .gitignore檔案中的 public這一行，否則該目錄是提交不上去的，之後運行如下命令：

git add --allgit commit -m 'publishing website'git push origin gh-pages-source

Step 4：把 public 目錄添加到 master/gh-pages 分支

git subtree push --prefix public origin master

或者：

git subtree push --prefix public origin gh-pages

六、總結

建立完成之後就可以到你的 Github Pages 中訪問網站了，可以查看我建立的樣本網站。

項目 Github 地址

