Fornax 0.15.1

Fornax

Fornax 是一个使用类型安全的 F# DSL 定义页面布局的 可脚本化静态网站生成器。

Fornax 是 Ionide 工具套件的一部分 - 您可以在 Open Collective 上支持其开发。

工作功能

• 使用 .fsx 文件创建自定义数据加载器，这意味着您可以使用任何想象得到的内容作为您站点的数据源，而不仅仅是预定义的 .md 或 .yml 文件。
• 使用 .fsx 文件创建自定义生成器，这意味着您可以生成任何类型的输出。
• 使用 .fsx 文件进行动态配置。
• 监视模式，在您更改数据或任何脚本文件时随时重新构建您的页面。

安装

Fornax 作为全局 .Net Core 工具发布。您可以使用 dotnet tool install fornax -g 安装它。

CLI 应用程序

Fornax 的主要功能来自 CLI 应用程序，它允许用户搭建和生成网页。

• fornax new - 在当前工作目录中搭建新的博客，使用的是一个非常简单的模板。
• fornax build - 构建网页，将输出放入 _public 文件夹。
• fornax watch - 启动一个小的 Web 服务器，托管您的生成站点，并在检测到任何更改时重新编译站点。这是使用 Fornax 的推荐方式。
• fornax clean - 删除输出目录和任何临时文件。
• fornax version - 打印出当前安装的 Fornax 版本。
• fornax help - 打印出帮助信息。

入门

开始使用 fornax 最简单的方式是运行 fornax new，然后运行 fornax watch - 这将创建一个相当简约的博客站点模板，以侦听模式启动 fornax 并启动一个网页服务器。然后您可以在浏览器中访问 localhost:8080 来查看页面，并使用编辑器修改生成的文件进行编辑。此外，您还可以查看此存储库中的 samples 文件夹 - 它包含一些您可以用于网站的其他 loaders 和 generators。

网站定义

Fornax 使用正常的 F# 代码（F# 脚本文件）来定义其任何核心概念：loaders、generators 和 config。

SiteContents

SiteContents 是一个相当简单的类型，它提供了对 Fornax 可用的任何信息的访问。信息通过使用 loaders 提供，然后可以在 generators 中访问。

SiteContents 在其公共 API 中有多个函数

type A = {a: string}
type B = {b: int; c: int}

let sc = SiteContents()
sc.Add({a = "test"})
sc.Add({a = "test2"})
sc.Add({a = "test3"})

sc.Add({b = 1; c = 3}) //You can add objects of different types, `Add` method is generic.

let as = sc.TryGetValues<A>() //This will return an option of sequence of all added elements for a given type - in this case it will be 3 elements
let b = sc.TryGetValue<B>() //This will return an option of element for given type

Loaders

Loader 是一个负责在生成上下文中加载外部数据的 F# 脚本。数据通常包括类似 .md 文件的内容、一些全局网站配置等，但由于这些都是正常的 F# 函数，您可以执行任何需要做的操作。想要从本地数据库或互联网加载数据？当然可以，为什么不行。想要使用 World Bank 类型提供者 包含一些世界银行的统计数据？这也是可能的 - 您可以在 loader 中使用任何依赖项，就像在正常的 F# 脚本中一样。

Loaders 是正常的 F# 函数，它们接受 SiteContents 作为输入，并接受页面根的绝对路径，然后返回 SiteContents

#r "../_lib/Fornax.Core.dll"

type Page = {
    title: string
    link: string
}

let loader (projectRoot: string) (siteContent: SiteContents) =
    siteContent.Add({title = "Home"; link = "/"})
    siteContent.Add({title = "About"; link = "/about.html"})
    siteContent.Add({title = "Contact"; link = "/contact.html"})

    siteContent

重要说明：您可以（并且可能应该）定义多个加载器 - 它们将在站点生成之前执行，并将信息传播到 SiteContents

Generators

Generator 是一个负责生成 Fornax 处理输出的 F# 脚本。这通常是 .html 文件，但可以是任何其他内容 - 实际上，generator API 只要求返回一个 string，该字符串将被保存到文件中。生成器再次是普通的 F# 函数，作为输入接受 SiteContents、页面根的绝对路径、当前处理的文件的相对路径（对于全局生成器可能为空）并返回 string

#r "../_lib/Fornax.Core.dll"
#if !FORNAX
#load "../loaders/postloader.fsx"
#endif

open Html

let generate' (ctx : SiteContents) (_: string) =
    let posts = ctx.TryGetValues<Postloader.Post> () |> Option.defaultValue Seq.empty

    let psts =
        posts
        |> Seq.toList
        |> List.map (fun p -> span [] [!! p.link] )

    html [] [
        div [] psts
    ]

let generate (ctx : SiteContents) (projectRoot: string) (page: string) =
    generate' ctx page
    |> HtmlElement.ToString

重要说明：您可以（并且可能应该）定义多个生成器 - 它们将生成不同类型的页面和/或内容，如 post、index、about、rss 等。

配置

Configuration 是一个定义何时运行哪些分析器以及如何保存其输出的 F# 脚本文件。必须将 Config.fsx 文件放在网站项目根目录中（您运行 fornax CLI 工具的地方）。

#r "../_lib/Fornax.Core.dll"

open Config
open System.IO

let postPredicate (projectRoot: string, page: string) =
    let fileName = Path.Combine(projectRoot,page)
    let ext = Path.GetExtension page
    if ext = ".md" then
        let ctn = File.ReadAllText fileName
        ctn.Contains("layout: post")
    else
        false

let staticPredicate (projectRoot: string, page: string) =
    let ext = Path.GetExtension page
    if page.Contains "_public" ||
       page.Contains "_bin" ||
       page.Contains "_lib" ||
       page.Contains "_data" ||
       page.Contains "_settings" ||
       page.Contains "_config.yml" ||
       page.Contains ".sass-cache" ||
       page.Contains ".git" ||
       page.Contains ".ionide" ||
       ext = ".fsx"
    then
        false
    else
        true

let config = {
    Generators = [
        {Script = "less.fsx"; Trigger = OnFileExt ".less"; OutputFile = ChangeExtension "css" }
        {Script = "sass.fsx"; Trigger = OnFileExt ".scss"; OutputFile = ChangeExtension "css" }
        {Script = "post.fsx"; Trigger = OnFilePredicate postPredicate; OutputFile = ChangeExtension "html" }
        {Script = "staticfile.fsx"; Trigger = OnFilePredicate staticPredicate; OutputFile = SameFileName }
        {Script = "index.fsx"; Trigger = Once; OutputFile = NewFileName "index.html" }

    ]
}

可能的生成器触发器

• Once：全局运行一次。
• OnFile filename：针对给定文件运行一次。
• OnFileExt extension：对具有给定扩展名的每个文件运行一次。
• OnFilePredicate predicate：对满足谓词的每个文件运行一次 (string -> string)。

可能的生成器输出

• SameFileName：输出文件的名称与输入文件相同。
• ChangeExtension newExtension：输出文件名与输入文件相同，但扩展名更改为 newExtension。
• NewFileName newFileName：输出文件名为 newFileName。
• Custom mapper：输出文件名为将映射器应用于输入文件名的结果。
• MultipleFiles mapper：输出多个文件，这些文件的名称是将映射器应用于生成器输出的第一个字符串的结果。

注意：对于MultipleFiles，generate函数必须输出一个list。

如何贡献

模仿者综合症免责声明：我需要你的帮助，真的。

可能会有一个小声音告诉你你还没有准备好；你需要完成一个教程，学习另一个框架，或写几篇博客，才能帮助我完成这个项目。

我可以保证，情况并非如此。

该项目有一些明确的贡献指南和期望，你可以在这里阅读。

贡献指南概述了您需要遵循的流程以将补丁合并。通过明确期望和过程，我希望这将使您更容易贡献。

你不仅仅可以编写代码。你也可以通过编写文档、编写测试，甚至通过对这个工作的反馈来提供帮助。（是的，这包括对贡献指南的反馈。）

感谢您的贡献！

构建过程

• 你需要.NET 6.0 SDK
• 运行dotnet tool restore以还原在.config/dotnet-tools.json中定义的.NET 6本地工具。
• 要构建项目，请运行dotnet run（这会运行包含FAKE构建管道的build.fsproj项目。）
• 要运行单元测试，请运行dotnet run Test

贡献和版权

该项目托管在GitHub上，您可以在那里报告问题、分叉项目并提交拉取请求。请阅读贡献指南

该库在MIT许可下可用，允许商业和非商业目的的修改和分发。

请注意，该项目附带了一份贡献者行为准则。通过参与此项目，你同意遵守其条款。