包简介

A static site generator written in PHP using Blade templates and markdown

README 文档

README

A static site generator written in PHP using Blade templates and Markdown.

Getting started

Installation

Caxton is available through Composer:

composer require savvywombat\caxton --dev

Environment and configuration

Caxton looks for a .env file in your project's root directory. The following variables are used (with defaults defined):

BASE_URL (http://localhost) - the base URL for your site
CONTENT_DIR (/content) - the folder where your Blade templates are stored
CACHE_DIR (/cache) - the folder under the build directory where Blade caches are stored
OUTPUT_DIR (/dev) - the folder under the build directory where the final HTML is saved to

You can create different environment configurations, for example .env.prod.

The default environment when building is dev.

Caxton will also look for additional configuration in caxton.json and caxton.{environment}.json. The various options are covered in the relevant sections below.

Building with Caxton

To build a site, you need at least one Blade template in your content directory. Then you can run:

vendor/bin/caxton

To build for specific environment:

vendor/bin/caxton -e prod

The default environment is dev, so any configuration targeting the dev environment will be used.

Assets (styles, scripts and images)

Common assets should be placed in your public directory. These will be copied to the build directory before your templates are built into HTML.

You can also put assets in your content directory alongside your templates to keep related assets and templates together.

Directory structure

Caxton expects the following structure, but can be overridden with environment variables:

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

The content and public paths are configurable as ENV variables in .env files.

The public directory should contain common files like images and stylesheets.

The content directory is where you put your templates that Caxton will use to create your HTML. You can include assets (images, stylesheets, scripts, and so on) alongside your templates. These assets will then be included in the same output directory as the generated HTML.

Authoring

Blade PHP Templates

Caxton uses Laravel's Blade template system. Any files in the content directory that end with .blade.php will be converted into an HTML document with the same name.

Markdown

Caxton also allows the use of Markdown within a Blade template. Files in the content directory that end with .blade.md will be passed through a Markdown parser before being saved as an HTML document.

Caxton supports the default CommonMark syntax using the PHP League's package, with one exception. The indentation syntax to format code blocks has been disabled, meaning code blocks must be wrapped in ``` delimiters.

Front Matter

Caxton supports front matter YAML at the start of any template file (PHP or Markdown). The values in the front matter are injected as view data, becoming available as PHP variables within the template.

Example

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>

Indexes (file collections)

Generated files can be collected into an index by specification in the template's front matter:

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

This allows you to refer to a Laravel Collection for generating lists:

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

Sorting

While you can use the Collection's sortBy method, this can be a bit verbose with Caxton pages:

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

You can define a default sort order in your caxton.json file:

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

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

Paged indexes

Coming soon.

Building

vendor/bin/caxton

The default output directory is /project/dir/public/dev, but can be overridden via the environment switch:

vendor/bin/caxton -e prod

Caxton will first copy the contents of the public directory to the build output directory. It will then copy any asset files from the content directory, as well as build the HTML files from the templates there.

Files and directories that begin with a . or _ will not be ignored.

Include/exclude list

You can specify files for inclusion or exclusion in the caxton.json configuration file. File paths are relative to the working directory.

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

Output mapping

By default, the output URLs will follow the same structure as the folder paths within your public and content directories.

If you like to organise your files differently, then you can use the output.maps configuration to map the URLs accordingly.

For example:

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

To output this document as /blog/2018-10-22/it-begins, you can use this in your caxton.json file:

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

date and slug are read from the front matter of the template file.

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

Caxton will then store an internal map for all output for paths starting with /blog/2018/10-22-it-begins/ and rewrite them as /blog/2018-10-22/it-begins. This means that any resources related to the blog post (such as the png file) will be written to the same output URL.

Sitemap

Caxton will generate a sitemap.xml and add it to the root of your output directory. Only HTML files will be included, and the last modified time will be calculated based on the source/template file.

Publishing

Caxton simply builds a directory of content that can be published. How you publish your content is up to you.

Why is this package called Caxton?

William Caxton is thought to be the person who introduced the printing press to England, and so ushered in a great advance in the production of books and dispersal of knowledge.

Acknowledgements

This package uses Laravel's Blade template engine, without requiring the full Laravel framework.

Matt Stauffer has a GitHub repository which has various examples of how to use parts of the framework as standalone components. Specifically, the view component enables the use of Blade.

savvywombat/caxton 适用场景与选型建议

savvywombat/caxton 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 3 次下载、GitHub Stars 达 2，最近一次更新时间为 2023 年 08 月 06 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「php」「template」「markdown」「blade」「static site generator」「static site builder」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 savvywombat/caxton 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 savvywombat/caxton 我们能提供哪些服务？

定制开发 / 二次开发

基于 savvywombat/caxton 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 savvywombat/caxton 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

dg/texy 159

Texy converts plain text in easy to read Texy syntax into structurally valid (X)HTML. It supports adding of images, links, nested lists, tables and has full support for CSS. Texy supports hyphenation of long words (which reflects language rules), clickable emails and URL (emails are obfuscated again

litalino/flarum-more-bbcode 2

Adds more BBCode

gurubob/ascii-table 2

Simple ASCII output of array data

e2es/blade 0

E2E Studios PHP Framework adaptation of leafsphp/blade package

ins0/github-changelog-generator 14

Creates a markdown changelog for your GitHub repository.

varunsridharan/wp2github-md 0

Lightweight Application To Convert WordPress Readme Into Github Markdown

savvywombat/caxton

包简介

关键字：