README

使用 PHP 编写，利用 Blade 模板和 Markdown 的静态网站生成器。

入门指南

安装

Caxton 通过 Composer 提供

composer require savvywombat\caxton --dev

环境和配置

Caxton 在您的项目根目录中寻找 .env 文件。以下变量被使用（带有默认值）：

BASE_URL (https://) - 您站点的基准 URL
CONTENT_DIR (/content) - 存储您的 Blade 模板的文件夹
CACHE_DIR (/cache) - 建议目录下存储 Blade 缓存的文件夹
OUTPUT_DIR (/dev) - 建议目录下保存最终 HTML 的文件夹

您可以创建不同的环境配置，例如 .env.prod。

构建时的默认环境是 dev。

Caxton 还会在 caxton.json 和 caxton.{environment}.json 中寻找额外的配置。各种选项在下面的相关部分中介绍。

使用 Caxton 构建

要构建一个网站，您需要在内容目录中至少有一个 Blade 模板。然后您可以运行：

vendor/bin/caxton

为特定环境构建

vendor/bin/caxton -e prod

默认环境是 dev，因此针对 dev 环境的任何配置都将被使用。

资产（样式、脚本和图片）

常见的资产应放在您的公共目录中。这些将在模板转换为 HTML 之前复制到构建目录。

您也可以将资产放入您的模板目录中，与您的模板一起，以保持相关资产和模板在一起。

目录结构

Caxton 期望以下结构，但可以通过环境变量覆盖

/project/dir/content
/project/dir/public

内容路径和公共路径可以在 .env 文件中作为 ENV 变量进行配置。

公共目录应包含如图片和样式表等常见文件。

内容目录是您放置 Caxton 将用于创建您的 HTML 的模板的地方。您可以在模板旁边包含资产（图片、样式表、脚本等）。这些资产将随后包含在生成的 HTML 的同一输出目录中。

创作

Blade PHP 模板

Caxton 使用 Laravel 的 Blade 模板系统。任何以 .blade.php 结尾的 content 目录中的文件将被转换为具有相同名称的 HTML 文档。

Markdown

Caxton 还允许在 Blade 模板中使用 Markdown。以 .blade.md 结尾的 content 目录中的文件将在保存为 HTML 文档之前通过 Markdown 解析器进行处理。

Caxton 支持使用 PHP League 的包的默认 CommonMark 语法，但有例外。代码块格式化的缩进语法已被禁用，这意味着代码块必须用 ``` 分隔符包裹。

前端内容

Caxton 支持在任何模板文件（PHP 或 Markdown）的开始处使用 YAML 前端内容。前端内容中的值作为视图数据注入，在模板中作为 PHP 变量可用。

示例

index.blade.php

---
title: Example document
---

@extends('_layouts.html')

@section('content')
  <p>Hello World</p>
@endsection

about.blade.md

---
title: About Markdown
---

@extends('_layouts.html')

@section('content')

This is Markdown.

@endsection

_layouts/html.blade.php

<html lang="en">
<head>
    <title>{{ $title }}</title>
</head>
<body>
    @yield('section')
</body>

索引（文件集合）

可以通过在模板的前端内容中指定来将生成的文件收集到索引中。

---
index: blog
date: 2023-08-26
title: Some blog post
description: This is really interesting
---

这允许您引用一个用于生成列表的 Laravel 集合

<ul class="index">
    @foreach ($site->index('blog')->slice(0, 3) as $post)
        <li>
            <a href="{{ $post->url() }}">{{ $post->data('title') }}</a>
            
            <p class="date">{{ $post->data('date') }}</p>
            
            <p>
                {{ $post->data('description') }}
            </p>
        </li>
    @endforeach
</ul>

排序

虽然您可以使用 Collection 的 sortBy 方法，但与 Caxton 页面一起使用时可能会有些冗长

@foreach ($site->index('blog')->sortByDesc(fn($post) => $post->data('date')) as $post)

您可以在 caxton.json 文件中定义默认排序顺序

{
  "output": {
    "index": {
      "blog": ["date", "desc"],
      "another": "title"
    }
  }
}

@foreach ($site->index('blog') as $page)

分页索引

即将推出。

构建

vendor/bin/caxton

默认输出目录为 /project/dir/public/dev，但可以通过环境变量覆盖

vendor/bin/caxton -e prod

Caxton 首先将 public 目录的内容复制到构建输出目录。然后，它将复制 content 目录中的任何资产文件，并从模板中构建 HTML 文件。

以 . 或 _ 开头的文件和目录不会被忽略。

包含/排除列表

您可以在 caxton.json 配置文件中指定要包含或排除的文件。文件路径相对于工作目录。

{
  "files": {
    "include": [
      "public/_redirects"
    ],
    "exclude": [
      "content/never-include-this-file"
    ],
  }
}

输出映射

默认情况下，输出 URL 将遵循您公共和内容目录内文件夹路径的相同结构。

如果您想以不同的方式组织文件，则可以使用 output.maps 配置来相应地映射 URL。

例如

+ content
|-+ blog
  |-+ 2018
    |-+ 10-22-it-begins
      |-- index.blade.md
      |-- pretty-picture.png

要将此文档输出为 /blog/2018-10-22/it-begins，您可以在您的 caxton.json 文件中使用此配置

{
  "output": {
    "maps": [
      {
        "path": "/blog/*/*/",
        "url": "/blog/{{ date }}/{{ slug }}/"
      }
    ]
  }
}

date 和 slug 将从模板文件的元数据中读取。

---
date: 2018-10-22
slug: it-begins
---

Caxton 将存储一个内部映射，用于所有以 /blog/2018/10-22-it-begins/ 开头的输出路径，并将它们重写为 /blog/2018-10-22/it-begins。这意味着与博客文章相关的任何资源（如 png 文件）都将写入相同的输出 URL。

发布

Caxton 简单地构建一个可发布的目录。如何发布您的内容由您决定。

为什么这个包叫做 Caxton？

威廉·卡克斯顿被认为是将印刷机引入英格兰的人，从而为书籍的生产和知识的传播带来了巨大的进步。

致谢

此包使用 Laravel 的 Blade 模板引擎，无需完整的 Laravel 框架。

Matt Stauffer 有一个 GitHub 仓库，其中包含如何作为独立组件使用框架各个部分的多个示例。具体来说，视图组件允许使用 Blade。

savvywombat / caxton

维护者

详细信息