README

Laravel Commonmark Blog

Laravel Commonmark Blog是一种Laravel的静态网站生成器。它是一个基于文件系统、SEO优化的简单结构博客，使用Commonmark和Laravel SEO。

目标与主要概念

本包的目标是在保持内容位于根域名下（例如project.com/blog而不是blog.project.com）的同时，将博客内容与应用程序分离。这在SEO方面是首选的。

通过避免渲染和通过框架传递内容，实现了最佳性能。框架最初用于准备和渲染博客内容。渲染的文件直接写入到public/目录，以避免触及应用程序。假设服务器配置正确，博客可以达到（近似）静态网站的性能水平。

为每个文件，创建一个包含index.htm的目录以避免额外的服务器配置。例如，文件blog/my-article.md将存储为blog/my-article/index.htm。大多数Web服务器已经配置好了直接服务这些文件。

关注SEO，CommonMark是合理的选择：它高度可扩展，允许进行任何可能的定制以实现排名。还有一个示例存储库演示了博客。

核心功能

• 支持文章和文章列表页面。示例存储库显示了如何实现。

• CommonMark：PHP CommonMark以支持可扩展性。默认情况下，所有.md文件都转换为HTML文件。HTML文件存储在public/目录中。其他文件扩展名，如.markdown，将被忽略，但会复制过来。

• Frontmatter可以在config/blog.php中定义全局默认值，并在每篇文章的基础上定义。

• 资产（如视频、图像等）以及其他任何文件都会以1:1的方式复制。

• 生成的文章的信息可以可选地存储在缓存中。这允许根据实际发布的文章和列表页面动态地向侧边栏、页脚等添加元素。

• 自动内容禁令：未来发布日期（published）的文章将被忽略，直到日期过去。注意：手动添加的链接不会进行检查，并将默认包含。

• 部分内容禁令：一旦修改日期过去，以*.emb.md结尾的文件将替换原始文件（例如，没有.1.emb.md）。

• hreflang：使用hreflang方式可以构建多语言网站。

  可以将一个包含替代语言URL的数组添加到frontmatter中，它将被转换为hreflang标签。

  x-default将设置为配置文件中定义的区域设置。

  在文章头部中的 locale 将在渲染模板之前被设置到应用中。

SEO增强

包含或通过扩展轻松配置的SEO改进。

• 从文章头部或全局设置元标签、Twitter Card和Facebook Open-Graph。
• 为图片添加懒加载属性（通过扩展可选）。
• 为根域名、子域名和外部链接定义全局的rel属性（通过扩展可选）。

SEO改进通常是默认启用的，或者可以通过配置文件进行配置。

计划/考虑的SEO相关增强

以下扩展/改进被考虑用于博客包。

• 图像优化，
• 使用 Spatie/schema-org 的 Schema.org条目。

如何使用此包

以下是如何使用博客包的示例。

如何添加文章

任何博客页面都遵循一个简单的结构，使用Frontmatter & Commonmark。YAML Frontmatter用于定义标题、社交分享图片等文章级别的信息，接着是CommonMark内容。

---
title: "The Love of Code"
description: "Why I love to code."
image: "/images/code.jpg"
---

# The Love Of Code

....

默认值可以在配置文件的defaults下设置。如果您不确定要包含哪些标题，请参考joshbuchea/HEAD。

如何添加文章列表页面

通过在目录中添加名为index.md的文件来创建列表页面。这样，渲染方法会传入以下参数

• 完整的头部（当前列表页的头部与config/blog.php中的defaults合并），
• 列表页面的CommonMark渲染内容作为$content，
• $total_pages作为页数，
• $current_page为页面编号，
• $base_url为分页页面的URL，以及
• $articles为文章。

有了这些信息，您的Blade文件应该能够渲染完整的文章列表页面。除了编号的页面文件，还添加了一个index文件，允许没有页面编号的“根”页面。以下示例解释了这一点。

如果需要创建三个带有文章的列表页面，则将创建以下文件

domain.com/blog/index.htm
domain.com/blog/1.htm
domain.com/blog/2.htm
domain.com/blog/3.htm

大多数Web服务器将以以下方式提供服务

domain.com/blog
domain.com/blog/1
domain.com/blog/2
domain.com/blog/3

注意

• 默认情况下，文章也包括在嵌套目录下。
• 所有页面将自动根据页面编号接收一个规范URL。
• 第一页（此处为/blog/1）是index.htm的副本，允许通过编号访问。它自动包含一个指向不带页面编号的变体的规范URL（此处为/blog）。

支持hreflang的多语言博客

博客模块支持使用hreflang的多语言博客。每篇文章的语言版本都将生活在单独的markdown文件中，并使用hreflang进行交叉引用。

英文文章

---
title: "The Love of Code"
description: "Why I love to code."
canonical: "/the-love-of-code/"

locale: "en"
hreflang:
    de: "/de/die-liebe-zum-programmieren/"
---

# The Love Of Code

....

德语文章

---
title: "Die Liebe zum Programmieren"
description: "Warum ich Programmieren liebe."
canonical: "/de/die-liebe-zum-programmieren/"

locale: "de"
hreflang:
    en: "/the-love-of-code/"
---

# Die Liebe zum Programmieren

....

请注意：目前不考虑封存（延迟发布）。您需要手动确保您的网站不引用尚未发布的文章。

要求 & 安装

要求

• PHP 7.4或更高版本
• Laravel 8.75或更高版本
• Web服务器提供index.htm文件（Nginx的默认设置）

安装

此包使用composer分发。如果您没有使用composer，您可能已经知道如何安装一个包。以下是基于composer的安装步骤

composer require spekulatius/laravel-commonmark-blog

接下来，发布配置文件

php artisan vendor:publish --provider="Spekulatius\LaravelCommonmarkBlog\CommonmarkBlogServiceProvider" --tag="blog-config"

根据需要审查、扩展和调整config/blog.php中的配置。所需的最小值是BLOG_SOURCE_PATH和一些默认的前置信息。

添加Commonmark扩展

您可以在配置文件的extensions下添加Commonmark扩展。

'extensions' => [
    new \SimonVomEyser\CommonMarkExtension\LazyImageExtension(),
],

在安装扩展之前，确保运行所需的composer安装命令。通常情况下，不需要默认安装包。

在配置文件 config/blog.php 中，您可以在 config 目录下为扩展添加额外的配置。

用法：博客文章的渲染

博客的构建是通过一个 Artisan 命令完成的

php artisan blog:build

您可以可选地传递一些参数，查看 php artisan help blog:build 获取详细信息。

通常，这一步骤会作为部署过程的一部分被触发。您可以设置两个仓库（一个用于您的项目，一个用于您的博客），并让两个仓库按需触发构建。

您还可以在 app/Console/Kernel.php 中安排命令，以确保定期更新。

提示：确保在每次构建后更新您的 sitemap.xml。

当然，您将博客集成到项目中的方式取决于部署工具和流程。

贡献 & 许可

请参阅 CONTRIBUTING 获取详细信息。

在MIT许可下发布。请参阅 许可文件 获取更多信息。