README

这是一个创建美观、可自定义文档站点的起始模板，只需做很少的修改即可使用。你只需更改一些设置，就可以开始使用。

预览文档模板。

安装

安装 Jigsaw 后，从您的项目目录中运行以下命令

./vendor/bin/jigsaw init jigsawboxes/simple-docs-template

此起始模板包括常见页面类型的示例，并预先配置了以下内容

• 一个完全响应式的导航栏
• 侧边栏导航菜单
• Tailwind CSS，一个允许您不修改任何 CSS 代码即可自定义设计的实用 CSS 框架
• Purgecss 用于从您的 CSS 中删除未使用的选择器，从而生成更小的 CSS 文件
• 使用 highlight.js 进行语法高亮
• 一个自动生成 sitemap.xml 文件的脚本
• 由 Algolia DocSearch 提供的搜索栏，以及如何开始使用他们的免费索引服务的说明
• 自定义 404 页面

配置您的网站

与所有 Jigsaw 网站一样，配置设置可以在 config.php 中找到；您可以在该文件中更新变量以设置特定于您的项目。您还可以添加新的配置变量以在您的网站上使用；请参阅 Jigsaw 文档 了解更多。

// config.php
return [
    'baseUrl' => 'https://my-awesome-jigsaw-site.com/',
    'production' => false,
    'siteName' => 'My Site',
    'siteDescription' => 'Give your documentation a boost with Jigsaw.',
    'docsearchApiKey' => '',
    'docsearchIndexName' => '',
    'navigation' => require_once('navigation.php'),
];

提示：此配置文件也是您定义任何“集合”的地方（例如，您网站的贡献者集合，或博客文章集合）。请参阅官方 Jigsaw 文档 了解更多。

添加内容

您可以使用多种文件类型（例如 文件类型）编写内容。默认情况下，此起始模板期望您的文件位于 source/docs 文件夹中。如果更改此设置，请确保更新 navigation.php 中的 URL 引用。

每个内容页面的第一部分包含一个 YAML 标头，指定了它应该如何渲染。使用 title 属性动态生成每个页面的 HTML title 和 OpenGraph 标签。使用 extends 属性定义此内容文件将使用哪个父 Blade 布局进行渲染（例如，_layouts.documentation 将与 source/_layouts/documentation.blade.php 一起渲染），并且使用 section 属性定义期望将此内容放置其中的 Blade "section"。

---
title: Navigation
description: Building a navigation menu for your site
extends: _layouts.documentation
section: content
---

阅读更多关于 Jigsaw 布局的信息。

添加资产

需要编译的任何资产（如 JavaScript、Less 或 Sass 文件）都可以添加到 source/_assets/ 目录中，当运行 npm run dev 或 npm run prod 时，Laravel Mix 将处理它们。处理后的资产将存储在 /source/assets/build/ 中（注意第二个 assets 目录中没有下划线）。

然后，当Jigsaw构建您的网站时，包含您构建文件（以及您选择存储在该处的任何其他包含静态资源（如图片或字体）的目录）的整个/source/assets/目录将被复制到目标构建文件夹（在您的本地机器上的build_local）。

不需要处理的文件（如图片和字体）可以直接添加到/source/assets/。

有关使用Laravel Mix在Jigsaw中编译资源的更多信息。

构建您的网站

现在您已经编辑了配置变量并了解了如何自定义样式和内容，让我们开始构建网站。

# build static files with Jigsaw
./vendor/bin/jigsaw build

# compile assets with Laravel Mix
# options: dev, prod
npm run dev