首页 » Web技术 » Laravel » 正文

Katana – 支持 Markdown 语法的 PHP 静态站点/博客生成器

目前已经有好几种静态站点生成器,如 Hexo、Jekyll等,今天发现一款使用 PHP 语法的静态博客生成器,支持 Markdown 语法,并且使用的是 Laravel 的 Blade 模版引擎。

katana

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-name

php 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 指令,你可以这么使用它:

<h2>Regular HTML heading</h2>

@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')
    <h2>@yield('post::title')</h2>
    <small>@yield('post::date')</small>

    Post content here.
@stop

post:: 开头的 Section 会添加到叫做 $blogPosts 的全局变量中,这个变量可以在所有的视图中使用,并且它包含了文章对象的数组。

你可以使用这个变量来循环输出所有的博客文章:

@foreach($blogPosts as $blogPost)
    <li>
        <a href="{{ $blogPost->path }}">
            {{ $blogPost->title }} at {{ $blogPost->date }}
        </a>
    </li>
@endforeach

path 属性是 Katana 自动添加的,它保存的是文章的相对 URL。

4.2 博客文章分页

Katana 分页显示博客的文章,你需要先在 config.php 中设置 postsPerPagepostsListView 配置项。浏览一下配置文件就会知道每一个配置项是做什么用的。

在分页视图中,$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 --all

git 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 地址

发表评论